{"repo": "alisherizmukhan/multi-agent-test1", "files": {"README.md": {"5a3296a185027f47b88525642aaacf0a5b40d03d": {"t": 1785746443.738121, "n": 9085, "h": "a1f3b5f75df7ea06", "c": "# Multi-Agent Research Assistant\n\nAn AI-powered research assistant that coordinates multiple specialized agents to answer complex questions. Built with LangGraph, LangChain, FastAPI, and PostgreSQL.\n\n---\n\n## What is LangGraph?\n\nLangGraph is a library for building stateful, multi-step AI applications as graphs. Instead of a single LLM call, you define a workflow where:\n\n- **Nodes** are functions (agents) that do some work\n- **Edges** are connections that define the order agents run\n- **State** is a shared object passed between every node\n\nThis lets you build workflows where agents talk to each other, loop back on bad results, or take different paths depending on what happened.\n\n---\n\n## What are Multi-Agent Systems?\n\nA multi-agent system is when multiple AI models (or instances of the same model) each have a specific role and work together to solve a problem.\n\nInstead of asking one LLM \"answer this complex question\", you split the work:\n\n| Agent      | Job                                    |\n|------------|----------------------------------------|\n| Planner    | Understands the question, makes a plan |\n| Researcher | Gathers and organizes information      |\n| Writer     | Writes a draft answer                  |\n| Reviewer   | Reviews and improves the draft         |\n\nEach agent does one thing well. The output of one becomes the input of the next.\n\n---\n\n## Architecture\n\n```\nUser Question\n      │\n      ▼\n┌──────────┐     ┌────────────┐     ┌────────┐     ┌──────────┐\n│ Planner  │────▶│ Researcher │────▶│ Writer │────▶│ Reviewer │\n│  Agent   │     │   Agent    │     │ Agent  │     │  Agent   │\n└──────────┘     └────────────┘     └────┬───┘     └────┬─────┘\n                                         │               │\n                                         │◀──────────────┘\n                                         │  NEEDS_REVISION (max 2x)\n                                         │\n                                         ▼ APPROVED\n                                    Final Answer\n                                         │\n                                         ▼\n                                    PostgreSQL\n                                   (save history)\n```\n\n---\n\n## Folder Structure\n\n```\nmulti-agent/\n├── app/\n│   ├── agents/             # One file per agent\n│   │   ├── planner.py\n│   │   ├── researcher.py\n│   │   ├── writer.py\n│   │   └── reviewer.py\n│   ├── graph/              # LangGraph setup\n│   │   ├── state.py        # Shared state definition\n│   │   └── workflow.py     # Graph nodes, edges, routing\n│   ├── services/           # Business logic\n│   │   └── research_service.py\n│   ├── api/                # FastAPI routes\n│   │   └── routes.py\n│   ├── schemas/            # Pydantic request/response models\n│   │   └── research.py\n│   ├── core/               # Configuration\n│   │   └── config.py\n│   └── main.py             # FastAPI app entry point\n├── docs/\n│   └── architecture.md\n├── tests/\n│   └── test_api.py\n├── docker/\n│   └── postgres/\n│       └── init.sql\n├── README.md\n├── PROJECT_EXPLANATION.md\n├── requirements.txt\n├── Dockerfile\n└── docker-compose.yml\n```\n\n---\n\n## OpenRouter Setup\n\nThis project uses [OpenRouter](https://openrouter.ai) as the LLM provider. OpenRouter gives you access to hundreds of models (DeepSeek, Llama, Qwen, Claude, GPT, Gemini, etc.) through a single OpenAI-compatible API.\n\n### 1. Get an API key\n\n1. Go to [https://openrouter.ai/keys](https://openrouter.ai/keys)\n2. Sign in or create a free account\n3. Click **Create Key** and copy it\n\n### 2. Configure .env\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and paste your key:\n\n```\nOPENROUTER_API_KEY=sk-or-v1-your_key_here\nLLM_PROVIDER=openrouter\nLLM_MODEL=deepseek/deepseek-chat-v3\nOPENROUTER_BASE_URL=https://openrouter.ai/api/v1\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/research_db\n```\n\n### 3. Switch models\n\nChange only `LLM_MODEL` in `.env` — no code changes required:\n\n| Model | Description |\n|-------|-------------|\n| `deepseek/deepseek-chat-v3` | Default — fast, cheap, strong reasoning |\n| `qwen/qwen3-32b` | Alibaba Qwen3, strong at instructions |\n| `meta-llama/llama-3.3-70b-instruct` | Meta Llama 3.3, open-weight |\n| `anthropic/claude-3-5-sonnet` | Claude 3.5 Sonnet via OpenRouter |\n| `openai/gpt-4o-mini` | OpenAI GPT-4o Mini via OpenRouter |\n\nBrowse all available models at [https://openrouter.ai/models](https://openrouter.ai/models).\n\n---\n\n## Local Setup (without Docker)\n\n### 1. Clone and enter the project\n\n```bash\ncd multi-agent\n```\n\n### 2. Create a virtual environment\n\n```bash\npython -m venv venv\nsource venv/bin/activate        # macOS/Linux\nvenv\\Scripts\\activate           # Windows\n```\n\n### 3. Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### 4. Configure environment variables\n\n```bash\ncp .env.example .env\n# Edit .env and add your OPENROUTER_API_KEY\n```\n\n### 5. Start PostgreSQL\n\nMake sure you have a PostgreSQL instance running locally, or use Docker just for the DB:\n\n```bash\ndocker run -d \\\n  --name research-db \\\n  -e POSTGRES_USER=postgres \\\n  -e POSTGRES_PASSWORD=postgres \\\n  -e POSTGRES_DB=research_db \\\n  -p 5432:5432 \\\n  postgres:15\n```\n\n### 6. Run the app\n\n```bash\nuvicorn app.main:app --reload\n```\n\nThe app starts at `http://localhost:8000`.\n\n---\n\n## Docker Setup (recommended)\n\n### 1. Copy and fill in environment variables\n\n```bash\ncp .env.example .env\n# Edit .env and add your OPENROUTER_API_KEY\n```\n\n### 2. Build and start all services\n\n```bash\ndocker compose up --build\n```\n\nThis starts:\n- **app** — FastAPI server on port 8000\n- **db** — PostgreSQL on port 5432\n\n### 3. Stop everything\n\n```bash\ndocker compose down\n```\n\nTo also remove the database volume:\n\n```bash\ndocker compose down -v\n```\n\n---\n\n## API Examples\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\nResponse:\n```json\n{\"status\": \"ok\"}\n```\n\n### Run Research\n\n```bash\ncurl -X POST http://localhost:8000/research \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"question\": \"Explain machine learning\"}'\n```\n\nResponse:\n```json\n{\n  \"plan\": \"1. Define what machine learning is...\",\n  \"research_notes\": \"## Key Concepts\\n- Machine learning is a subset of AI...\",\n  \"draft_answer\": \"Machine learning is the practice of...\",\n  \"final_answer\": \"Machine learning (ML) is a branch of artificial intelligence...\"\n}\n```\n\n### Interactive API Docs\n\nOpen `http://localhost:8000/docs` in your browser for the Swagger UI.\n\n---\n\n## Running Tests\n\n```bash\npytest tests/ -v\n```\n\n---\n\n## Environment Variables\n\n| Variable               | Required | Default                                               | Description                          |\n|------------------------|----------|-------------------------------------------------------|--------------------------------------|\n| `OPENROUTER_API_KEY`   | Yes      | —                                                     | Your OpenRouter API key              |\n| `LLM_MODEL`            | No       | `deepseek/deepseek-chat-v3`                           | Model to use (any OpenRouter model)  |\n| `LLM_PROVIDER`         | No       | `openrouter`                                          | LLM provider name                    |\n| `OPENROUTER_BASE_URL`  | No       | `https://openrouter.ai/api/v1`                        | OpenRouter API base URL              |\n| `DATABASE_URL`         | No       | `postgresql://postgres:postgres@localhost:5432/research_db` | PostgreSQL connection string   |\n\n---\n\n## Technologies Used\n\n| Technology       | Purpose                               |\n|------------------|---------------------------------------|\n| Python 3.12      | Core language                         |\n| FastAPI          | HTTP API framework                    |\n| LangChain        | LLM interaction and prompt management |\n| LangGraph        | Multi-agent workflow orchestration    |\n| OpenRouter       | LLM gateway (access to 100+ models)  |\n| PostgreSQL       | Storing research history              |\n| SQLAlchemy       | Database ORM                          |\n| Pydantic         | Data validation and settings          |\n| Uvicorn          | ASGI server                           |\n| Docker           | Containerization                      |\n\n---\n\n## Future Improvements\n\n- **Add web search** — give the Researcher agent access to real-time web search tools (e.g., Tavily, SerpAPI)\n- **Streaming responses** — stream each agent's output to the client as it is generated\n- **Authentication** — add API key or JWT-based auth\n- **Rate limiting** — prevent abuse with per-user request limits\n- **Async database** — replace sync SQLAlchemy with `asyncpg` + SQLAlchemy async for better performance\n- **Research history endpoint** — expose `GET /history` to retrieve past research sessions\n- **Caching** — cache results for identical questions to reduce API costs\n- **Monitoring** — add LangSmith tracing to observe agent behavior in production\n- **Better revision logic** — have the Reviewer return structured feedback per section, not just free text\n- **Agent memory** — give agents access to previous conversation turns for follow-up questions\n"}}}}