🧠 Cortex Council

An autonomous multi-agent reasoning system that assembles a dynamic council for any situation, case, statement, or conflict.

Overview

Cortex Council is an intelligent analysis platform that brings together a diverse council of AI experts and simulated person nodes to analyze any situation from multiple perspectives. Each council member provides their unique viewpoint based on their expertise, creating a comprehensive analysis that considers medical, legal, psychological, economic, and many other angles.

Architecture

System Flow

┌──────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐
│  Input   │───►│  Parse &  │───►│  Council  │───►│Synthesis │
│  Query   │    │  Mode     │    │  Analysis │    │  Report  │
└──────────┘    │  Detect   │    │  (R1 + R2)│    │  Output  │
                └───────────┘    └───────────┘    └──────────┘
                      │                │
                      ▼                ▼
                ┌───────────┐    ┌───────────┐
                │  Person   │    │  Domain   │
                │  Nodes    │    │  Nodes    │
                │  (12+)   │    │  (12)     │
                └───────────┘    └───────────┘

Tech Stack

Frontend

Backend

Infrastructure

Features

🏛️ Multi-Agent Council

12 domain expert nodes that analyze situations from their specialized perspective:

• 🩺 Doctor - Medical & health implications
• ⚖️ Lawyer - Legal rights & frameworks
• 🧠 Psychologist - Behavioral & mental patterns
• 📊 Economist - Financial & market impacts
• ⚙️ Engineer - Technical feasibility
• 📚 Teacher - Educational implications
• 🤔 Philosopher - Ethical dimensions
• 🌐 Sociologist - Social & cultural factors
• 👨‍👩‍👧 Parent - Family & child welfare
• 📰 Journalist - Transparency & public interest
• 🏛️ Politician - Power & policy dynamics
• 🎨 Artist - Symbolic & cultural meaning

👥 Person Nodes

Dynamically generated person nodes representing people directly involved:

• Victim, Accused, Witness, Spouse, Colleague, Friend, Neighbor, etc.

🔄 Two-Round Analysis

1. Round 1 - Initial independent analysis from each node
2. Round 2 - Nodes react, challenge, and build on each other's findings

🎯 Intelligent Synthesis

Final synthesis with:

• Consensus - What all nodes agree on
• Tensions - Where perspectives conflict
• Blind Spots - Overlooked insights
• Recommendation - Balanced synthesis
• Action - Single next step

🎨 Modern UI

• 3-column resizeable layout
• Real-time WebSocket streaming
• Dark theme investigation room aesthetic
• Animated node cards with status badges
• Clickable expert tag pills

Project Structure

cortex-council/
├── backend/
│   ├── app/
│   │   ├── agents/
│   │   │   ├── orchestrator.py      # Main orchestration logic
│   │   │   ├── domain_nodes.py     # 12 expert node definitions
│   │   │   ├── person_nodes.py      # Dynamic person node generator
│   │   │   ├── modes.py            # Analysis mode detection
│   │   │   └── prompts.py           # System prompts for nodes
│   │   ├── api/
│   │   │   └── routes/
│   │   │       ├── analyze.py       # Analysis endpoints
│   │   │       ├── auth.py          # Authentication
│   │   │       ├── sessions.py      # Session management
│   │   │       ├── nodes.py         # Node definitions
│   │   │       └── websocket.py      # WebSocket handler
│   │   ├── core/
│   │   │   ├── config.py           # Ollama & app settings
│   │   │   ├── database.py         # PostgreSQL connection
│   │   │   └── security.py         # JWT auth
│   │   ├── models/
│   │   │   └── models.py           # SQLAlchemy models
│   │   ├── schemas/
│   │   │   └── models.py           # Pydantic schemas
│   │   ├── services/
│   │   │   ├── huggingface.py      # Ollama API service
│   │   │   ├── wikipedia.py        # Wikipedia context fetcher
│   │   │   ├── source_map.py      # Source URL mappings
│   │   │   └── web_scraper.py     # Web content scraper
│   │   └── main.py                 # FastAPI application
│   ├── requirements.txt
│   └── docker-compose.yml
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Auth/
│   │   │   │   └── AuthModal.tsx
│   │   │   ├── Graph/
│   │   │   │   ├── PerspectiveCanvas.tsx
│   │   │   │   ├── PerspectiveNode.tsx
│   │   │   │   └── SynthesisNode.tsx
│   │   │   ├── Layout/
│   │   │   │   ├── Header.tsx
│   │   │   │   └── Sidebar.tsx
│   │   │   ├── Panels/
│   │   │   │   ├── AnalysisPanel.tsx
│   │   │   │   ├── NodeDetailPanel.tsx
│   │   │   │   └── QueryBar.tsx
│   │   │   ├── Sessions/
│   │   │   │   ├── CreateSessionModal.tsx
│   │   │   │   └── SessionList.tsx
│   │   │   └── Depth/
│   │   │       └── DepthModes.tsx
│   │   ├── lib/
│   │   │   └── api.ts              # API & WebSocket client
│   │   ├── store/
│   │   │   └── index.ts           # Zustand stores
│   │   ├── types/
│   │   │   └── index.ts            # TypeScript types
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── Dockerfile
├── SPEC.md                          # Full system specification
├── README.md
└── docker-compose.yml

Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+
• Ollama installed locally

1. Install Ollama

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Or download from https://ollama.ai

# Pull the model
ollama pull gemma3:4b

# Start Ollama server
ollama serve

2. Clone & Setup

git clone <repository-url>
cd cortex-council

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install

3. Configure Environment

Create backend/.env:

# Ollama (LLM)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=gemma3:4b

# Backend
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cortex_council
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-key-min-32-characters-long

4. Start Services

# Start PostgreSQL and Redis (Docker)
docker-compose up -d postgres redis

# Start Backend
cd backend
uvicorn app.main:app --host 127.0.0.1 --port 8000

# Start Frontend (new terminal)
cd frontend
npm run dev

5. Access Application

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

API Endpoints

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	Login and get JWT token
GET	/api/sessions	List user's sessions
POST	/api/sessions	Create new session
DELETE	/api/sessions/{id}	Delete a session
POST	/api/analyze	Start new analysis
WS	/ws/{situation_id}	WebSocket for streaming responses
GET	/api/nodes	List available expert nodes
POST	/api/nodes/custom	Create custom expert node

Database Schema

┌─────────────┐     ┌─────────────┐     ┌────────────────┐
│    users    │     │  sessions   │     │  situations    │
├─────────────┤     ├─────────────┤     ├────────────────┤
│ id (UUID)   │────►│ id (UUID)   │────►│ id (UUID)      │
│ email       │     │ user_id     │     │ session_id     │
│ password    │     │ name        │     │ query          │
│ created_at  │     │ active_nodes│     │ mode           │
└─────────────┘     │ created_at  │     │ parsed_data    │
                    └─────────────┘     └────────────────┘
                                                 │
                                                 ▼
                    ┌────────────────────────────────┐
                    │         node_findings          │
                    ├────────────────────────────────┤
                    │ id (UUID)                      │
                    │ situation_id                    │
                    │ node_id                        │
                    │ node_type (domain/person)      │
                    │ content                         │
                    │ round                           │
                    │ status                          │
                    └────────────────────────────────┘

Docker Deployment

# Build and run all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

License

MIT License - see LICENSE for details.

---

Built with 🧠 for autonomous multi-agent reasoning.