# prajwal-031/rag-agentic-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/prajwal-031/rag-agentic-chatbot
- Repository: https://github.com/prajwal-031/rag-agentic-chatbot

## Overview

1. **Repository shape**
   - This is a **single-service Python application** centered on `agent.py`.
   - There is no separate frontend or worker service; **document ingestion, vector indexing, retrieval, and chat serving all happen in one runtime**.

2. **Primary inputs**
   - The main knowledge source is the local PDF file **`ai.pdf`**.
   - Configuration is minimal and comes from **`.env`**, primarily the **`OPENAI_API_KEY`**.
   - `projectfile.pdf` is present in the repo but is not described as part of the default runtime path in the README.

3. **Document ingestion pipeline**
   - At startup, the agent reads the PDF using a PDF reader, splits it into document chunks, and attaches metadata.
   - These chunks become the persistent knowledge base contents rather than being queried directly from the file each time.

4. **Embedding and indexing**
   - Each chunk is embedded using OpenAI’s **`text-embedding-3-small`** model.
   - Embeddings are stored in a **PostgreSQL database with the pgvector extension**, exposed locally via Docker Compose.
   - The vector table is named **`ai_documents`**.

5. **Persistent storage boundary**
   - The database is the main persistence layer and is separate from the Python process.
   - The repo expects PostgreSQL to run on **`localhost:5532`** with database/user/password all set to **`ai`** for local development.

6. **Retrieval subsystem**
   - Query-time retrieval happens through Agno’s knowledge layer using **hybrid search**: semantic vector similarity plus keyword matching.
   - The retrieved documents are the context passed into generation, so the response quality depends on the indexed PDF chunks.

7. **Generation subsystem**
   - The answer model is **`gpt-4o-mini`**.
   - The flow is classic RAG: user query → retrieve relevant chunks from pgvector → assemble context → generate response with the chat model.

8. **Agent/runtime boundary**
   - The application exposes a **uAgent** server, running on **port 8001**.
   - uAgent handles incoming chat messages and returns acknowledgements/content, making the service accessible as an agent rather than a web API.

9. **End-to-end data flow**
   - Startup path: PDF file → chunking → OpenAI embeddings → pgvector persistence.
   - Runtime path: incoming user message → uAgent → RAG lookup in pgvector → GPT-4o-mini response → response sent back through uAgent.

10. **External dependencies**
   - The architecture depends materially on three external systems:
     - **OpenAI API** for embeddings and response generation
     - **PostgreSQL/pgvector** for persistent similarity search
     - **uAgent/AgentVerse ecosystem** for agent messaging and inspection

11. **Operational model**
   - The service is intended to be started with Docker Compose for the database and `python agent.py` for the agent.
   - The README shows the agent also emits an **AgentVerse inspection URL**, which is useful for observing the running agent instance.

12. **What to draw in an architecture diagram**
   - A good diagram would show one Python application box (`agent.py`) connected to:
     - a local PDF input,
     - OpenAI API,
     - PostgreSQL + pgvector,
     - and the uAgent message interface.
   - The key architectural distinction is that **ingestion and live chat are two phases of the same process**, sharing the same knowledge base.

