How prajwal-031/rag-agentic-chatbot works
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 agent.py · ai.pdf ai.pdf · .env .env · docker-compose.yml docker-compose.yml
Components 15
Python App
Single-process agent runtime that ingests documents, retrieves context, and serves chat responses.
- agent.py · Main application entrypoint; coordinates ingestion, retrieval, generation, and uAgent serving.
agent.py - Ingest · Startup phase that loads the PDF and prepares knowledge chunks.
- PDF reader · Parses the source PDF into document objects.
- Chunking · Splits documents into chunks and attaches metadata.
- Embeddings · Converts chunks into vectors with OpenAI text-embedding-3-small.
- Retrieve · Per-query hybrid search over vector and keyword signals.
- Generate · Assembles retrieved context and produces the final answer with GPT-4o-mini.
Persistence
Local PostgreSQL/pgvector store that holds the indexed knowledge base.
- PostgreSQL · Local database container exposed on localhost:5532 for persistent storage.
docker-compose.yml - pgvector · PostgreSQL extension enabling similarity search over embedded chunks.
- ai_documents · Persistent table that stores embedded document chunks and metadata.
External Services
Third-party APIs and agent messaging runtime used by the application.
- uAgent server · Receives incoming chat messages and returns agent responses.
- OpenAI API · External API used for embeddings and chat generation.
Local Inputs
Repository files that seed or configure the runtime.
- ai.pdf · Primary knowledge source ingested into the RAG index.
ai.pdf - .env · Local configuration, primarily the OpenAI API key and connection settings.
.env - docker-compose.yml · Defines the local PostgreSQL service used by the agent runtime.
docker-compose.yml
Connections 15
- 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.