Knowledge Base (RAG)¶

Geodesia G-1 includes a built-in Retrieval-Augmented Generation (RAG) system that lets you upload documents and have the LLM answer questions grounded in those documents. Every retrieved chunk is passed to the faithfulness detection axis, and the claims in the answer are verified citation-by-citation against the source material.

Supported document formats: PDF, Word (.docx), PowerPoint (.pptx), Markdown (.md), HTML, Excel (.xlsx), CSV, plain text (.txt)

How It Works¶

1. You upload a document → Docling parses it → chunked into ~480 tokens with 64-token overlap
2. Each chunk is embedded with BGE-M3 (multilingual) → stored in LanceDB
3. On a RAG-enabled chat request:
   a. Retrieve top-K chunks most relevant to the user's question (dense retrieval + reranking)
   b. Inject the retrieved context into the upstream LLM's prompt
   c. The LLM answers using the context
   d. Geodesia verifies each claim in the answer against the retrieved chunks
   e. If all claims are verified with citations → halluc_context flag suppressed
   f. If any claim is ungrounded → halluc_context flags normally

Collections¶

Documents are organised into collections. A collection is a named group of documents that shares an embedding index. You can have multiple collections for different topics or customers.

API Reference¶

All RAG endpoints are mounted at /v1/glad/rag/ on the gateway.

GET /v1/glad/rag/status¶

Returns whether the RAG service is loaded and ready.

curl http://localhost:8800/v1/glad/rag/status

{"ok": true, "embed_model": "BAAI/bge-m3", "device": "cuda:0", "store_dir": "runs/rag_store"}

POST /v1/glad/rag/collections¶

Create a new document collection.

Request:

{"name": "company-policies", "description": "Internal HR and legal policies"}

Response:

{"collection_id": "c_a3f7b2d1", "name": "company-policies", "created_at": "2026-06-10T12:00:00Z"}

GET /v1/glad/rag/collections¶

List all collections.

curl http://localhost:8800/v1/glad/rag/collections

Response:

[
  {
    "collection_id": "c_a3f7b2d1",
    "name": "company-policies",
    "description": "Internal HR and legal policies",
    "document_count": 3,
    "chunk_count": 142,
    "created_at": "2026-06-10T12:00:00Z"
  }
]

DELETE /v1/glad/rag/collections/{collection_id}¶

Delete a collection and all its documents and embeddings.

curl -X DELETE http://localhost:8800/v1/glad/rag/collections/c_a3f7b2d1

POST /v1/glad/rag/collections/{collection_id}/documents¶

Upload a document to a collection. The document is automatically parsed, chunked, and embedded.

curl -X POST \
  http://localhost:8800/v1/glad/rag/collections/c_a3f7b2d1/documents \
  -F "file=@/path/to/policy.pdf"

Multipart fields:

Response:

{
  "document_id": "doc_b5c2e1a3",
  "title": "policy.pdf",
  "chunk_count": 47,
  "status": "indexed"
}

Parsing notes: - PDF and DOCX files are parsed with Docling (IBM's multi-format parser), which preserves reading order, headings, and tables better than simple text extraction. - Large files may take several seconds to process. Embeddings are computed synchronously; the response is returned when indexing is complete.

DELETE /v1/glad/rag/collections/{collection_id}/documents/{document_id}¶

Delete a single document and cascade-remove its embedded chunks.

curl -X DELETE \
  http://localhost:8800/v1/glad/rag/collections/c_a3f7b2d1/documents/doc_b5c2e1a3

POST /v1/glad/rag/collections/{collection_id}/query¶

Query a collection directly (without a full chat request). Returns the most relevant chunks for a given question.

Request:

{
  "query": "What is the refund window?",
  "top_k": 5,
  "rerank": true
}

Response:

{
  "chunks": [
    {
      "text": "Our return policy allows refunds within 30 days of purchase...",
      "score": 0.94,
      "document_id": "doc_b5c2e1a3",
      "document_title": "policy.pdf",
      "page": 3,
      "heading": "Return Policy"
    }
  ]
}

Using RAG in Chat Requests¶

To use a knowledge base in a chat request, add the rag field:

{
  "model": "my-model",
  "stream": false,
  "messages": [{"role": "user", "content": "What is our refund window?"}],
  "rag": {
    "collection_id": "c_a3f7b2d1",
    "top_k": 5,
    "rerank": true,
    "verify": true,
    "verify_deep": true
  }
}

RAG Chat Request Fields¶

RAG in the Response¶

When RAG is active, the geodesia.rag field in the response contains retrieval and verification details:

"geodesia": {
  "rag": {
    "collection_id": "c_a3f7b2d1",
    "n_sources": 3,
    "sources": [
      {
        "text": "Our return policy allows refunds within 30 days...",
        "score": 0.94,
        "document_title": "policy.pdf",
        "page": 3
      }
    ],
    "verification": {
      "n_total": 2,
      "n_grounded": 2,
      "ungrounded": false,
      "claims": [
        {
          "claim": "refunds within 30 days",
          "grounded": true,
          "citation": "Our return policy allows refunds within 30 days..."
        }
      ]
    }
  },
  "brake": false
}

Configuration¶

RAG-specific environment variables: