How mr-rsr/agentic-rag-app-tutorial works
1. Top-level shape
- This is a small, service-oriented FastAPI backend for a RAG agent.
- The runtime entrypoint is app/main.py, with most behavior pushed into app/services/* rather than living in the API layer.
2. API boundary
- The HTTP layer exposes three main operations: ingest, query, and health.
- app/models/schemas.py defines the request/response contracts, so the API boundary is explicit and typed.
3. Configuration boundary
- app/config/settings.py centralizes environment-driven configuration.
- The repo is designed to run locally with .env values such as AWS credentials, Gemini API key, and the PDF folder path; this makes external integrations configurable without changing code.
4. Document ingestion subsystem
- app/services/document_loader.py is the intake path for content.
- It supports two sources: web URLs and PDF files from pdf_docs/.
- This layer is responsible for loading, cleaning, and splitting content into chunks suitable for retrieval.
5. Embedding and model subsystem
- app/services/models.py owns creation of the LLM and embedding model instances.
- The README indicates the primary stack is AWS Bedrock for Claude Haiku + Titan embeddings, with Google Gemini as an optional alternative.
- This is the main model boundary between business logic and external AI providers.
6. Vector storage subsystem
- app/services/vector_store.py wraps a FAISS index.
- Ingestion produces embedded chunks that are stored here for similarity search, making this the retrieval backbone of the RAG flow.
7. Agent/tooling subsystem
- app/services/tools.py defines the tools the agent can invoke.
- The tool set includes:
- RAG retrieval over the vector store
- Web search via DuckDuckGo
- Weather via a mock tool
- This layer is where the agent gets access to non-LLM capabilities.
8. Orchestration layer
- app/services/agent.py coordinates the LLM and the available tools into a single query-handling agent.
- It sits above retrieval and tool execution, and below the API, acting as the main business-logic orchestrator.
9. Primary data flow: ingestion
- A client calls /ingest with either a URL or a request to process the PDF folder.
- Documents are loaded and split, embedded with the configured embedding model, then written into FAISS.
- The response reports how many chunks were added and from which source(s).
10. Primary data flow: question answering
- A client calls /query with a natural-language prompt.
- The agent decides whether to answer from retrieved context, web search, weather, or a combination.
- The final response is synthesized by the LLM and returned through the API.
11. Persistence and state
- The architecture appears centered on an in-process vector store rather than a separate database service.
- The pdf_docs/ directory is effectively a local content source, and the FAISS index is the key stateful component supporting retrieval.
12. External dependencies that shape the design
- The system depends on FastAPI/Uvicorn for serving, FAISS for retrieval, and external model/search providers for live intelligence.
- DuckDuckGo search adds real-time web grounding, while the weather tool provides an additional non-retrieval capability for the agent.
13. How to draw the architecture
- A clear diagram would show: client → FastAPI routes → service layer → (document loader / agent / tools / vector store / model factory).
- External boxes should include AWS Bedrock, Gemini, and DuckDuckGo.
- The pdf_docs/ folder should be shown as a local input source feeding ingestion, and FAISS as the local retrieval store feeding the agent.
Main entry points: main.py FastAPI app · models.py Models · agent.py Agent · vector_store.py Vector store
Components 17
API layer
FastAPI entrypoint, contracts, and request handlers.
- Client · HTTP consumer of ingest and query operations.
- FastAPI app · Runtime entrypoint that exposes the HTTP API.
app/main.py - Ingest · API operation for loading and indexing content.
- Query · API operation for answering natural-language questions.
- Health · Lightweight service health check.
- Schemas · Typed request and response models for the API.
app/models/schemas.py - Settings · Environment-driven application configuration.
app/config/settings.py
Service layer
Core ingestion, retrieval, model, and agent orchestration services.
- Loader · Loads, cleans, and splits web or PDF documents into chunks.
app/services/document_loader.py - Models · Creates the LLM and embedding model instances.
app/services/models.py - Vector store · Wraps FAISS for similarity search over embedded chunks.
app/services/vector_store.py - Tools · Agent tools for retrieval, web search, and weather.
app/services/tools.py - Agent · Coordinates the model and tools to answer queries.
app/services/agent.py
State and sources
Local content and retrieval state used by the app.
- PDF docs · Local folder containing PDF inputs for ingestion.
pdf_docs - FAISS · Local similarity index backing retrieval.
- AWS Bedrock · Primary external provider for Claude and Titan models.
- Gemini · Optional alternative model provider.
- DuckDuckGo · External web search tool used by the agent.
Connections 20
- Client → FastAPI app: calls · Sends HTTP requests to the FastAPI application.
- FastAPI app → Ingest: exposes · Registers the ingest operation.
- FastAPI app → Query: exposes · Registers the query operation.
- FastAPI app → Health: exposes · Registers the health check.
- FastAPI app → Schemas: uses · Shares typed request and response contracts.
- FastAPI app → Settings: loads · Reads runtime configuration from the environment.
- Ingest → Loader: loads · Starts document intake and chunking.
- Ingest → Models: embeds · Builds embeddings for ingested chunks.
- Ingest → Vector store: indexes · Writes embedded chunks into retrieval storage.
- Loader → PDF docs: reads · Consumes local PDF documents when requested.
- Loader → Models: prepares · Produces content ready for embedding and retrieval.
- Models → AWS Bedrock: primary · Uses AWS Bedrock as the default model backend.
- Models → Gemini: optional · Can switch to Gemini as an alternative backend.
- Vector store → FAISS: wraps · FAISS is the underlying similarity index.
- Query → Agent: delegates · Hands natural-language questions to the agent layer.
- Agent → Tools: invokes · Uses tool capabilities during reasoning.
- Agent → Models: runs on · Relies on the configured LLM for synthesis.
- Tools → Vector store: retrieves · Exposes RAG retrieval over embedded chunks.
- Tools → DuckDuckGo: searches · Uses web search for fresh context.
- Agent → Vector store: grounds · Retrieval can feed the final answer path.