Knowledge & Search

How Pyramid AI answers questions

When you ask a question through the Agent API, the AI doesn’t just make up an answer — it searches your actual documents first, finds the most relevant passages, and then formulates a response grounded in that evidence.

This approach is called Retrieval Augmented Generation (RAG). In plain terms:

1. Retrieval — find the most relevant document sections
2. Augmented — feed those sections to the AI as context
3. Generation — the AI writes an answer based on what it found

Your question
     │
     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Search your   │ ──> │ Feed context  │ ──> │ AI generates  │
│ document      │     │ to the AI     │     │ an answer     │
│ chunks        │     │ model         │     │ with citations│
└──────────────┘     └──────────────┘     └──────────────┘
     │                                           │
     ▼                                           ▼
 "Found 5 relevant                    "Based on Section 3.2
  passages from                        of the Safety Plan..."
  3 documents"

Why this matters

Traditional search finds pages containing your keywords. Pyramid AI understands meaning.

Sources and citations

Every response includes a sources array that tells you exactly where the answer came from:

1
{
2
  "answer": "According to the project safety plan, all workers must wear...",
3
  "sources": [
4
    {
5
      "id": "chunk_abc",
6
      "title": "Safety-Plan-2026.pdf",
7
      "relevance": 0.95
8
    },
9
    {
10
      "id": "chunk_def",
11
      "title": "HK-Building-Regulations.pdf",
12
      "relevance": 0.87
13
    }
14
  ]
15
}

This traceability is critical for compliance — you can always verify the AI’s answer against the original source document.

Three ways to search

Pyramid AI offers three interfaces for querying your knowledge base, each designed for different use cases:

1. Single Query — POST /api/v2/agent/query

Ask one question, get one answer. No conversation history, no session state. The simplest integration point.

Best for: Excel add-ins, automated scripts, one-off lookups, embedding answers in other tools.

1
{
2
  "project_id": "...",
3
  "query": "What is the maximum allowable floor load?"
4
}

2. Chat — POST /api/v2/chat

Multi-turn conversations where the AI remembers what was discussed. Follow-up questions understand context from earlier in the conversation.

Best for: Chatbots, interactive assistants, exploratory research where users drill into a topic.

1
{
2
  "project_id": "...",
3
  "messages": [
4
    { "role": "user", "content": "What are the fire safety requirements?" },
5
    { "role": "assistant", "content": "According to..." },
6
    { "role": "user", "content": "What about for buildings over 30 stories?" }
7
  ]
8
}

The AI understands that “What about for buildings over 30 stories?” refers to fire safety requirements from the previous message.

3. Batch Queries — POST /api/v2/agent/batches

Submit hundreds of questions at once and get them all answered in the background. Results are downloadable as CSV.

Best for: Compliance questionnaires, regulatory checklists, bulk data extraction, audit preparation.

1
{
2
  "project_id": "...",
3
  "name": "Q2 Safety Checklist",
4
  "questions": [
5
    "Is there a fire safety plan?",
6
    "Are emergency exits marked?",
7
    "Is PPE policy documented?",
8
    "..."
9
  ]
10
}

Search scope

The AI only searches documents within the project you specify. This is intentional — it keeps results focused and prevents cross-contamination between unrelated projects.

If you need to search across multiple projects, make separate queries to each project.

Tips for better results

• Be specific — “What is the maximum concrete pour temperature?” gets better results than “Tell me about concrete”
• Upload relevant documents — the AI can only find what’s in your project. Missing documents mean missing answers
• Use complete documents — partial uploads or corrupted files lead to incomplete indexing
• Check document status — only completed documents are searchable. Documents still processing won’t appear in results