# IDCC Multi-Agent Orchestration Logic
**Impact Data Consortium Chain (IDCC) · AI Research System v4.0**

---

## Overview

The IDCC system uses a 6-agent architecture with a central orchestrator (Cici) that routes queries to specialist agents based on intent classification. Three routing modes handle different query types.

---

## The Six Agents

| Agent | Role | Trigger |
|-------|------|---------|
| **Cici** | Orchestrator — routes all queries | Always active |
| **James** | Literature Search — FTS across 62,602 SWRD articles + 23,793 SSWR papers | Research questions, topic searches |
| **Jessica** | Data Analysis — SQL queries on SWRD for method/trend analysis | Statistical, empirical questions |
| **Johnson** | Impact Measurement — RAG on frameworks (SROI, IRIS+, ESG, IFC) | Framework, ESG, impact strategy questions |
| **Terence** | SROI Calculation — full SVI-methodology SROI arithmetic | SROI calculation, financial proxies, adjustments |
| **Tat** | Report Writing — synthesises all agents into professional reports | Final reports, summaries |

---

## Mode A: Standard Pipeline (Sequential)

**Trigger:** General research questions without @mention

```
User Query
    ↓
Cici (intent classification)
    ↓
James (literature search) ──────────────────┐
    ↓                                         │
Jessica (data analysis, challenges James) ───┤
    ↓                                         │
Johnson (impact frameworks, if relevant) ────┤
    ↓                                         │
Terence (SROI calculation, if requested) ────┤
    ↓                                         │
Tat (synthesises all inputs into report) ◄───┘
```

**Depth variants:**
- **Fast** — Tat only, 200-word summary (no James/Jessica pipeline)
- **Standard** — James → Jessica → Tat (default)
- **Deep** — James → Jessica debate (2 rounds) → Johnson → Tat

---

## Mode B: @Mention Direct Dispatch

**Trigger:** User writes `@james`, `@jessica`, `@johnson`, `@terence`, or `@tat`

```
User Query (@agent)
    ↓
Cici detects mention
    ↓
Direct route to named agent (no pipeline)
    ↓
Agent responds directly to user
```

The agent receives the full conversation history and responds as a specialist, without Tat synthesising.

**Special case — `@team`:** Routes to full Standard Pipeline.

---

## Mode C: Document / Idea Summarisation (Tat-First)

**Trigger:** User pastes a document, asks for a summary, or says "summarise this"

```
User pastes document / idea
    ↓
Cici detects Mode C intent
    ↓
Tat responds directly (no James/Jessica search)
    ↓
Tat offers to run full pipeline if user wants deeper analysis
```

---

## SROI Workflow (Terence-specific)

**Trigger:** Phrases like "calculate SROI", "value map", "four adjustments", "deadweight"

```
Cici detects SROI calculation intent
    ↓
Johnson (framework scoping — selects proxies, identifies outcomes)
    ↓
Terence (full SROI arithmetic):
    ├── Value Map (outcomes × financial proxies)
    ├── Raw SROI ratio = PV(net benefits) ÷ value of inputs
    ├── Four mandatory adjustments:
    │       Deadweight · Attribution · Displacement · Drop-off
    ├── Adjusted SROI ratio
    └── Sensitivity analysis ±10% / ±25%
    ↓
Tat (SROI report in SVI format)
```

---

## Bio / Introduction Routing

**Trigger:** "Who is James?", "introduce the team", "about Cici"

```
Cici detects bio intent
    ↓
bioAgent() reads AGENT_BIOS constant (no LLM call)
    ↓
Returns agent bio directly
```

Supported targets: `james`, `jessica`, `johnson`, `terence`, `tat`, `cici`, `team`, `platform`

---

## Intent Classification (Cici's LLM Call)

Cici uses a single LLM call with a structured JSON output:

```json
{
  "workflow": "standardResearch | sroiValueMap | sroiFullCalculation | sroiReport | ...",
  "targetAgent": "search | analysis | report | impact | sroi",
  "bioTarget": "james | jessica | johnson | terence | tat | cici | team | platform",
  "depth": "fast | standard | deep",
  "lang": "en | zh-TW | zh-CN"
}
```

---

## Key Design Principles

1. **Single orchestrator** — Cici makes one classification call; all subsequent agents are task-focused, not meta-decision-makers
2. **Streaming SSE** — all agent outputs stream token-by-token via `POST /api/chat`
3. **History-aware** — every agent receives the full conversation history
4. **Language-consistent** — `lang` is detected once by Cici and passed to all downstream agents
5. **RAG-augmented** — Johnson and Terence both query the same Supabase pgvector knowledge base before generating

---

## API Endpoint

```
POST /api/chat
Content-Type: application/json

{
  "question": "string",
  "lang": "en | zh-TW | zh-CN",
  "history": [{ "role": "user|assistant", "content": "string" }],
  "depth": "fast | standard | deep"
}
```

Response: **Server-Sent Events (SSE)** stream

Each event:
```
data: {"agent":"search|analysis|report|impact|sroi|orchestrator", "type":"thinking|result|done", "message":"string"}
```

---

*IDCC · Impact Data Consortium Chain · Hong Kong · idcc@idcc.hk*