🧠 Deep Research Agent Swarm

A dynamic, true-parallel AI agent swarm architecture powered by Google Gemini and Streamlit.

Welcome to the Deep Research Agent Swarm. This project implements a cutting-edge "Fan-Out / Fan-In" architecture that leverages large language models not just as chat bots, but as dynamic, autonomous planners and parallel workers. It comes with a beautiful, real-time "localhost browser" UI powered by Streamlit.

✨ Features

• Dynamic Task Planning: A Master Coordinator breaks down complex tasks into manageable sub-tasks using Pydantic JSON structured outputs.
• True Parallel Execution: Subagents (Researcher, Analyst, Writer) are spawned dynamically and run simultaneously via Python's asyncio.gather().
• Search Integration: The Researcher agent utilizes the built-in Google Search tool for grounded, factual data gathering.
• Synthesis Engine: A powerful final agent merges all disparate parallel findings into one hyper-coherent, beautifully formatted markdown report.
• Localhost Browser UI: A slick Streamlit dashboard to monitor the Swarm's thoughts, plans, and executions in real-time.

---

🏗️ Architecture Flow

graph TD
    A[User Prompt via Web UI] -->|Sends Task| B(Coordinator Agent)
    B -->|Generates JSON Plan| C{Dynamic Agent Router}
    
    C -->|Spawn & Async Run| D[Researcher Agent]
    C -->|Spawn & Async Run| E[Analyst Agent]
    C -->|Spawn & Async Run| F[Writer Agent]
    
    D -->|Factual Data| G((Synthesizer Agent))
    E -->|Trend Analysis| G
    F -->|Narrative Draft| G
    
    G -->|Merge & Format| H[Final Markdown Report]

Loading

---

📂 Repository Structure

deep_research_swarm/
├── app.py                # 🌐 Streamlit Web UI (Localhost Browser)
├── requirements.txt      # 📦 Dependencies
├── .env                  # 🔑 API Keys (Git ignored)
├── core/
│   ├── coordinator.py    # 🧠 Dynamic Planner
│   ├── swarm.py          # ⚡ Async Orchestrator
│   └── agent.py          # 🤖 Google GenAI Wrapper
└── agents/               # 📝 Modular System Prompts (Markdown)
    ├── coordinator.md
    ├── researcher.md
    ├── analyst.md
    ├── writer.md
    └── synthesizer.md

---

🚀 Setup & Installation

1. Clone the repository:

git clone https://github.com/yourusername/deep-research-swarm.git
cd deep-research-swarm

2. Install Dependencies: We recommend using a virtual environment.

pip install -r requirements.txt

3. Configure API Key: Create a .env file in the root directory and add your Google Gemini API key:

GOOGLE_API_KEY="AIzaSyYourApiKeyHere"

(Don't have one? Get it from Google AI Studio)

---

🖥️ Usage

Fire up the Localhost Browser UI by running:

streamlit run app.py

1. Open the local URL provided by Streamlit (usually http://localhost:8501).
2. Enter your complex research topic.
3. Watch the Coordinator generate its plan, expand the logs to see parallel agent execution, and download the final synthesized report directly from the browser!

---

🛠️ Customization

Want to add a new type of agent (e.g., a FactChecker or Coder)?

1. Create a new prompt in the agents/ folder.
2. Update the core/swarm.py factory method to recognize the new role.
3. Watch the Coordinator automatically start utilizing your new agent!

---

Built for the future of agentic AI workflows.