RAG Overview
Upload a document, and the platform chunks, embeds, and indexes it per agent. Ask a question, and a LangGraph pipeline retrieves, judges the retrieval, and only then answers — or refuses.
The two halves
| Page | Covers |
|---|---|
| Ingestion | Upload validation, chunking strategy, the embedding pipeline, dual-store writes |
| Retrieval | Query embedding, Chroma search, agent scoping, scores, the raw search endpoint |
| Corrective RAG | The LangGraph graph: nodes, routing, refusal semantics, cost profile |
Why this design
Per-agent knowledge bases. Every vector carries agent_id metadata and every query filters on it — an agent can only ever answer from its own documents. This is the platform's tenant-isolation primitive (Security).
Grounded or silent. Two independent mechanisms prevent hallucinated answers: the evaluator gate (routes weak retrievals to refusal before generation) and the answer prompt's context-only rule with a mandated refusal string. The result: the honest failure mode is "I could not find this information in the uploaded documents." — never a confident invention.
Relational truth, vector speed. SQLite keeps the authoritative record (what was uploaded, how it chunked, each chunk's vector_id); Chroma exists purely to be searched. If the vector store were lost, the chunks in SQLite could rebuild it.
Capabilities and limits at a glance
| Today | |
|---|---|
| File types | .txt (UTF-8) only |
| Chunking | fixed 800 chars, 100 overlap |
| Embeddings | OpenAI text-embedding-3-small (1536-dim) |
| Store | local persistent Chroma, single agent_documents collection |
| Retrieval | top-k (default 3) dense search, agent-filtered; score = raw distance (lower = better) |
| Answering | corrective graph via POST .../documents/ask; raw search via POST .../documents/search |
| Tool gating | both query endpoints require the document_search tool |
| Deletion / re-indexing | ❌ not implemented — vectors persist forever (Known Issues) |
Try it in 60 seconds
printf "Premium customers have a 4-hour support SLA." > sla.txt
curl -X POST http://localhost:8001/agents/1/documents/upload -F "file=@sla.txt"
curl -X POST http://localhost:8001/agents/1/documents/ask \
-H "Content-Type: application/json" \
-d '{"question": "What is the premium SLA?", "top_k": 3}'Full walkthrough with inspection steps: RAG Tutorial.
Related pages
- Service: Documents · Service: RAG Graph — the implementing code
- API Reference: Documents — the endpoints
- Evaluation — the judge in the middle