Main entry points: [`agent.py`](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/agent.py) (agent.py), [`ai.pdf`](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/ai.pdf) (ai.pdf), [`.env`](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/.env) (.env), [`docker-compose.yml`](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/docker-compose.yml) (docker-compose.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Python App"]
  node_agent_py["agent.py<br/>agent runtime<br/>[agent.py]"]
  node_ingest(("Ingest<br/>pipeline stage"))
  node_pdf_read["PDF reader<br/>document loader"]
  node_split_meta["Chunking<br/>document processing"]
  node_embed(("Embeddings<br/>embedding stage"))
  node_retrieve(("Retrieve<br/>rag retrieval"))
  node_generate(("Generate<br/>llm response"))
end

subgraph group_storage["Persistence"]
  node_postgres[("PostgreSQL<br/>database<br/>[docker-compose.yml]")]
  node_pgvector[("pgvector<br/>vector index")]
  node_ai_docs[("ai_documents<br/>vector table")]
end

subgraph group_external["External Services"]
  node_uagent["uAgent server<br/>message server"]
  node_openai{{"OpenAI API<br/>ai service"}}
end

subgraph group_inputs["Local Inputs"]
  node_ai_pdf["ai.pdf<br/>source document<br/>[ai.pdf]"]
  node_env[".env<br/>runtime config<br/>[.env]"]
  node_compose["docker-compose.yml<br/>infra config<br/>[docker-compose.yml]"]
end

node_agent_py -->|"startup"| node_ingest
node_ai_pdf -->|"input"| node_pdf_read
node_pdf_read -->|"documents"| node_split_meta
node_split_meta -->|"chunks"| node_embed
node_embed -->|"embed"| node_openai
node_embed -->|"store"| node_ai_docs
node_ai_docs -->|"indexed by"| node_pgvector
node_agent_py -->|"query"| node_retrieve
node_retrieve -->|"hybrid search"| node_ai_docs
node_retrieve -->|"similarity"| node_pgvector
node_retrieve -->|"context"| node_generate
node_generate -->|"chat"| node_openai
node_agent_py -->|"serve"| node_uagent
node_env -->|"config"| node_agent_py
node_compose -->|"provisions"| node_postgres

click node_agent_py "https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/agent.py"
click node_postgres "https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/docker-compose.yml"
click node_ai_pdf "https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/ai.pdf"
click node_env "https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/.env"
click node_compose "https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/docker-compose.yml"

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_agent_py,node_ingest,node_pdf_read,node_split_meta,node_embed,node_retrieve,node_generate toneBlue
class node_postgres,node_pgvector,node_ai_docs toneAmber
class node_uagent,node_openai toneMint
class node_ai_pdf,node_env,node_compose toneRose
```

## Components

### Python App

Single-process agent runtime that ingests documents, retrieves context, and serves chat responses.

- [agent.py](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/agent.py): agent runtime · Main application entrypoint; coordinates ingestion, retrieval, generation, and uAgent serving. · `agent.py`
- **Ingest**: pipeline stage · Startup phase that loads the PDF and prepares knowledge chunks.
- **PDF reader**: document loader · Parses the source PDF into document objects.
- **Chunking**: document processing · Splits documents into chunks and attaches metadata.
- **Embeddings**: embedding stage · Converts chunks into vectors with OpenAI text-embedding-3-small.
- **Retrieve**: rag retrieval · Per-query hybrid search over vector and keyword signals.
- **Generate**: llm response · Assembles retrieved context and produces the final answer with GPT-4o-mini.

### Persistence

Local PostgreSQL/pgvector store that holds the indexed knowledge base.

- [PostgreSQL](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/docker-compose.yml): database · Local database container exposed on localhost:5532 for persistent storage. · `docker-compose.yml`
- **pgvector**: vector index · PostgreSQL extension enabling similarity search over embedded chunks.
- **ai_documents**: vector table · Persistent table that stores embedded document chunks and metadata.

### External Services

Third-party APIs and agent messaging runtime used by the application.

- **uAgent server**: message server · Receives incoming chat messages and returns agent responses.
- **OpenAI API**: ai service · External API used for embeddings and chat generation.

### Local Inputs

Repository files that seed or configure the runtime.

- [ai.pdf](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/ai.pdf): source document · Primary knowledge source ingested into the RAG index. · `ai.pdf`
- [.env](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/.env): runtime config · Local configuration, primarily the OpenAI API key and connection settings. · `.env`
- [docker-compose.yml](https://github.com/prajwal-031/rag-agentic-chatbot/blob/master/docker-compose.yml): infra config · Defines the local PostgreSQL service used by the agent runtime. · `docker-compose.yml`

## Connections

- agent.py → Ingest: startup · Runs ingestion when the agent process starts.
- ai.pdf → PDF reader: input · Source PDF is loaded by the document reader.
- PDF reader → Chunking: documents · Parsed pages are split into chunks and annotated.
- Chunking → Embeddings: chunks · Chunked documents are prepared for embedding.
- Embeddings → OpenAI API: embed · Uses OpenAI text-embedding-3-small to vectorize chunks.
- Embeddings → ai_documents: store · Persist embeddings and chunk metadata in the vector table.
- ai_documents → pgvector: indexed by · Vector search is powered by pgvector inside PostgreSQL.
- agent.py → Retrieve: query · Incoming user messages trigger retrieval.
- Retrieve → ai_documents: hybrid search · Fetches relevant chunks using vector similarity and keyword matching.
- Retrieve → pgvector: similarity · Uses the vector extension for semantic ranking.
- Retrieve → Generate: context · Retrieved chunks are passed into generation as context.
- Generate → OpenAI API: chat · Uses GPT-4o-mini for response generation.
- agent.py → uAgent server: serve · Exposes the chat agent through the uAgent interface.
- .env → agent.py: config · Provides runtime secrets and connection settings.
- docker-compose.yml → PostgreSQL: provisions · Starts the local PostgreSQL/pgvector service.
