ThinkTank

A multi-agent meeting coordinator that orchestrates domain-specific AI agents to research, debate, and synthesize decisions on complex topics. Agents ingest documents, query a shared knowledge graph, and collaborate through configurable protocols — all streamed in real time to a React dashboard.

Architecture

┌─────────────────────────────────────────────────────────┐
│ React + ReactFlow Frontend (Vite, port 5173)           │
│ Live meeting canvas • Agent cards • Detail drawer       │
└──────────────┬──────────────────────┬───────────────────┘
                 REST /api    WebSocket /ws
┌──────────────┴──────────────────────┴───────────────────┐
│ FastAPI Backend (uvicorn, port 8000)                    │
│ Projects / Meetings / Agents CRUD • Run orchestration   │
├──────────────────────────────────────────────────────────┤
│ Coordinator (LangGraph StateGraph)                      │
│ Planner → DAG → Protocol Dispatch → Analyzer → Summary  │
├────────────┬──────────────┬──────────────────────────────┤
│ PostgreSQL │ ChromaDB     │ FalkorDB (Knowledge Graph)   │
│ (metadata) │ (vectors)    │ (claims, entities, decisions)│
│  Docker    │ (embedded)   │  Docker                      │
└────────────┴──────────────┴──────────────────────────────┘

Protocols: single_agent · parallel_exploration · serial_refinement · critic_review · adversarial_debate

Prerequisites

Tool	Version	Purpose
Docker	20+	PostgreSQL & FalkorDB containers
Python	3.11+	Backend, agents, ingestion
Node.js	18+	Frontend dev server (optional)
Git	any	Source control

Note: PostgreSQL and FalkorDB run in Docker containers — no manual installation required.

Setup

Quick Start (One Command)

macOS:

git clone <repo-url> ThinkTank_v2
cd ThinkTank_v2
./install.sh

Linux:

git clone <repo-url> ThinkTank_v2
cd ThinkTank_v2
./install-linux.sh

The installation script handles everything:

Checks prerequisites (Docker, Python, Node.js)
Starts PostgreSQL and FalkorDB in Docker containers
Creates Python virtual environment and installs dependencies
Runs database migrations
Installs frontend dependencies

Note: After installation, edit .env and add your TAMUS_AI_CHAT_API_KEY.

Migrating an Existing Database

If you have an existing PostgreSQL database and want to preserve your data:

./scripts/migrate_db_to_docker.sh

This script:

Backs up your existing database
Stops local PostgreSQL (prompts you)
Starts Docker containers
Restores the backup to the Docker PostgreSQL container

Manual Setup (Alternative)

If you prefer manual setup or need custom configuration:

1. Clone and create `.env`

git clone <repo-url> ThinkTank_v2
cd ThinkTank_v2

Create a .env file (copy from example):

cp .env.example .env
# Edit .env and add your TAMUS_AI_CHAT_API_KEY

Or create manually:

# ── LLM API ──────────────────────────────────────────────
TAMUS_AI_CHAT_API_KEY=<your-api-key>
TAMUS_AI_CHAT_API_ENDPOINT=https://chat-api.tamu.ai

# Models (adjust to your provider's model names)
TAMUS_AI_MODEL_LARGE=protected.gpt-5.1
TAMUS_AI_MODEL_MEDIUM=protected.o4-mini
TAMUS_AI_MODEL_IMAGE=protected.gemini-2.5-flash

# ── PostgreSQL (Docker) ──────────────────────────────────
DATABASE_URL=postgresql+asyncpg://thinktank:thinktank@localhost/thinktank
DB_ECHO=false

# ── FalkorDB (Docker) ────────────────────────────────────
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_PASSWORD=

# ── File Uploads ─────────────────────────────────────────
UPLOAD_DIR=./uploads

2. Start Docker containers

docker compose up -d

This launches both PostgreSQL (port 5432) and FalkorDB (port 6379). Verify:

docker ps  # should show thinktank-postgres and thinktank-falkordb

3. Install Python dependencies

python3 -m venv .venv
source .venv/bin/activate  # macOS / Linux
pip install --upgrade pip
pip install -r requirements.txt

Note: unstructured[pdf,docx,html] and sentence-transformers are large packages — the first install may take several minutes and download ~1 GB of model weights.

4. Run database migrations

source .venv/bin/activate
alembic upgrade head

5. Install frontend dependencies

cd frontend && npm install && cd ..

Starting the Application

Terminal 1 — Backend API:

source .venv/bin/activate
uvicorn server:app --reload
# or: uvicorn server:app --reload --host 0.0.0.0 --port 8000

Terminal 2 — Frontend dev server:

cd frontend
npm run dev

Open http://localhost:5173 in your browser.

Stopping Services

macOS:

./stop.sh

Linux:

./stop-linux.sh

Or directly: docker-compose down

Usage

Create a Project — top-level container (e.g., "Server Procurement Q1").
Create Agents — each agent has a title, role description, and its own document store. Upload PDFs/DOCX/HTML via the agent management page; files are ingested into ChromaDB automatically.
Create a Meeting — set a goal (research question) and assign 2–5 agents.
Run the Meeting — the coordinator plans tasks, dispatches them across agents using the best protocol, analyzes results, and loops until all levels of the DAG are resolved.
View Results — the live canvas shows task nodes, agent progress events, and the final summary in the detail drawer.

Project Structure

