--- title: RAG Agent emoji: 🕵🏻‍♂️ colorFrom: indigo colorTo: indigo sdk: gradio sdk_version: 6.0.1 app_file: main.py pinned: false hf_oauth: true hf_oauth_expiration_minutes: 480 --- # 📁 Project Structure ``` mai-rag-agent/ │ ├── 📂 agent/ # Core agent logic │ ├── graph.py # LangGraph workflow definition │ ├── nodes.py # Agent nodes (router, vectordb, web_search, generate) │ ├── prompts.py # System prompts and templates │ ├── state.py # Agent state management (AgentState, RAG_method) │ └── tools.py # Tool definitions (Tavily, Wikipedia, ArXiv, ChromaDB) │ ├── 📂 core/ # Business logic layer │ ├── llm.py # LLM initialization (Anthropic Claude) │ └── rag_agent.py # Main RAGAgent class with graph orchestration │ ├── 📂 ui/ # User interface │ └── gradio_components.py # Gradio web interface components │ ├── 📂 knowledge_base/ # scripts for setting up Chroma │ ├── 📂 chroma_data/ # Artifacts for Chroma │ ├── 📂 docs/ # Source documents (PDFs, text files) │ ├── 📄 main.py # Application entry point ├── 📄 config.py # Configuration settings ├── 📄 test_scripts.py # Agent testing script │ ├── 📄 .env # Environment variables (API keys) ├── 📄 .gitignore # Git ignore rules │ ├── 📄 requirements.txt # Python dependencies ├── 📄 pyproject.toml # Project metadata (if using uv) │ └── 📄 README.md # Project documentation (this file) ``` ## 📋 Key Components ### 🤖 Agent Module (`agent/`) - **`graph.py`**: Defines the LangGraph workflow with conditional routing - **`nodes.py`**: Implements agent nodes: - `router_node`: Classifies queries (RAG/WEBSEARCH/GENERAL) - `vectordb_node`: Retrieves from local ChromaDB - `web_search_agent_node`: Executes web searches - `generate_node`: Generates final responses - **`state.py`**: Defines `AgentState` with message history, routing method, and context - **`tools.py`**: Tool implementations for Tavily, Wikipedia, ArXiv, and ChromaDB - **`prompts.py`**: System prompts for routing and generation ### 🎯 Core Module (`core/`) - **`llm.py`**: Initializes the LLM (Anthropic Claude Sonnet 4.5) - **`rag_agent.py`**: Main `RAGAgent` class that orchestrates the graph ### 🖥️ UI Module (`ui/`) - **`gradio_components.py`**: Gradio web interface with chat functionality ### 📊 Data Module (`data/`) - **`documents/`**: Raw source documents for ingestion - **`chroma_db/`**: Persisted vector embeddings ### ⚙️ Configuration - **`config.py`**: Centralized configuration (model names, paths, API settings) - **`.env`**: API keys (ANTHROPIC_API_KEY, TAVILY_API_KEY) ### 🚀 Entry Points - **`main.py`**: Launches the Gradio UI - **`test_scripts.py`**: Runs agent tests ## 🔄 Data Flow ``` User Query ↓ [Router Node] → Classifies intent (RAG/WEBSEARCH/GENERAL) ↓ ├─→ [VectorDB Node] → Retrieves from ChromaDB → [Generate Node] ├─→ [Web Search Agent] → Calls Tavily/Wikipedia → [Generate Node] └─→ [Generate Node] → Uses LLM knowledge only ↓ Response to User ``` ## 🛠️ Technology Stack - **LangChain**: Framework for LLM applications - **LangGraph**: Workflow orchestration - **Anthropic Claude**: LLM (Sonnet 4.5) - **ChromaDB**: Vector database - **Gradio**: Web UI framework - **HuggingFace**: Embeddings model - **Tavily**: Web search API - **UV**: Python package manager ## 🚀 Quick Start with UV ### Prerequisites - Python 3.10+ - UV package manager ([Install UV](https://github.com/astral-sh/uv)) - API Keys: Anthropic, Tavily ### 1️⃣ Clone the Repository ```bash git clone https://github.com/yourusername/mai-rag-agent.git cd mai-rag-agent ``` ### 2️⃣ Create Virtual Environment with UV ```bash # Create a new virtual environment uv venv # Activate the environment source .venv/bin/activate # Linux/macOS # or .venv\Scripts\activate # Windows ``` ### 3️⃣ Install Dependencies ```bash # Install all dependencies from requirements.txt uv pip install -r requirements.txt # Or install directly from pyproject.toml (if available) uv pip install -e . ``` ### 4️⃣ Set Up Environment Variables ```bash # Copy example environment file cp .env.example .env # Edit .env and add your API keys nano .env # or use your preferred editor ``` **Required environment variables:** ```bash GOOGLE_API_KEY=xxxxxxxxxxxxx # Gemini API key TAVILY_API_KEY=tvly-xxxxxxxxxxxxx # Enable web search ``` ### 5️⃣ Prepare Data ```bash # Create necessary directories mkdir -p data/documents data/chroma_db # Add your documents to data/documents/ # Then run ingestion (if you have an ingestion script) # python ingest_data.py ``` ### 6️⃣ Run the Application ```bash # Launch the Gradio UI python main.py ``` ### 7️⃣ Run Tests (Optional) ```bash # Test the agent functionality python test_scripts.py ``` --- ## 🐳 Quick Start with Dev Container (Alternative) If you're using VS Code with Dev Containers: ```bash # 1. Open in VS Code code . # 2. Reopen in Container # Command Palette (Ctrl+Shift+P) → "Dev Containers: Reopen in Container" # 3. Inside container, install dependencies uv pip install -r requirements.txt # 4. Set up .env file cp .env.example .env # Edit .env with your API keys # 5. Run the app python main.py ``` --- ## 📦 UV-Specific Commands ```bash # Update all dependencies uv pip install --upgrade -r requirements.txt # List installed packages uv pip list # Freeze current environment uv pip freeze > requirements.txt # Install a new package uv pip install package-name # Uninstall a package uv pip uninstall package-name # Sync environment (removes unused packages) uv pip sync requirements.txt ``` --- ## 🔧 Troubleshooting ### Issue: `uv` command not found ```bash # Install UV curl -LsSf https://astral.sh/uv/install.sh | sh # Add to PATH (if needed) export PATH="$HOME/.cargo/bin:$PATH" ``` ### Issue: API key not loading ```bash # Check if .env exists cat .env | grep -i api # Ensure no typos in variable names # Should be: ANTHROPIC_API_KEY and TAVILY_API_KEY ``` ### Issue: ChromaDB not found ```bash # Ensure data directories exist mkdir -p data/chroma_db # Check permissions chmod -R 755 data/ ``` ### Issue: Port 7860 already in use ```bash # Find and kill the process lsof -ti:7860 | xargs kill -9 # Or use a different port in main.py # demo.launch(server_port=7861) ``` --- ## 🎯 Next Steps 1. ✅ Add your documents to `data/documents/` 2. ✅ Configure embeddings model in `config.py` 3. ✅ Customize prompts in `agent/prompts.py` 4. ✅ Test with sample queries in the Gradio UI 5. ✅ Deploy to production (see deployment docs) --- ## 📚 Additional Resources - [UV Documentation](https://github.com/astral-sh/uv) - [LangGraph Docs](https://langchain-ai.github.io/langgraph/) - [Gemini API](https://ai.google.dev/gemini-api/docs/api-key) - [Tavily API](https://docs.tavily.com/) - [ChromaDB Docs](https://docs.trychroma.com/) ## 📚 Reference (Used for demo as document in vector store) 1. Wei, H., Sun, Y., & Li, Y. (2025). Deepseek-ocr: Contexts optical compression. arXiv preprint arXiv:2510.18234. 2. Chen, X., Chu, F. J., Gleize, P., Liang, K. J., Sax, A., Tang, H., ... & SAM 3D Team. (2025). SAM 3D: 3Dfy Anything in Images. arXiv preprint arXiv:2511.16624. 3. Carion, N., Gustafson, L., Hu, Y. T., Debnath, S., Hu, R., Suris, D., ... & Feichtenhofer, C. (2025). SAM 3: Segment Anything with Concepts. arXiv preprint arXiv:2511.16719. 4. Yan, B. Y., Li, C., Qian, H., Lu, S., & Liu, Z. (2025). General Agentic Memory Via Deep Research. arXiv preprint arXiv:2511.18423. 5. Zhang, S., Fan, J., Fan, M., Li, G., & Du, X. (2025). Deepanalyze: Agentic large language models for autonomous data science. arXiv preprint arXiv:2510.16872.