README.md

---
title: LangGraph Multi-Agent Orchestrator
emoji: 🧭
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
  - streamlit
  - langgraph
  - langchain
  - groq
  - sqlite
  - neo4j
short_description: A multi-agent chat app powered by LangGraph.
---

# 🧭 LangGraph Multi-Agent Orchestrator (Streamlit)

A **multi-agent chat orchestrator** built with **LangGraph + LangChain**, wrapped in a **Streamlit** UI.

It routes each user message to the best specialist:

- **SQL Agent** → relational questions over **SQLite**
- **Graph Agent** → relationship questions over **Neo4j** (Cypher)
- **Tools Agent** → **Web / Wikipedia / arXiv / Calculator** assisted answers
- **General** → normal LLM chat/explanations

---

## ✨ What you can do

### 1) Router Chat (auto orchestration)
A single chat experience where a router decides which agent to run each turn:
- SQL / Graph / Tools / General
- Handles follow-up questions by rewriting them into standalone queries

### 2) SQL Agent (SQLite analytics)
Ask questions like:
- “Top 10 students by average score in 2025-Fall”
- “Which course has the lowest average score?”
- “Who has attendance below 70%?”

### 3) Graph Agent (Neo4j Cypher Q&A)
Ask relationship-heavy questions like:
- “Movies that share actors with The Matrix”
- “Shortest path between Tom Hanks and Tom Cruise”
- “Actors who worked with both X and Y”

> Graph Agent is optional — it only works if Neo4j credentials are configured.

### 4) Tools Agent (Web + Wikipedia + arXiv + Calculator)
Useful for open-world questions outside your databases:
- quick research + citations from tools (inside the agent)
- safe arithmetic calculator tool for quick computations

---

## 🧱 Architecture (high-level)

```

User → Router (LangGraph) → one route:
├─ SQL Agent   (SQLite, read-only)
├─ Graph Agent (Neo4j → Cypher → answer grounded in results)
├─ Tools Agent (DuckDuckGo + Wikipedia + arXiv + Calculator)
└─ General     (LLM-only)

```

## 🚀 Run locally (Python)

### 1) Install
```bash
git clone https://github.com/sparklerz/LangGraph-Multi-Agent-Orchestrator
cd LangGraph-Multi-Agent-Orchestrator

pip install -r requirements.txt
````

### 2) Configure environment variables

Create a `.env` file:

```bash
# Required
GROQ_API_KEY="YOUR_GROQ_KEY"

# Recommended (the repo includes school.db)
SQLITE_PATH="school.db"

# Optional model override (Groq)
LLM_MODEL="meta-llama/llama-4-maverick-17b-128e-instruct"

# Optional: enable Neo4j Graph Agent
NEO4J_URI="neo4j+s://97329836.databases.neo4j.io"
NEO4J_USERNAME="neo4j"
NEO4J_PASSWORD="password"

# Optional: tool config
WIKI_DOC_CHARS="2000"

# Optional: debugging (shows more internal steps)
DEBUG="1"
```

### 3) Run

```bash
streamlit run app.py
```

---

## 🗄️ SQLite database (SQL Agent)

This repo ships with a demo SQLite DB: **`school.db`**.

If you see “DB not found” errors:

* ensure `school.db` exists in the repo root
* set `SQLITE_PATH=school.db`

### Optional: regenerate / reseed the DB

```bash
python sqlite.py
```

> `sqlite.py` supports env overrides like `SQLITE_DB`, `NUM_STUDENTS`, etc.

---

## 🕸️ Neo4j setup (Graph Agent)

Graph Agent is optional. To enable it, set:

* `NEO4J_URI`
* `NEO4J_USERNAME`
* `NEO4J_PASSWORD`

**Tip:** Neo4j’s “Movies” dataset is perfect for testing locally.

If Neo4j is not configured, Graph Agent calls will fail gracefully (and the rest of the app still works).

---
## Hugging Face Spaces (Docker) deployment

This repo is configured for **Docker Spaces** using the .github/workflows/main.yml.

### 1) Create the Space
1. Create a new Space on Hugging Face
2. Choose **SDK → Docker**
3. Push / sync this repository to the Space

### 2) Add required Secret
In your Space: **Settings → Variables and secrets**
- Add **Secret**: `GROQ_API_KEY` (required)

### 3) Add Variables (recommended)

Add **Variables**:

* `SQLITE_PATH=school.db`
* Optional: `LLM_MODEL=meta-llama/llama-4-maverick-17b-128e-instruct`
* Optional: `WIKI_DOC_CHARS=2000`
* Optional: `DEBUG=1`

### 4) Neo4j on Spaces (optional)

If you want Graph Agent on Spaces, your Neo4j must be reachable from the public internet.
Add these as **Secrets**:

* `NEO4J_URI`
* `NEO4J_USERNAME`
* `NEO4J_PASSWORD`

> If you don’t set Neo4j creds, just avoid Graph-only questions (Router will still work for SQL/Tools/General).

---

## ⚙️ Configuration reference

| Variable         | Default                                         | Purpose                                              |
| ---------------- | ----------------------------------------------- | ---------------------------------------------------- |
| `GROQ_API_KEY`   | (none)                                          | **Required**. Enables Groq LLM calls                 |
| `LLM_MODEL`      | `meta-llama/llama-4-maverick-17b-128e-instruct` | Default Groq model                                   |
| `SQLITE_PATH`    | `student.db`                                    | Path to SQLite DB (set to `school.db` for this repo) |
| `NEO4J_URI`      | (empty)                                         | Neo4j connection URI                                 |
| `NEO4J_USERNAME` | (empty)                                         | Neo4j username                                       |
| `NEO4J_PASSWORD` | (empty)                                         | Neo4j password                                       |
| `WIKI_DOC_CHARS` | `2000`                                          | Wikipedia doc truncation size for tools              |
| `DEBUG`          | `0`                                             | Show more intermediate/debug info                    |

---

## 🧪 Example prompts to try

### Router Chat

* “Show the top 10 students by average score in 2025-Fall”
* “Now only Computer Science students”
* “Explain what LangGraph is, in simple terms”
* “Summarize the latest research on graph RAG” (tools)

### SQL Agent

* “List the tables”
* “Attendance below 70% in 2025-Fall”
* “Which department has the highest average course score?”

### Graph Agent

* “Find movies that share at least 2 actors with The Matrix”
* “Shortest connection between Tom Hanks and Tom Cruise”

### Tools Agent

* “What’s the difference between BM25 and dense retrieval?”
* “Find 3 papers on multi-agent orchestration and summarize”
* “(12*(3+4))/2”

---

## 🧯 Troubleshooting

* **Missing `GROQ_API_KEY`**
  Set it in `.env` (local) or Space **Secrets** (HF).

* **SQLite DB not found**
  Ensure the file exists in the repo root and `SQLITE_PATH` matches (recommended: `school.db`).

* **Neo4j errors**
  Confirm Neo4j is running and reachable, credentials are correct, and the dataset exists.

* **Tools Agent can’t access web**
  Some hosted environments restrict outbound requests. If web tools fail, try Router/SQL/General flows.

---

## 📄 License

Apache-2.0