AI Orchestrator
================

The Co-design Platform uses a multi-agent AI orchestrator built on
**LangGraph** for stateful, graph-based agent workflows.

Architecture Overview
----------------------

.. code-block:: text

   User Input
       │
       ▼
   ┌─────────────────────┐
   │    Router Agent      │  ← Intent classification
   └──────────┬──────────┘
              │ (routes to specialized agent)
              ▼
   ┌─────────────────────────────────────────────────────────┐
   │                 Agent Graph (LangGraph)                   │
   │                                                          │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐    │
   │  │Stakeholder│  │Ecosystem Map │  │ RAG Agent      │    │
   │  │  Agent    │  │   Agent      │  │ (knowledge)    │    │
   │  └──────────┘  └──────────────┘  └────────────────┘    │
   │                                                          │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐    │
   │  │ DIV      │  │Sustainability│  │ Outcomes       │    │
   │  │ Agent    │  │Canvas Agent  │  │ Diagram Agent  │    │
   │  └──────────┘  └──────────────┘  └────────────────┘    │
   │                                                          │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐    │
   │  │ Diagnosis│  │ Suggest      │  │ Assessment     │    │
   │  │ Agent    │  │ Stakeholder  │  │ Agent          │    │
   │  └──────────┘  └──────────────┘  └────────────────┘    │
   └──────────────────────┬──────────────────────────────────┘
                          │
                          ▼
   ┌─────────────────────┐
   │    Reviser Agent     │  ← Quality assurance & formatting
   └──────────┬──────────┘
              │
              ▼
   ┌─────────────────────┐
   │    Sender Agent      │  ← Response delivery
   └─────────────────────┘

Agent Types
------------

**Routing & Control:**

- **Router** — Classifies user intent and routes to the correct agent
- **Clarification** — Asks follow-up questions when intent is ambiguous
- **Human Input** — Escalates to human review when needed

**Template Agents (Data Generation):**

- **Stakeholder** — Guides stakeholder card creation (Phase 1)
- **Suggest Stakeholder** — AI suggestions for new stakeholders
- **Partnership Project** — Suggest partnership opportunities
- **Suggest Project** — AI project suggestions
- **Ecosystem Map** — Generate ecosystem matrix (all connections)
- **DIV** — Data-Information-Value guide (Phase 2)
- **Outcomes Diagram** — Outcomes planning (Phase 4)
- **Sustainability Canvas** — 6-dimension analysis (Phase 4)

**Assessment Agents:**

- **Assessment Stakeholder** — Evaluate stakeholder capabilities (0–5 radar)
- **Assessment Project** — Project readiness assessment
- **Phase Analyzer** — Determine which phase to focus on

**Knowledge Agents:**

- **RAG Agent** — Retrieval-augmented generation from vector DB
- **DB Retriever** — Fetch project data for context
- **Assistant Agent** — General co-design coaching

**Quality Agents:**

- **Reviser** — Quality assurance, factual accuracy
- **Response Relevance** — Filter irrelevant outputs
- **Toxicity** — Content safety filter
- **Feedback** — Gather structured user feedback

LLM Configuration
------------------

The platform uses **LiteLLM** as a unified gateway to LLM providers:

.. code-block:: yaml

   # llm_lite_config.yaml
   model_list:
     - model_name: mistral-large
       litellm_params:
         model: ovh/mistral-large-latest
         api_key: ${OVH_ENDPOINT_API_KEY_1}

   # Multiple API keys for load balancing
   # Automatic failover between keys

**Current Provider:** OVH (Mistral models)
**Interface:** ``ILLMService`` (pluggable — can swap to OpenAI, Anthropic, etc.)

RAG Pipeline
-------------

The retrieval-augmented generation pipeline combines:

1. **BM25 (Sparse Retrieval):**
   Keyword-based matching using rank-bm25 library.

2. **Semantic Search (Dense Retrieval):**
   Sentence-transformer embeddings stored in Weaviate.
   Cosine similarity for relevance ranking.

3. **Hybrid Fusion:**
   Combines BM25 and semantic scores for final ranking.

4. **Reranking:**
   Optional cross-encoder reranking for precision.

.. code-block:: text

   User Query
       │
       ├──▶ BM25 (keyword) ──────┐
       │                          │
       └──▶ Semantic (embedding) ─┼──▶ Fusion ──▶ Rerank ──▶ Top-K Docs
                                  │
                                  │
   Project Context ───────────────┘

State Persistence
------------------

LangGraph state is persisted in PostgreSQL using the async checkpointer:

- **checkpoint_writes** — Write operations log
- **checkpoint_blobs** — Serialized agent state
- **checkpoints** — State snapshots per thread
- **checkpoint_migrations** — Schema versioning

This enables:

- Conversations that survive server restarts
- Thread resumption at any point
- Debugging via state inspection

Form Triggers
--------------

When an agent generates structured data (e.g., a stakeholder card), it returns
a **form trigger** that the frontend uses to pre-fill forms:

.. code-block:: json

   {
     "form_trigger": {
       "templateCode": "1.0.1",
       "action": "create",
       "fields": {
         "formalInfo_name": "European Space Agency",
         "formalInfo_type": "Intergovernmental organization",
         "assessment_technical_eo_score": 5
       }
     }
   }

The frontend renders a pre-filled form that the user can review and submit.

Carbon Tracking
----------------

The platform integrates **CodeCarbon** for tracking LLM inference emissions:

- Per-request token usage tracking
- Cumulative emissions reporting
- Helps quantify the environmental cost of AI-assisted co-design