ThinkTank_v2/
├── server.py              # FastAPI app (REST + WebSocket)
├── main.py                # Uvicorn entrypoint shim
├── requirements.txt       # Python dependencies
├── docker-compose.yml     # PostgreSQL + FalkorDB containers
├── install.sh             # One-command setup script
├── stop.sh                # Stop services script
├── alembic.ini            # DB migration config
├── manage_db.py           # CLI: wipe / list / remove DB objects
├── .env                   # Secrets (git-ignored)
│
├── backend/
│   ├── database.py        # Async SQLAlchemy engine + session
│   ├── models.py          # Project, Meeting, Agent, RunState
│   ├── schemas.py         # Pydantic request/response models
│   └── routes/            # CRUD routers (projects, meetings, agents)
│
├── agents/
│   ├── coordinator/       # LangGraph orchestration
│   │   ├── graph.py       # StateGraph: plan → execute → analyze → summarize
│   │   ├── planner.py     # Task DAG generation
│   │   ├── analyzer.py    # Result evaluation + DAG extension
│   │   ├── dag.py         # DAG level tracking
│   │   ├── decision_synthesizer.py
│   │   ├── historian.py   # KG persistence after each level
│   │   ├── kg_client.py   # FalkorDB read/write
│   │   ├── events.py      # WebSocket event emitter
│   │   ├── interrupt_manager.py  # Pause / resume / HIL
│   │   └── prompts/       # LLM prompt templates
│   │
│   ├── domain_specific/   # Per-agent RAG pipeline
│   │   ├── workflow.py    # LangGraph agent workflow (decompose → retrieve → rerank → synthesize)
│   │   ├── retrieval.py   # ChromaDB + BM25 hybrid retrieval
│   │   ├── rerank.py      # CrossEncoder reranking (singleton)
│   │   ├── compression.py # Context compression
│   │   ├── synthesis.py   # LLM answer generation
│   │   └── subquery.py    # Query decomposition
│   │
│   └── ingestion/         # Document processing pipeline
│       ├── pipeline.py    # Orchestrates parse → chunk → embed → store
│       ├── document_parser.py
│       ├── chunking.py
│       ├── chroma_store.py
│       └── image_processor.py
│
├── scripts/
│   └── migrate_db_to_docker.sh  # Database migration script
│
├── frontend/              # React + TypeScript + Vite
│   ├── src/
│   │   ├── components/    # MeetingFlowCanvas, AgentNode, DetailDrawer
│   │   ├── pages/         # Dashboard, ProjectDetail, AgentManagement
│   │   ├── stores/        # Zustand state management
│   │   ├── lib/           # api.ts, utils
│   │   └── types/         # TypeScript interfaces
│   ├── package.json
│   └── vite.config.ts     # Proxy /api → :8000, /ws → ws://:8000
│
├── utils/
│   └── tamus_chat_client.py  # LLM API wrapper (retry, multi-turn, images)
│
├── chroma_stores/         # Persisted ChromaDB collections (git-ignored)
├── uploads/               # Uploaded documents (git-ignored)
└── tests/                 # Integration test cases

Key Technologies

Layer	Stack
Orchestration	LangGraph 1.x `StateGraph`, `Send()` fan-out, `SqliteSaver` checkpointing
Backend	FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, uvicorn
Frontend	React 18, ReactFlow, Framer Motion, Zustand, TailwindCSS, shadcn/ui
Vector DB	ChromaDB (per-agent collections)
Knowledge Graph	FalkorDB (per-meeting graph: tasks, claims, entities, decisions)
Relational DB	PostgreSQL 15 (Docker) via asyncpg
LLM	TAMU Chat API (OpenAI-compatible endpoint)
Document Ingestion	Unstructured, sentence-transformers, BM25

Database Management

python manage_db.py stats           # Show row counts
python manage_db.py list-projects   # List all projects
python manage_db.py list-meetings   # List all meetings
python manage_db.py wipe            # Drop all data (destructive)
python manage_db.py remove-last-agent  # Remove most recent agent

Troubleshooting

Problem	Fix
`TAMUS_AI_CHAT_API_KEY not found`	Create `.env` with your API key
`Connection refused` on port 5432 or 6379	Run `docker compose up -d` to start containers
`asyncpg.InvalidCatalogNameError`	Run `alembic upgrade head` after containers are up
`ChromaDB invalid collection name`	Agent IDs are auto-generated; don't use spaces or special characters in agent titles
Frontend shows blank page	Make sure `npm install` ran in `frontend/` and the backend is on port 8000
Slow first run	CrossEncoder model (~80 MB) downloads on first import; subsequent starts are instant
Port 5432 already in use	Stop local PostgreSQL: `brew services stop postgresql@15` (macOS) or `sudo systemctl stop postgresql` (Linux)

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

ThinkTank

Architecture

Prerequisites

Setup

Quick Start (One Command)

Migrating an Existing Database

Manual Setup (Alternative)

1. Clone and create `.env`

2. Start Docker containers

3. Install Python dependencies

4. Run database migrations

5. Install frontend dependencies

Starting the Application

Stopping Services

Usage

Project Structure

Key Technologies

Database Management

Troubleshooting

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
agents		agents
alembic		alembic
backend		backend
docs		docs
eval		eval
frontend		frontend
scripts		scripts
utils		utils
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
install-linux.sh		install-linux.sh
install.sh		install.sh
main.py		main.py
package.json		package.json
requirements.txt		requirements.txt
server.py		server.py
setup_database.sh		setup_database.sh
stop-linux.sh		stop-linux.sh
stop.sh		stop.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ThinkTank

Architecture

Prerequisites

Setup

Quick Start (One Command)

Migrating an Existing Database

Manual Setup (Alternative)

1. Clone and create .env

2. Start Docker containers

3. Install Python dependencies

4. Run database migrations

5. Install frontend dependencies

Starting the Application

Stopping Services

Usage

Project Structure

Key Technologies

Database Management

Troubleshooting

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Clone and create `.env`

Packages