How ogulcanakca/agentic-chatbot works
1. High-level shape
- This repository is a Python-based multi-agent chatbot built around a LangGraph supervisor pattern.
- A single chat interface routes each user request into one of several specialized branches: Resmi Gazete RAG, news/general knowledge, uploaded-document RAG, travel planning, or fallback.
2. Primary entry point and UI boundary
- The user-facing entry point is Streamlit in app/ui/streamlit_app.py.
- The UI is thin: it collects chat input, optional document uploads, and displays answers, sources, and travel-plan outputs; it delegates orchestration to the graph layer.
3. Main orchestration layer
- app/graph.py defines the top-level LangGraph workflow.
- Shared conversational data moves through app/core/state.py, which acts as the central state object passed between supervisor and agents.
- app/core/llm.py centralizes LLM creation so all agents use a consistent model setup.
4. Supervisor routing
- app/agents/supervisor.py classifies the request and chooses the next agent.
- This is the main architectural decision point: it determines whether the query is treated as legal/government text, general knowledge/news, user document QA, travel planning, or fallback.
5. Specialized agents at the top level
- app/agents/resmi_gazete_agent.py handles Turkish Resmi Gazete questions using retrieval-augmented generation.
- app/agents/news_agent.py answers news and general knowledge queries using external search and knowledge tools.
- app/agents/agentic_rag_agent.py handles uploaded document QA via RAG.
- app/agents/travel_agent.py bridges into the travel-planning subsystem.
- app/agents/fallback_agent.py covers out-of-scope queries.
6. RAG and vector storage boundary
- Persistent retrieval data is managed in app/storage/database.py on top of ChromaDB.
- The repository contains prebuilt vector data in data/embeddings/, so the RAG agents can query local embeddings without rebuilding them at runtime.
- app/tools/rag_tools.py provides document retrieval and context formatting for the Resmi Gazete path.
7. External knowledge tools
- app/tools/external_apis.py supplies tools used by the news/general-knowledge branch.
- The README indicates integrations such as Tavily/DuckDuckGo, Wikipedia, and related search APIs; this branch is designed for live or semi-live information rather than local corpora.
8. Travel-planning subsystem as a nested workflow
- app/travel_system/workflow.py defines a separate subworkflow for trip planning, distinct from the main chat graph.
- It has its own agents:
- destination_agent.py for destination research,
- date_budget_agent.py for time/budget reasoning,
- coordinator_agent.py for composing the final travel plan.
- Its tools cover parsing, budget, date, destination, and PDF generation, making it a self-contained planning pipeline.
9. Travel outputs
- The travel subsystem can produce a PDF itinerary via app/travel_system/utils/pdf_saver.py.
- plans/ stores generated plan PDFs, while assets/fonts/ and fonts/ provide the font assets needed for PDF rendering.
10. Data preparation pipeline
- scripts/news_fetcher.py and scripts/resmi_news_fetcher.py fetch source content into data/raw/.
- scripts/process_data.py converts raw content into structured chunks under data/processed/.
- scripts/generate_embeddings.py builds the vector store in data/embeddings/.
- scripts/del.py is a cleanup utility for resetting generated data.
11. Configuration and environment
- Runtime behavior is driven by configs/agent_config.py, configs/app_config.py, configs/api_config.py, and configs/script_config.py.
- API keys and service credentials are loaded from .env, which is part of the deployment boundary but not the application logic itself.
12. Deployment and persistence
- The repo supports both local execution and Docker/Docker Compose deployment.
- Persistent application state is mostly file-based: data/ for corpora and embeddings, plans/ for PDFs, and environment variables for secrets.
- There is no central relational backend in the architecture; the system is primarily a graph-orchestrated LLM app with local vector persistence and external API calls.
Main entry points: supervisor.py Supervisor · graph.py Main Graph · workflow.py Travel Workflow · news_agent.py News Agent
Components 29
User Interface
Streamlit chat entry point and presentation layer.
- Streamlit UI · Chat interface that collects input, uploads, and displays answers and sources.
app/ui/streamlit_app.py
Chat Orchestration
Supervisor graph, shared state, and agent routing.
- Main Graph · Top-level orchestration workflow connecting the supervisor to specialized branches.
app/graph.py - Chat State · Central conversational state passed through the graph and agents.
app/core/state.py - LLM Setup · Centralized creation and configuration of LLM instances.
app/core/llm.py - Supervisor · Classifies each request and selects the next branch to run.
app/agents/supervisor.py
Specialized Agents
Domain branches for legal, news, document QA, travel, and fallback.
- Resmi Gazete · Answers Turkish official gazette questions using local retrieval.
app/agents/resmi_gazete_agent.py - News Agent · Handles news and general knowledge queries using external sources.
app/agents/news_agent.py - Doc RAG · Answers questions over user-uploaded documents.
app/agents/agentic_rag_agent.py - Travel Bridge · Hands travel requests into the dedicated planning subsystem.
app/agents/travel_agent.py - Fallback · Covers out-of-scope or unsupported requests.
app/agents/fallback_agent.py - External APIs · Live knowledge and search integrations used by the news branch.
app/tools/external_apis.py
Travel Subsystem
Nested planning workflow with its own agents, tools, and PDF output.
- Travel Workflow · Separate trip-planning workflow with its own agents and tools.
app/travel_system/workflow.py - Destination Agent · Researches destinations and destination-specific context.
app/travel_system/agents/destination_agent.py - Date & Budget · Reasons about timing and budget constraints for the trip.
app/travel_system/agents/date_budget_agent.py - Trip Coordinator · Combines travel sub-results into the final itinerary plan.
app/travel_system/agents/coordinator_agent.py - PDF Saver · Writes itinerary PDFs for travel plans.
app/travel_system/utils/pdf_saver.py
Retrieval Data
Persistent vector store and processed corpora used by RAG branches.
- RAG Tools · Retrieval and context formatting helpers for the Resmi Gazete path.
app/tools/rag_tools.py - Vector Store · Persistent Chroma-backed storage for embeddings and retrieved chunks.
app/storage/database.py - Embeddings · Prebuilt embedding store used by local retrieval paths.
data/embeddings
Data Prep
Offline scripts that fetch, process, and embed source content.
- Raw Data · Fetched source content for news and Resmi Gazete.
data/raw - Processed Data · Structured JSONL corpora prepared for embedding and retrieval.
data/processed - Fetchers · Source ingestion scripts for news and official gazette content.
scripts/news_fetcher.py - Process Data · Transforms raw source files into structured processed corpora.
scripts/process_data.py - Build Embeddings · Generates vector embeddings from processed data.
scripts/generate_embeddings.py
Configuration
Runtime and API settings.
- Agent Config · Agent and orchestration configuration.
configs/agent_config.py - App Config · Application-level runtime settings.
configs/app_config.py - API Config · External service and API settings.
configs/api_config.py
Connections 29
- Streamlit UI → Main Graph: submit chat · User input and uploads are handed to the orchestration graph.
- Main Graph → Supervisor: route request · The main graph begins by invoking the supervisor router.
- Supervisor → Resmi Gazete: official text · Routes legal/government queries to the Resmi Gazete branch.
- Supervisor → News Agent: news / knowledge · Routes live information and general knowledge queries to the news branch.
- Supervisor → Doc RAG: uploaded docs · Routes document questions to the uploaded-document RAG branch.
- Supervisor → Travel Bridge: travel request · Routes trip-planning requests into the travel subsystem.
- Supervisor → Fallback: out of scope · Uses fallback handling when no specialized branch fits.
- Main Graph → Chat State: store state · The workflow reads and updates shared conversation state.
- Main Graph → LLM Setup: instantiate model · Branches use the centralized model setup.
- Resmi Gazete → RAG Tools: retrieve context · Resmi Gazete questions pull context through retrieval helpers.
- RAG Tools → Vector Store: query vectors · Retrieval helpers access the persistent vector store.
- Vector Store → Embeddings: load embeddings · The database layer serves prebuilt vector data from disk.
- News Agent → External APIs: search tools · News/general knowledge answers rely on external search and knowledge tools.
- Doc RAG → Vector Store: local retrieval · Uploaded-document QA also queries the shared vector store boundary.
- Travel Bridge → Travel Workflow: invoke subworkflow · Travel requests are delegated to the dedicated planning workflow.
- Travel Workflow → Destination Agent: destination stage · The travel workflow runs destination research first.
- Travel Workflow → Date & Budget: constraint stage · It reasons over dates and budget constraints.
- Travel Workflow → Trip Coordinator: compose plan · The coordinator assembles the final travel itinerary.
- Trip Coordinator → PDF Saver: export PDF · Final plans can be rendered to a PDF file.
- PDF Saver → Plans: save plan · Generated itineraries are written to the plans directory.
- PDF Saver → Fonts: use fonts · PDF rendering depends on packaged font assets.
- Fetchers → Raw Data: fetch source · Ingestion scripts populate the raw corpora directories.
- Process Data → Raw Data: read raw · Processing reads from fetched raw content.
- Process Data → Processed Data: write chunks · Processed JSONL corpora are written for later embedding.
- Build Embeddings → Processed Data: read processed · Embedding generation consumes processed corpora.
- Build Embeddings → Embeddings: write vectors · Generated embeddings are stored under the vector data directory.
- Streamlit UI → App Config: runtime settings · The UI boundary is shaped by application configuration.
- Supervisor → Agent Config: agent rules · Routing and agent behavior are driven by agent configuration.
- News Agent → API Config: api settings · External search integrations are configured via API settings.