How roly-luna/deep-research-agentic-rag works
Deep Research Agentic RAG is a FastAPI research assistant: users authenticate, submit conversation messages, and receive agent-generated answers grounded in PDF retrieval and external research tools. A separate document workflow uploads and indexes PDFs or searches the knowledge base directly. PostgreSQL supports both vector storage and persistent conversation checkpoints. The main app wires routes and runtime services; route and tool internals were not all excerpted, so some documented capabilities are shown without detailed call paths.
Main entry points: core.py Deep research agent · main.py FastAPI app · documents.py Document endpoints · pgvector.py PGVector store
Components 25
API and access
- FastAPI app
app/main.py - Token endpoint
app/api/routes/auth.py - JWT security
app/api/auth/security.py - Request authentication
app/api/auth/dependencies.py - Conversation endpoints
app/api/routes/conversations.py - Document endpoints
app/api/routes/documents.py - Health endpoints
app/api/routes/health.py
Research agent
- Deep research agent
app/agent/core.py - Prompt templates
app/prompts - arXiv search
app/tools/arxiv_search.py - Wikipedia search
app/tools/wikipedia_search.py - Web search
app/tools/web_search.py - Research analyst sub-agent
app/tools
Knowledge base
- PDF ingestion
app/ingestion/pipeline.py - Gemini embeddings
app/embeddings/gemini.py - PGVector store
app/vectorstore/pgvector.py - Semantic retrieval
app/rag/retriever.py - Knowledge-base tool
app/tools/knowledge_base.py
Runtime services
- PostgreSQL
app/db/postgres.py - Application settings
app/config/settings.py - Tavily search service
- arXiv service
- Wikipedia service
- Gemini model
Other components
- API user
Connections 30
- API user → FastAPI app: calls API
- FastAPI app → Token endpoint: registers routes
app/main.py - FastAPI app → Conversation endpoints: registers routes
app/main.py - FastAPI app → Document endpoints: registers routes
app/main.py - FastAPI app → Health endpoints: registers routes
app/main.py - Token endpoint → JWT security: issues token
app/api/routes/auth.py - Conversation endpoints → Request authentication: requires authentication
app/api/routes/conversations.py - Document endpoints → Request authentication: requires authentication
app/api/routes/documents.py - Conversation endpoints → Deep research agent: runs conversation
app/api/routes/conversations.py - Document endpoints → PDF ingestion: ingests uploads
app/api/routes/documents.py - Document endpoints → Semantic retrieval: searches knowledge base
app/api/routes/documents.py - FastAPI app → Deep research agent: creates agent
app/main.py - FastAPI app → PostgreSQL: opens pool
app/main.py - FastAPI app → PGVector store: initializes store
app/main.py - Deep research agent → Prompt templates: renders prompt
app/agent/core.py - Deep research agent → arXiv search: registers tools
app/agent/core.py - Deep research agent → Wikipedia search: registers tools
app/agent/core.py - Deep research agent → Web search: registers tools
app/agent/core.py - Deep research agent → Knowledge-base tool: registers tools
app/agent/core.py - Deep research agent → Research analyst sub-agent: may delegate
app/agent/core.py - Deep research agent → PostgreSQL: persists checkpoints
- PDF ingestion → PGVector store: stores chunks
app/ingestion/pipeline.py - PGVector store → Gemini embeddings: embeds documents
app/vectorstore/pgvector.py - Semantic retrieval → PGVector store: searches vectors
app/rag/retriever.py - Knowledge-base tool → Semantic retrieval: retrieves passages
app/tools/knowledge_base.py - arXiv search → arXiv service: searches papers
- Wikipedia search → Wikipedia service: searches articles
- Web search → Tavily search service: searches web
app/tools/web_search.py - Deep research agent → Gemini model: generates answers
- FastAPI app → Application settings: loads configuration
app/main.py