Document Intelligence & RAG¶
The Document Intelligence & RAG module turns user-shared content (uploads, email attachments, Swisper-generated notes) into searchable, planner-accessible knowledge. v2 replaces the v1 LangGraph delegation flow with Pattern 2 tools registered directly with the agentic supervisor — search_documents, get_document, list_documents, and create_document — so the planner can interleave document operations with memory and other tools in a single turn.
Retrieval is hybrid (RRF over pgvector + tsvector) with an optional Vertex AI Discovery Engine reranker. Embeddings ride two distinct lanes: gemini-embedding-001 for facts, gemini-embedding-2-preview for documents. Every read and write is scoped by workspace_id + avatar_id. Indexed documents feed the memory graph asynchronously via ExtractDocumentFactsJob.
Key Components¶
| Component | Purpose |
|---|---|
Document Tools (agents/document/) |
Four BaseTool subclasses registered with the FC loop — search_documents, get_document, list_documents, create_document. Built per request by build_document_tools(). |
DocumentSearchService (services/document_search.py) |
Embedding-lane selection, fusion strategy (dense_only / weighted_blend / rrf), AttachmentChunk join, reranker invocation. |
IndexingService (services/file_indexing.py) |
Upload → store (S3) → parse (Document AI Layout Parser) → chunk → embed (document_embedding) → persist with tsvector populated against plaintext. |
RerankerService (services/reranker.py) |
Vertex AI Discovery Engine adapter (semantic-ranker-default-004). Graceful degradation. |
ExtractDocumentFactsJob (jobs/extract_document_facts_job.py) |
Async fact extraction from indexed documents, with source_ref_type='document' provenance. |
ReembedDocumentChunksJob (jobs/reembed_document_chunks_job.py) |
One-shot migration of legacy chunks onto the document_embedding lane. |
Supervisor wiring (agents/agentic_supervisor/agent.py) |
_get_document_tools() builds the request-scoped tool list when DOCUMENT_SEARCH_V2_ENABLED=True and a workspace context exists. |
Documentation Sections¶
- Overview — What the module does, who it serves, supported formats, limits and FAQ.
- Architecture — v2 design, v1→v2 changes, tool catalogue, hybrid retrieval, embedding lanes, configuration, and a spec-vs-implementation gap analysis.