# chandancoding/production-agentic-rag architecture

> Architecture diagram of the GitHub repository chandancoding/production-agentic-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandancoding/production-agentic-rag
- Repository: https://github.com/chandancoding/production-agentic-rag

## Overview

This is a provider-agnostic agentic RAG library with CLI and FastAPI interfaces. Its main workflow loads and chunks documents into a hybrid index, then checks a question, plans sub-questions, retrieves and synthesizes grounded answers, and returns citations and a trace. Evaluation, alternate LangGraph execution, and optional integrations are separate capabilities. Edges follow shown calls or README claims; some branches are documented but their implementation was not sampled.

Main entry points: [`src/production_agentic_rag/pipeline.py`](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/pipeline.py) (RAG pipeline), [`src/production_agentic_rag/agents/rag_agent.py`](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/rag_agent.py) (Agent loop), [`src/production_agentic_rag/retrieval/hybrid.py`](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/hybrid.py) (Hybrid retriever), [`src/production_agentic_rag/cli.py`](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["HTTP service<br/>[main.py]"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_loaders["File loaders<br/>[loaders.py]"]
  node_chunking["Chunk strategies<br/>[chunking.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_retriever["Hybrid retriever<br/>[hybrid.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_vectorstore[("Vector store<br/>[vectorstore.py]")]
  node_embeddings["Embedding providers<br/>[embeddings.py]"]
end

subgraph group_agent["Agent and safeguards"]
  node_agent["Agent loop<br/>[rag_agent.py]"]
  node_planner["Query planner<br/>[planner.py]"]
  node_tool["Retrieval tool<br/>[tools.py]"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_langgraph["LangGraph engine<br/>[graph.py]"]
end

subgraph group_operations["Evaluation and telemetry"]
  node_evaluation["Evaluation harness<br/>[harness.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_tracer["Trace accounting<br/>[observability.py]"]
  node_integrations["Optional integrations<br/>[integrations.py]"]
end

node_user(("User"))
node_corpus["Document corpus"]

node_user -->|"asks or evaluates"| node_cli
node_user -->|"sends request"| node_api
node_cli -->|"loads documents"| node_loaders
node_cli -->|"runs query"| node_pipeline
node_corpus -->|"provides files"| node_loaders
node_loaders -->|"supplies documents"| node_pipeline
node_pipeline -->|"chunks text"| node_chunking
node_pipeline -->|"indexes chunks"| node_retriever
node_pipeline -->|"checks and redacts"| node_guardrails
node_pipeline -->|"runs selected engine"| node_agent
node_pipeline -->|"builds embedder"| node_embeddings
node_pipeline -->|"builds provider"| node_llm
node_pipeline -->|"records query trace"| node_tracer
node_pipeline -->|"selects when configured"| node_langgraph
node_agent -->|"decomposes query"| node_planner
node_agent -->|"calls retrieval"| node_tool
node_agent -->|"synthesizes answer"| node_llm
node_agent -->|"scores grounding"| node_guardrails
node_agent -->|"records usage spans"| node_tracer
node_tool -->|"retrieves chunks"| node_retriever
node_retriever -->|"searches lexically"| node_bm25
node_retriever -->|"searches vectors"| node_vectorstore
node_vectorstore -->|"embeds chunks"| node_embeddings
node_api -->|"serves RAG requests"| node_pipeline
node_cli -->|"runs eval"| node_evaluation
node_evaluation -->|"computes measures"| node_metrics
node_integrations -.->|"wraps retrieval tool"| node_retriever
node_tracer -.->|"exports telemetry"| node_integrations

click node_cli "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/cli.py"
click node_api "https://github.com/chandancoding/production-agentic-rag/blob/main/api/main.py"
click node_pipeline "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/pipeline.py"
click node_loaders "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/ingestion/loaders.py"
click node_chunking "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/ingestion/chunking.py"
click node_retriever "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/hybrid.py"
click node_bm25 "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/bm25.py"
click node_vectorstore "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/vectorstore.py"
click node_embeddings "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/providers/embeddings.py"
click node_agent "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/rag_agent.py"
click node_planner "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/planner.py"
click node_tool "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/tools.py"
click node_llm "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/providers/llm.py"
click node_guardrails "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/guardrails.py"
click node_langgraph "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/graph.py"
click node_evaluation "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/evaluation/harness.py"
click node_metrics "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/evaluation/metrics.py"
click node_tracer "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/observability.py"
click node_integrations "https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/integrations.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_pipeline,node_user toneBlue
class node_loaders,node_chunking toneAmber
class node_retriever,node_bm25,node_vectorstore,node_embeddings toneMint
class node_agent,node_planner,node_tool,node_llm,node_guardrails,node_langgraph toneRose
class node_evaluation,node_metrics,node_tracer,node_integrations,node_corpus toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/cli.py): `src/production_agentic_rag/cli.py`
- [HTTP service](https://github.com/chandancoding/production-agentic-rag/blob/main/api/main.py): `api/main.py`
- [RAG pipeline](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/pipeline.py): `src/production_agentic_rag/pipeline.py`

### Ingestion

- [File loaders](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/ingestion/loaders.py): `src/production_agentic_rag/ingestion/loaders.py`
- [Chunk strategies](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/ingestion/chunking.py): `src/production_agentic_rag/ingestion/chunking.py`

### Retrieval

- [Hybrid retriever](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/hybrid.py): `src/production_agentic_rag/retrieval/hybrid.py`
- [BM25 search](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/bm25.py): `src/production_agentic_rag/retrieval/bm25.py`
- [Vector store](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/retrieval/vectorstore.py): `src/production_agentic_rag/retrieval/vectorstore.py`
- [Embedding providers](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/providers/embeddings.py): `src/production_agentic_rag/providers/embeddings.py`

### Agent and safeguards

- [Agent loop](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/rag_agent.py): `src/production_agentic_rag/agents/rag_agent.py`
- [Query planner](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/planner.py): `src/production_agentic_rag/agents/planner.py`
- [Retrieval tool](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/agents/tools.py): `src/production_agentic_rag/agents/tools.py`
- [LLM providers](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/providers/llm.py): `src/production_agentic_rag/providers/llm.py`
- [Guardrails](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/guardrails.py): `src/production_agentic_rag/guardrails.py`
- [LangGraph engine](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/graph.py): `src/production_agentic_rag/graph.py`

### Evaluation and telemetry

- [Evaluation harness](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/evaluation/harness.py): `src/production_agentic_rag/evaluation/harness.py`
- [Evaluation metrics](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/evaluation/metrics.py): `src/production_agentic_rag/evaluation/metrics.py`
- [Trace accounting](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/observability.py): `src/production_agentic_rag/observability.py`
- [Optional integrations](https://github.com/chandancoding/production-agentic-rag/blob/main/src/production_agentic_rag/integrations.py): `src/production_agentic_rag/integrations.py`

### Other components

- **User**
- **Document corpus**

## Connections

- User → CLI: asks or evaluates (evidence: `README.md`)
- User → HTTP service: sends request (evidence: `README.md`)
- CLI → File loaders: loads documents (evidence: `src/production_agentic_rag/cli.py`)
- CLI → RAG pipeline: runs query (evidence: `src/production_agentic_rag/cli.py`)
- Document corpus → File loaders: provides files (evidence: `README.md`)
- File loaders → RAG pipeline: supplies documents (evidence: `src/production_agentic_rag/cli.py`)
- RAG pipeline → Chunk strategies: chunks text (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → Hybrid retriever: indexes chunks (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → Guardrails: checks and redacts (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → Agent loop: runs selected engine (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → Embedding providers: builds embedder (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → LLM providers: builds provider (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → Trace accounting: records query trace (evidence: `src/production_agentic_rag/pipeline.py`)
- RAG pipeline → LangGraph engine: selects when configured (evidence: `src/production_agentic_rag/pipeline.py`)
- Agent loop → Query planner: decomposes query (evidence: `src/production_agentic_rag/agents/rag_agent.py`)
- Agent loop → Retrieval tool: calls retrieval (evidence: `src/production_agentic_rag/agents/rag_agent.py`)
- Agent loop → LLM providers: synthesizes answer (evidence: `src/production_agentic_rag/agents/rag_agent.py`)
- Agent loop → Guardrails: scores grounding (evidence: `src/production_agentic_rag/agents/rag_agent.py`)
- Agent loop → Trace accounting: records usage spans (evidence: `src/production_agentic_rag/agents/rag_agent.py`)
- Retrieval tool → Hybrid retriever: retrieves chunks (evidence: `src/production_agentic_rag/agents/tools.py`)
- Hybrid retriever → BM25 search: searches lexically (evidence: `src/production_agentic_rag/retrieval/hybrid.py`)
- Hybrid retriever → Vector store: searches vectors (evidence: `src/production_agentic_rag/retrieval/hybrid.py`)
- Vector store → Embedding providers: embeds chunks (evidence: `src/production_agentic_rag/retrieval/vectorstore.py`)
- HTTP service → RAG pipeline: serves RAG requests (evidence: `README.md`)
- CLI → Evaluation harness: runs eval (evidence: `src/production_agentic_rag/cli.py`)
- Evaluation harness → Evaluation metrics: computes measures (evidence: `src/production_agentic_rag/evaluation/harness.py`)
- Optional integrations → Hybrid retriever: wraps retrieval tool (evidence: `README.md`)
- Trace accounting → Optional integrations: exports telemetry (evidence: `README.md`)