Knowledge Base

How it works

When a user asks a question, Sandra generates an embedding of the query and performs a cosine-similarity search against your indexed content. The top chunks are injected into the agent’s context window.

Option A: Register a Git repository

Point Sandra at a GitHub or GitLab repository and she’ll clone, chunk, and embed the contents automatically. Markdown, text, and code files are all indexed.

curl -X POST $SANDRA_URL/api/repos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/your-org/your-docs",
    "branch": "main",
    "tenantId": "your-tenant-id"
  }'

Re-index at any time by calling the same endpoint. Sandra diffs and re-embeds only changed files.

Option B: Index documents via API

Push individual documents or text directly. Useful for CMS content, database exports, or any content that isn’t in a git repo.

curl -X POST $SANDRA_URL/api/index \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your document text goes here...",
    "metadata": {
      "source": "handbook",
      "title": "Employee Onboarding Guide",
      "category": "hr"
    },
    "tenantId": "your-tenant-id"
  }'

Option C: Check indexing status

List registered repos and their indexing status:

curl $SANDRA_URL/api/repos \
  -H "Authorization: Bearer $API_KEY"

[
  {
    "id": "repo-001",
    "url": "https://github.com/your-org/your-docs",
    "branch": "main",
    "status": "indexed",
    "chunks": 342,
    "lastIndexed": "2025-04-01T12:00:00Z"
  }
]

Retrieval in action

You don’t need to call a separate retrieval endpoint — Sandra handles it automatically during conversation. When a user sends a message, the agent:

1. Generates an embedding of the user’s message
2. Searches pgvector for the top-k relevant chunks (filtered by tenant)
3. Injects the retrieved context into the prompt
4. Generates a grounded response with source citations

Sandra cites sources in her responses so users can verify the information. The toolsUsed field in the API response shows when RAG was invoked.

Health check

Verify the knowledge base is operational and check index stats:

curl $SANDRA_URL/api/health

{
  "status": "ok",
  "database": "connected",
  "embeddings": { "totalChunks": 1247, "repos": 3 }
}