### Start Frontend Development Server - Bash

Source: https://context7.com/karpathy/llm-council/llms.txt

Instructions to start the React frontend development server using Vite. It involves navigating to the `frontend` directory, installing dependencies with `npm install`, and then starting the development server with `npm run dev`. The frontend will be available at `http://localhost:5173`.

```bash
# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Frontend starts on http://localhost:5173
# Open in browser to use the application
```

--------------------------------

### Install Frontend Dependencies with npm

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Installs the frontend project dependencies using npm. This command should be run from the 'frontend' directory to set up the React application.

```bash
cd frontend
npm install
cd ..
```

--------------------------------

### Start LLM Council Application Script

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Executes a start script to launch the LLM Council application. This is a convenient way to run both the backend and frontend services.

```bash
./start.sh
```

--------------------------------

### Start Backend Server - Bash

Source: https://context7.com/karpathy/llm-council/llms.txt

Provides instructions to start the FastAPI backend server. It can be run directly using `python -m backend.main` or with `uvicorn`. The server will be accessible at `http://localhost:8001`, and API documentation will be available at `http://localhost:8001/docs`.

```bash
# From project root
python -m backend.main

# Or with uvicorn directly
uvicorn backend.main:app --host 0.0.0.0 --port 8001 --reload

# Server starts on http://localhost:8001
# API docs available at http://localhost:8001/docs
```

--------------------------------

### Install Backend Dependencies with uv

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Installs the backend project dependencies using the uv package manager. This ensures all necessary Python libraries are set up for the backend service.

```bash
uv sync
```

--------------------------------

### Run Backend Manually

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Starts the backend service manually using uv and Python. This command should be run in a dedicated terminal.

```bash
uv run python -m backend.main
```

--------------------------------

### Run Frontend Manually

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Starts the frontend development server manually using npm. This command should be run from the 'frontend' directory in a separate terminal.

```bash
cd frontend
npm run dev
cd ..
```

--------------------------------

### List All Conversations API Endpoint and Frontend Client

Source: https://context7.com/karpathy/llm-council/llms.txt

Retrieves metadata for all conversations, ordered by creation time. The API returns a list of conversation summaries. The frontend example shows how to fetch and display this list.

```bash
# List all conversations
curl http://localhost:8001/api/conversations

# Response:
# [
#   {
#     "id": "abc123",
#     "created_at": "2025-11-27T10:30:00.123456",
#     "title": "Quantum Computing Basics",
#     "message_count": 4
#   },
#   {
#     "id": "def456",
#     "created_at": "2025-11-26T15:20:00.123456",
#     "title": "Climate Change Effects",
#     "message_count": 2
#   }
# ]
```

```javascript
// Frontend API client usage
import { api } from './api';

async function loadConversations() {
  try {
    const conversations = await api.listConversations();
    console.log(`Found ${conversations.length} conversations`);
    conversations.forEach(conv => {
      console.log(`${conv.title} - ${conv.message_count} messages`);
    });
  } catch (error) {
    console.error('Failed to load conversations:', error);
  }
}
```

--------------------------------

### GET /api/conversations

Source: https://context7.com/karpathy/llm-council/llms.txt

Retrieves a list of all existing conversations, ordered by their creation time with the newest first.

```APIDOC
## GET /api/conversations

### Description
Fetches a list of all conversations, including their metadata.

### Method
GET

### Endpoint
/api/conversations

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the conversation.
- **created_at** (string) - Timestamp of conversation creation.
- **title** (string) - The title of the conversation.
- **message_count** (integer) - The number of messages in the conversation.

#### Response Example
```json
[
  {
    "id": "abc123",
    "created_at": "2025-11-27T10:30:00.123456",
    "title": "Quantum Computing Basics",
    "message_count": 4
  },
  {
    "id": "def456",
    "created_at": "2025-11-26T15:20:00.123456",
    "title": "Climate Change Effects",
    "message_count": 2
  }
]
```
```

--------------------------------

### Query Multiple Models in Parallel with asyncio

Source: https://context7.com/karpathy/llm-council/llms.txt

Queries multiple LLM council models simultaneously using asyncio.gather for efficient parallel execution. It takes a list of model identifiers and messages as input, returning a dictionary mapping model names to their responses. This is useful for getting varied perspectives on a query quickly.

```python
from backend.openrouter import query_models_parallel
from backend.config import COUNCIL_MODELS

async def example_parallel_queries():
    messages = [
        {"role": "user", "content": "Explain photosynthesis in one paragraph."}
    ]

    # Query all council models in parallel
    responses = await query_models_parallel(COUNCIL_MODELS, messages)

    # Results are a dict mapping model name to response
    for model, response in responses.items():
        if response is not None:
            print(f"\n{model}:")
            print(response['content'][:200] + "...")
        else:
            print(f"\n{model}: FAILED")

    # Count successful responses
    successful = sum(1 for r in responses.values() if r is not None)
    print(f"\n{successful}/{len(responses)} models responded successfully")

    return responses
```

--------------------------------

### Get Conversation Details API Endpoint

Source: https://context7.com/karpathy/llm-council/llms.txt

Retrieves the full details of a specific conversation, including all messages and stage data, using its unique identifier. Requires the conversation ID as a URL parameter.

```bash
# Get specific conversation
curl http://localhost:8001/api/conversations/abc123

# Response:
# {
#   "id": "abc123",
#   "created_at": "2025-11-27T10:30:00.123456",
#   "title": "Quantum Computing Basics",
#   "messages": [
#     {
#       "role": "user",
#       "content": "Explain quantum superposition"
#     },
#     {
#       "role": "assistant",
#       "stage1": [...],
#       "stage2": [...],
#       "stage3": {...}
#     }
#   ]
# }
```

--------------------------------

### GET /api/conversations/{conversation_id}

Source: https://context7.com/karpathy/llm-council/llms.txt

Retrieves the complete details of a specific conversation, including all its messages and deliberation stage data.

```APIDOC
## GET /api/conversations/{conversation_id}

### Description
Fetches the full details of a specific conversation, including its history and deliberation outcomes.

### Method
GET

### Endpoint
/api/conversations/{conversation_id}

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The unique identifier of the conversation to retrieve.

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the conversation.
- **created_at** (string) - Timestamp of conversation creation.
- **title** (string) - The title of the conversation.
- **messages** (array) - An array of message objects within the conversation. Each message may contain:
    - **role** (string) - The role of the speaker (e.g., "user", "assistant").
    - **stage1** (array) - Results from the first deliberation stage.
    - **stage2** (array) - Results from the second deliberation stage.
    - **stage3** (object) - Results from the third deliberation stage.

#### Response Example
```json
{
  "id": "abc123",
  "created_at": "2025-11-27T10:30:00.123456",
  "title": "Quantum Computing Basics",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum superposition"
    },
    {
      "role": "assistant",
      "stage1": [...],
      "stage2": [...],
      "stage3": {...}
    }
  ]
}
```
```

--------------------------------

### Configure OpenRouter API Key

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Sets up the OpenRouter API key by creating a .env file in the project root. This key is essential for authenticating requests to the OpenRouter service.

```bash
OPENROUTER_API_KEY=sk-or-v1-...
```

--------------------------------

### Backend Data Flow Summary (Python)

Source: https://github.com/karpathy/llm-council/blob/master/CLAUDE.md

Illustrates the asynchronous and parallel data processing flow within the backend, from user query to final response aggregation and frontend display. This Python code snippet represents the conceptual stages.

```python
User Query
    ↓
Stage 1: Parallel queries → [individual responses]
    ↓
Stage 2: Anonymize → Parallel ranking queries → [evaluations + parsed rankings]
    ↓
Aggregate Rankings Calculation → [sorted by avg position]
    ↓
Stage 3: Chairman synthesis with full context
    ↓
Return: {stage1, stage2, stage3, metadata}
    ↓
Frontend: Display with tabs + validation UI
```

--------------------------------

### Configure Council Models - Python & Environment

Source: https://context7.com/karpathy/llm-council/llms.txt

Configures the LLM council members and chairman model within `backend/config.py`. Requires an OpenRouter API key set in the `.env` file. Specifies the list of council models and the designated chairman model.

```python
# backend/config.py configuration
import os
from dotenv import load_dotenv

load_dotenv()

# Required: Set in .env file
OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")

# Council members - customize as needed
COUNCIL_MODELS = [
    "openai/gpt-5.1",
    "google/gemini-3-pro-preview",
    "anthropic/claude-sonnet-4.5",
    "x-ai/grok-4",
]

# Chairman synthesizes final response (can be same as a council member)
CHAIRMAN_MODEL = "google/gemini-3-pro-preview"

# Data storage location
DATA_DIR = "data/conversations"
```

```dotenv
# .env file setup
OPENROUTER_API_KEY=your_api_key_here
```

```bash
# Test your configuration
cd /path/to/project
python -m backend.main

# Backend will start on http://localhost:8001
```

--------------------------------

### Query Single Model (Python)

Source: https://context7.com/karpathy/llm-council/llms.txt

Demonstrates how to query a single LLM using the 'query_model' function from the backend. It shows how to set messages, handle responses, and specify custom timeouts for the API call.

```python
from backend.openrouter import query_model

async def example_single_query():
    messages = [
        {"role": "user", "content": "What is the capital of France?"}
    ]

    # Query with default 120s timeout
    response = await query_model("openai/gpt-5.1", messages)

    if response is not None:
        print(f"Response: {response['content']}")
        if response.get('reasoning_details'):
            print(f"Reasoning: {response['reasoning_details']}")
    else:
        print("Query failed")

    # Query with custom timeout
    fast_response = await query_model(
        "google/gemini-2.5-flash",
        messages,
        timeout=30.0
    )

    return response

```

--------------------------------

### Configure LLM Council Models in Python

Source: https://github.com/karpathy/llm-council/blob/master/README.md

Defines the list of LLMs to be used in the council and designates a Chairman LLM. This configuration is done within the backend/config.py file.

```python
COUNCIL_MODELS = [
    "openai/gpt-5.1",
    "google/gemini-3-pro-preview",
    "anthropic/claude-sonnet-4.5",
    "x-ai/grok-4",
]

CHAIRMAN_MODEL = "google/gemini-3-pro-preview"
```

--------------------------------

### Run Full Council Process - Python

Source: https://context7.com/karpathy/llm-council/llms.txt

Orchestrates the complete 3-stage council deliberation process, including individual responses, peer rankings, and final synthesis. It takes a user query as input and returns the stage outputs and metadata. Handles edge cases where all models might fail.

```python
from backend.council import run_full_council

async def example_full_council():
    user_query = "How does blockchain technology work?"

    # Run complete 3-stage process
    stage1, stage2, stage3, metadata = await run_full_council(user_query)

    # Stage 1: Individual responses
    print("STAGE 1: Individual Responses")
    for resp in stage1:
        print(f"  {resp['model']}: {resp['response'][:100]}...")

    # Stage 2: Rankings
    print("\nSTAGE 2: Peer Rankings")
    for rank in stage2:
        print(f"  {rank['model']}: {rank['parsed_ranking']}")

    # Stage 3: Final synthesis
    print("\nSTAGE 3: Final Synthesis")
    print(f"  {stage3['model']}:")
    print(f"  {stage3['response'][:200]}...")

    # Metadata
    print("\nMETADATA:")
    print(f"  Anonymization mapping: {metadata['label_to_model']}")
    print(f"  Aggregate rankings: {metadata['aggregate_rankings']}")

    # Handle edge case: all models failed
    if not stage1:
        print("ERROR: All models failed to respond")
        print(stage3['response'])  # Will contain error message

    return stage1, stage2, stage3, metadata
```

--------------------------------

### Create New Conversation API Endpoint and Backend

Source: https://context7.com/karpathy/llm-council/llms.txt

Creates a new conversation with a unique identifier. The API endpoint accepts an empty JSON body and returns conversation metadata. The backend function directly creates the conversation in storage.

```bash
# Create a new conversation
curl -X POST http://localhost:8001/api/conversations \
  -H "Content-Type: application/json" \
  -d '{}'

# Response:
# {
#   "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
#   "created_at": "2025-11-27T10:30:00.123456",
#   "title": "New Conversation",
#   "messages": []
# }
```

```python
# Python example using the backend directly
from backend.storage import create_conversation
import uuid

conversation_id = str(uuid.uuid4())
conversation = create_conversation(conversation_id)
print(f"Created conversation: {conversation['id']}")
```

--------------------------------

### Send Message (Batch Mode) API Endpoint

Source: https://context7.com/karpathy/llm-council/llms.txt

Sends a user message to a conversation, initiating the complete 3-stage LLM council process. It returns all results from stage 1, stage 2 (including parsed rankings), and stage 3, along with metadata.

```bash
# Send a message to a conversation
curl -X POST http://localhost:8001/api/conversations/abc123/message \
  -H "Content-Type: application/json" \
  -d '{"content": "What is quantum entanglement?"}'

# Response:
# {
#   "stage1": [
#     {
#       "model": "openai/gpt-5.1",
#       "response": "Quantum entanglement is a phenomenon where..."
#     },
#     {
#       "model": "anthropic/claude-sonnet-4.5",
#       "response": "Entanglement occurs when two particles..."
#     }
#   ],
#   "stage2": [
#     {
#       "model": "openai/gpt-5.1",
#       "ranking": "Response A provides...\n\nFINAL RANKING:\n1. Response B\n2. Response A",
#       "parsed_ranking": ["Response B", "Response A"]
#     }
#   ],
#   "stage3": {
#     "model": "google/gemini-3-pro-preview",
#     "response": "Based on the council's deliberation..."
#   },
#   "metadata": {
#     "label_to_model": {
#       "Response A": "openai/gpt-5.1",
#       "Response B": "anthropic/claude-sonnet-4.5"
#     },
#     "aggregate_rankings": [
#       {
#         "model": "anthropic/claude-sonnet-4.5",
#         "average_rank": 1.25,
#         "rankings_count": 4
#       }
#     ]
#   }
# }
```

--------------------------------

### Collect Initial Responses from Council Models

Source: https://context7.com/karpathy/llm-council/llms.txt

Collects initial responses from all council members in parallel. It takes a user query as input and returns a list of dictionaries, where each dictionary contains the 'model' name and its 'response'. This function is part of the first stage of gathering information.

```python
from backend.council import stage1_collect_responses

async def example_stage1():
    user_query = "What are the main causes of climate change?"

    # Stage 1: Get individual responses
    results = await stage1_collect_responses(user_query)

    # Results is a list of dicts with 'model' and 'response' keys
    print(f"Received {len(results)} responses\n")

    for result in results:
        print(f"Model: {result['model']}")
        print(f"Response: {result['response'][:150]}...\n")

    # Only successful responses are included
    # If all models fail, results will be an empty list

    return results
```

--------------------------------

### Create New Conversation - Python

Source: https://context7.com/karpathy/llm-council/llms.txt

Initializes a new conversation file in the data directory. It generates a unique conversation ID and returns a conversation object with default fields like id, created_at, title, and an empty message list. The conversation is saved to a JSON file.

```python
from backend.storage import create_conversation
import uuid

conversation_id = str(uuid.uuid4())
conversation = create_conversation(conversation_id)

print(f"Created: {conversation['id']}")
print(f"At: {conversation['created_at']}")
print(f"Title: {conversation['title']}")
print(f"Messages: {len(conversation['messages'])}")

# File saved to: data/conversations/{conversation_id}.json
```

--------------------------------

### Core Backend Functions - query_model

Source: https://context7.com/karpathy/llm-council/llms.txt

Queries a single LLM via OpenRouter API with configurable timeout and robust error handling. This function is fundamental for direct model interactions.

```APIDOC
## Core Backend Functions - query_model

### Description
Queries a single LLM via OpenRouter API with timeout and error handling.

### Method
(Internal Function)

### Endpoint
(Not Applicable - Direct Python Function Call)

### Parameters
- **model_name** (string) - Required - The identifier of the LLM to query (e.g., "openai/gpt-5.1").
- **messages** (list of dict) - Required - The conversation history. Each dict should have 'role' and 'content' keys.
- **timeout** (float) - Optional - The maximum time in seconds to wait for a response. Defaults to 120.0 seconds.

### Request Example (Python)
```python
from backend.openrouter import query_model

messages = [
    {"role": "user", "content": "What is the capital of France?"}
]

# Query with default 120s timeout
response = await query_model("openai/gpt-5.1", messages)

# Query with custom timeout
fast_response = await query_model(
    "google/gemini-2.5-flash",
    messages,
    timeout=30.0
)
```

### Response
#### Success Response
- **content** (string) - The response content from the LLM.
- **reasoning_details** (string, optional) - Detailed reasoning provided by the model, if available.

#### Failure Response
- **None** - Returned if the query fails or times out.

### Response Example (Success)
```json
{
  "content": "The capital of France is Paris.",
  "reasoning_details": "Based on general knowledge..."
}
```
```

--------------------------------

### Send Message (Streaming Mode - cURL)

Source: https://context7.com/karpathy/llm-council/llms.txt

Demonstrates how to send a message to the LLM API using cURL and receive Server-Sent Events as each stage of the processing completes. This is useful for real-time UI updates.

```bash
# Send message with streaming (works with curl but better with event stream clients)
curl -X POST http://localhost:8001/api/conversations/abc123/message/stream \
  -H "Content-Type: application/json" \
  -d '{"content": "Explain neural networks"}' \
  --no-buffer

# Stream output:
# data: {"type": "stage1_start"}
#
# data: {"type": "stage1_complete", "data": [{"model": "...", "response": "..."}]}
#
# data: {"type": "stage2_start"}
#
# data: {"type": "stage2_complete", "data": [...], "metadata": {...}}
#
# data: {"type": "stage3_start"}
#
# data: {"type": "stage3_complete", "data": {"model": "...", "response": "..."}}
#
# data: {"type": "title_complete", "data": {"title": "Neural Networks"}}
#
# data: {"type": "complete"}

```

--------------------------------

### Handle Send Message (React)

Source: https://context7.com/karpathy/llm-council/llms.txt

Handles sending a message to the LLM API and processing the response in stages (individual responses, rankings, final synthesis, metadata). Assumes an 'api' object with a 'sendMessage' method and UI update functions.

```javascript
async function handleSendMessage(conversationId, content) {
  try {
    const response = await api.sendMessage(conversationId, content);

    // Display Stage 1: Individual responses
    response.stage1.forEach(result => {
      console.log(`${result.model}: ${result.response}`);
    });

    // Display Stage 2: Rankings
    response.stage2.forEach(ranking => {
      console.log(`${ranking.model} ranked: ${ranking.parsed_ranking}`);
    });

    // Display Stage 3: Final synthesis
    console.log(`Chairman: ${response.stage3.response}`);

    // Display metadata
    console.log('Model mappings:', response.metadata.label_to_model);
    console.log('Aggregate rankings:', response.metadata.aggregate_rankings);
  } catch (error) {
    console.error('Failed to send message:', error);
  }
}
```

--------------------------------

### Handle Send Message Stream (React)

Source: https://context7.com/karpathy/llm-council/llms.txt

Implements frontend logic to handle streaming responses from the LLM API using Server-Sent Events. It updates the UI dynamically as each event (stage start/complete, title, etc.) is received.

```javascript
async function handleSendMessageStream(conversationId, content) {
  const stageStatus = {
    stage1: 'waiting',
    stage2: 'waiting',
    stage3: 'waiting'
  };

  try {
    await api.sendMessageStream(conversationId, content, (eventType, event) => {
      switch (eventType) {
        case 'stage1_start':
          stageStatus.stage1 = 'loading';
          updateUI({ stage1Loading: true });
          break;

        case 'stage1_complete':
          stageStatus.stage1 = 'complete';
          updateUI({
            stage1Data: event.data,
            stage1Loading: false
          });
          break;

        case 'stage2_start':
          stageStatus.stage2 = 'loading';
          updateUI({ stage2Loading: true });
          break;

        case 'stage2_complete':
          stageStatus.stage2 = 'complete';
          updateUI({
            stage2Data: event.data,
            metadata: event.metadata,
            stage2Loading: false
          });
          break;

        case 'stage3_start':
          stageStatus.stage3 = 'loading';
          updateUI({ stage3Loading: true });
          break;

        case 'stage3_complete':
          stageStatus.stage3 = 'complete';
          updateUI({
            stage3Data: event.data,
            stage3Loading: false
          });
          break;

        case 'title_complete':
          updateUI({ title: event.data.title });
          break;

        case 'complete':
          console.log('Stream completed successfully');
          break;

        case 'error':
          console.error('Stream error:', event.message);
          break;
      }
    });
  } catch (error) {
    console.error('Failed to send message:', error);
  }
}
```

--------------------------------

### Synthesize Final Answer as Chairman

Source: https://context7.com/karpathy/llm-council/llms.txt

Synthesizes the final answer by acting as a chairman, consolidating all provided responses and rankings. It requires the user query, Stage 1 results, and Stage 2 results as input. The output is a dictionary containing the 'model' that synthesized the answer and the final 'response'. Handles potential chairman failure by returning an error dict.

```python
from backend.council import stage3_synthesize_final

async def example_stage3(user_query, stage1_results, stage2_results):
    # Stage 3: Chairman synthesizes final answer
    final = await stage3_synthesize_final(
        user_query,
        stage1_results,
        stage2_results
    )

    print(f"Chairman Model: {final['model']}")
    print(f"Final Response:\n{final['response']}")

    # If chairman fails, returns error dict with fallback message
    if final['model'] == 'error':
        print("Chairman synthesis failed!")

    return final
```

--------------------------------

### POST /api/conversations

Source: https://context7.com/karpathy/llm-council/llms.txt

Creates a new conversation within the LLM Council system and returns a unique identifier for it.

```APIDOC
## POST /api/conversations

### Description
Initiates a new conversation, providing a unique ID for future interactions.

### Method
POST

### Endpoint
/api/conversations

### Parameters
#### Request Body
- **content** (string) - Optional. Initial user message to start the conversation.

### Request Example
```json
{
  "content": "Hello, LLM Council!"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the newly created conversation.
- **created_at** (string) - Timestamp indicating when the conversation was created.
- **title** (string) - The title of the conversation, defaulting to "New Conversation".
- **messages** (array) - An empty array to hold messages, to be populated as the conversation progresses.

#### Response Example
```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "created_at": "2025-11-27T10:30:00.123456",
  "title": "New Conversation",
  "messages": []
}
```
```

--------------------------------

### Add Assistant Response to Conversation - Python

Source: https://context7.com/karpathy/llm-council/llms.txt

Stores the complete 3-stage assistant response (individual, rankings, synthesis) into a conversation. It takes the conversation ID and the data for each stage as input. Note that metadata like anonymization mapping and aggregate rankings are not persisted and must be calculated on demand.

```python
from backend.storage import add_assistant_message

conversation_id = "abc123"

# Mock stage data
stage1_data = [
    {"model": "openai/gpt-5.1", "response": "ML is..."},
    {"model": "anthropic/claude-sonnet-4.5", "response": "ML involves..."}
]

stage2_data = [
    {"model": "openai/gpt-5.1", "ranking": "...", "parsed_ranking": ["Response B", "Response A"]}
]

stage3_data = {
    "model": "google/gemini-3-pro-preview",
    "response": "Machine learning is..."
}

# Add assistant message with all stages
add_assistant_message(conversation_id, stage1_data, stage2_data, stage3_data)

# Note: metadata (label_to_model, aggregate_rankings) is NOT persisted
# It must be calculated on-demand when needed
```

--------------------------------

### Conversations API

Source: https://github.com/karpathy/llm-council/blob/master/CLAUDE.md

Endpoints for managing conversations and messages within the LLM Council system.

```APIDOC
## POST /api/conversations/{id}/message

### Description
Submits a new message to a specific conversation. The system processes the message through its three-stage deliberation process and returns the full conversation history including intermediate and final responses, along with metadata like model rankings.

### Method
POST

### Endpoint
/api/conversations/{id}/message

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the conversation.

#### Query Parameters
None

#### Request Body
- **message** (string) - Required - The user's message content.

### Request Example
```json
{
  "message": "What are the latest advancements in renewable energy?"
}
```

### Response
#### Success Response (200)
- **id** (string) - The conversation ID.
- **created_at** (string) - Timestamp of conversation creation.
- **messages** (array) - An array of message objects, each containing:
  - **role** (string) - The role of the message sender (e.g., 'user', 'assistant').
  - **stage1** (object) - Responses from Stage 1 models.
  - **stage2** (object) - Rankings and evaluations from Stage 2.
  - **stage3** (object) - The final synthesized answer from Stage 3.
- **metadata** (object) - Additional information:
  - **label_to_model** (object) - Mapping of anonymized labels to actual model identifiers.
  - **aggregate_rankings** (object) - Aggregated rankings from Stage 2 evaluations.

#### Response Example
```json
{
  "id": "conv_abc123",
  "created_at": "2023-10-27T10:00:00Z",
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in renewable energy?"
    },
    {
      "role": "assistant",
      "stage1": {
        "Response A": {"content": "..."},
        "Response B": {"content": "..."}
      },
      "stage2": {
        "rankings": [...],
        "label_to_model": {"Response A": "model-x", "Response B": "model-y"}
      },
      "stage3": {"content": "..."}
    }
  ],
  "metadata": {
    "label_to_model": {"Response A": "model-x", "Response B": "model-y"},
    "aggregate_rankings": {"model-x": 1.5, "model-y": 2.5}
  }
}
```
```

--------------------------------

### Health Check API

Source: https://context7.com/karpathy/llm-council/llms.txt

A simple endpoint to verify if the LLM Council API is running and accessible.

```APIDOC
## GET /

### Description
Checks the health status of the LLM Council API.

### Method
GET

### Endpoint
/

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the API status, expected to be "ok".
- **service** (string) - The name of the service, "LLM Council API".

#### Response Example
```json
{
  "status": "ok",
  "service": "LLM Council API"
}
```
```

--------------------------------

### POST /api/conversations/{conversation_id}/message

Source: https://context7.com/karpathy/llm-council/llms.txt

Sends a message to a conversation and returns the full response after all stages are complete. This is suitable for scenarios where immediate full results are needed.

```APIDOC
## POST /api/conversations/{conversation_id}/message

### Description
Sends a message to a conversation and returns the full response after all stages are complete. This is suitable for scenarios where immediate full results are needed.

### Method
POST

### Endpoint
`/api/conversations/{conversation_id}/message`

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The ID of the conversation.

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The user's message content.

### Request Example
```json
{
  "content": "Explain neural networks"
}
```

### Response
#### Success Response (200)
- **stage1** (array) - An array of responses from individual models.
  - **model** (string) - The name of the model.
  - **response** (string) - The response from the model.
- **stage2** (array) - An array of rankings from models.
  - **model** (string) - The name of the model.
  - **parsed_ranking** (any) - The parsed ranking data.
- **stage3** (object) - The final synthesis of the responses.
  - **model** (string) - The name of the model that generated the synthesis.
  - **response** (string) - The synthesized response.
- **metadata** (object) - Additional metadata about the response.
  - **label_to_model** (object) - Mapping from labels to model names.
  - **aggregate_rankings** (object) - Aggregated ranking data.

#### Response Example
```json
{
  "stage1": [
    {
      "model": "openai/gpt-4o",
      "response": "A neural network is a type of machine learning algorithm inspired by the structure and function of the human brain..."
    }
  ],
  "stage2": [
    {
      "model": "anthropic/claude-3-opus",
      "parsed_ranking": ["openai/gpt-4o", "google/gemini-pro"]
    }
  ],
  "stage3": {
    "model": "openai/gpt-4o",
    "response": "Neural networks are powerful ML models inspired by the brain, processing information through layers of interconnected nodes..."
  },
  "metadata": {
    "label_to_model": {
      "model_1": "openai/gpt-4o",
      "model_2": "anthropic/claude-3-opus"
    },
    "aggregate_rankings": {
      "ranking_1": ["model_1", "model_2"]
    }
  }
}
```
```

--------------------------------

### POST /api/conversations/{conversation_id}/message/stream

Source: https://context7.com/karpathy/llm-council/llms.txt

Sends a message and streams Server-Sent Events as each stage completes, enabling real-time UI updates. This is ideal for interactive applications requiring immediate feedback.

```APIDOC
## POST /api/conversations/{conversation_id}/message/stream

### Description
Sends a message and streams Server-Sent Events as each stage completes, enabling real-time UI updates. This is ideal for interactive applications requiring immediate feedback.

### Method
POST

### Endpoint
`/api/conversations/{conversation_id}/message/stream`

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The ID of the conversation.

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The user's message content.

### Request Example
```bash
curl -X POST http://localhost:8001/api/conversations/abc123/message/stream \
  -H "Content-Type: application/json" \
  -d '{"content": "Explain neural networks"}' \
  --no-buffer
```

### Response
Server-Sent Events (SSE) stream with the following event types:
- **stage1_start**: Indicates the start of stage 1 processing.
- **stage1_complete**: Contains `data` with stage 1 results.
  - **data** (array) - An array of responses from individual models.
    - **model** (string) - The name of the model.
    - **response** (string) - The response from the model.
- **stage2_start**: Indicates the start of stage 2 processing.
- **stage2_complete**: Contains `data` with stage 2 rankings and `metadata`.
  - **data** (array) - An array of rankings from models.
    - **model** (string) - The name of the model.
    - **parsed_ranking** (any) - The parsed ranking data.
  - **metadata** (object) - Additional metadata about the response.
    - **label_to_model** (object) - Mapping from labels to model names.
    - **aggregate_rankings** (object) - Aggregated ranking data.
- **stage3_start**: Indicates the start of stage 3 processing.
- **stage3_complete**: Contains `data` with the final synthesis.
  - **data** (object) - The final synthesis of the responses.
    - **model** (string) - The name of the model that generated the synthesis.
    - **response** (string) - The synthesized response.
- **title_complete**: Contains `data` with the generated title.
  - **data** (object)
    - **title** (string) - The title of the conversation.
- **complete**: Indicates the end of the stream.
- **error**: Indicates an error occurred during streaming.
  - **message** (string) - The error message.

### Response Example (SSE Stream)
```
data: {"type": "stage1_start"}

data: {"type": "stage1_complete", "data": [{"model": "...", "response": "..."}]}

data: {"type": "stage2_start"}

data: {"type": "stage2_complete", "data": [...], "metadata": {...}}

data: {"type": "stage3_start"}

data: {"type": "stage3_complete", "data": {"model": "...", "response": "..."}}

data: {"type": "title_complete", "data": {"title": "Neural Networks"}}

data: {"type": "complete"}
```
```

--------------------------------

### Health Check API Endpoint

Source: https://context7.com/karpathy/llm-council/llms.txt

A simple endpoint to verify the API's availability. It returns a status message and the service name. No specific inputs are required.

```bash
curl http://localhost:8001/

# Response:
# {
#   "status": "ok",
#   "service": "LLM Council API"
# }
```

--------------------------------

### POST /api/conversations/{conversation_id}/message

Source: https://context7.com/karpathy/llm-council/llms.txt

Sends a new message to a specific conversation, triggering the full 3-stage LLM Council deliberation process and returning all results.

```APIDOC
## POST /api/conversations/{conversation_id}/message

### Description
Submits a user message to a conversation, initiating a multi-stage AI deliberation and returning the aggregated results.

### Method
POST

### Endpoint
/api/conversations/{conversation_id}/message

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The unique identifier of the conversation to send the message to.

#### Request Body
- **content** (string) - Required - The user's message content.

### Request Example
```json
{
  "content": "What is quantum entanglement?"
}
```

### Response
#### Success Response (200)
- **stage1** (array) - Results from the initial AI model responses.
    - **model** (string) - The name of the AI model used.
    - **response** (string) - The response from the AI model.
- **stage2** (array) - Results from the peer review stage.
    - **model** (string) - The model performing the review.
    - **ranking** (string) - The raw ranking text.
    - **parsed_ranking** (array) - The parsed ranking order.
- **stage3** (object) - The final synthesized response.
    - **model** (string) - The designated chairman model.
    - **response** (string) - The final consensus answer.
- **metadata** (object) - Contains additional information about the deliberation.
    - **label_to_model** (object) - Mapping of response labels to model names.
    - **aggregate_rankings** (array) - Statistical summary of rankings.

#### Response Example
```json
{
  "stage1": [
    {
      "model": "openai/gpt-5.1",
      "response": "Quantum entanglement is a phenomenon where..."
    },
    {
      "model": "anthropic/claude-sonnet-4.5",
      "response": "Entanglement occurs when two particles..."
    }
  ],
  "stage2": [
    {
      "model": "openai/gpt-5.1",
      "ranking": "Response A provides...\n\nFINAL RANKING:\n1. Response B\n2. Response A",
      "parsed_ranking": ["Response B", "Response A"]
    }
  ],
  "stage3": {
    "model": "google/gemini-3-pro-preview",
    "response": "Based on the council's deliberation..."
  },
  "metadata": {
    "label_to_model": {
      "Response A": "openai/gpt-5.1",
      "Response B": "anthropic/claude-sonnet-4.5"
    },
    "aggregate_rankings": [
      {
        "model": "anthropic/claude-sonnet-4.5",
        "average_rank": 1.25,
        "rankings_count": 4
      }
    ]
  }
}
```
```

--------------------------------

### Collect Anonymized Peer Review Rankings

Source: https://context7.com/karpathy/llm-council/llms.txt

Anonymizes Stage 1 responses and collects rankings from each model. It takes the user query and Stage 1 results as input. The function returns a tuple containing the rankings and a mapping from anonymous labels to model names. This enables unbiased peer review.

```python
from backend.council import stage2_collect_rankings

async def example_stage2(stage1_results):
    user_query = "What are the main causes of climate change?"

    # Stage 2: Get rankings (returns tuple)
    rankings, label_to_model = await stage2_collect_rankings(
        user_query,
        stage1_results
    )

    # label_to_model maps anonymous labels to actual model names
    print("Anonymization mapping:")
    for label, model in label_to_model.items():
        print(f"  {label} -> {model}")

    print("\nRankings:")
    for ranking in rankings:
        print(f"\n{ranking['model']}:")
        print(f"  Full evaluation: {ranking['ranking'][:200]}...")
        print(f"  Parsed ranking: {ranking['parsed_ranking']}")

    return rankings, label_to_model
```

--------------------------------

### Calculate Aggregate Rankings for Consensus

Source: https://context7.com/karpathy/llm-council/llms.txt

Calculates the average rank position for each model across all peer evaluations. It takes the Stage 2 results and the anonymization mapping as input. The function returns a sorted list of models based on their average rank, with the lowest average rank indicating the best consensus. Useful for identifying the most consistently ranked model.

```python
from backend.council import calculate_aggregate_rankings

def example_aggregate_rankings(stage2_results, label_to_model):
    # Calculate aggregate rankings
    aggregate = calculate_aggregate_rankings(stage2_results, label_to_model)

    # Results sorted by average rank (lower is better)
    print("Aggregate Rankings:")
    for rank in aggregate:
        print(f"  {rank['model']}:")
        print(f"    Average rank: {rank['average_rank']}")
        print(f"    Ranked by {rank['rankings_count']} models")

    # Top model has lowest average_rank
    if aggregate:
        winner = aggregate[0]
        print(f"\nBest response: {winner['model']}")

    return aggregate
```

--------------------------------

### Add User Message to Conversation - Python

Source: https://context7.com/karpathy/llm-council/llms.txt

Appends a user's message to an existing conversation history. It requires the conversation ID and the message content. After appending, it retrieves and prints the last message to verify the addition.

```python
from backend.storage import add_user_message, get_conversation

conversation_id = "abc123"

# Add user message
add_user_message(conversation_id, "What is machine learning?")

# Verify it was added
conv = get_conversation(conversation_id)
last_message = conv['messages'][-1]
print(f"Role: {last_message['role']}")
print(f"Content: {last_message['content']}")
```

--------------------------------

### Update Conversation Title - Python

Source: https://context7.com/karpathy/llm-council/llms.txt

Updates the title of an existing conversation. This function is typically called after the first user message to provide a meaningful title. The actual title generation logic, often using another LLM, is handled separately by `generate_conversation_title()`.

```python
from backend.storage import update_conversation_title

conversation_id = "abc123"

# Update title
update_conversation_title(conversation_id, "Machine Learning Basics")

# Title is generated automatically by generate_conversation_title()
# which uses gemini-2.5-flash for fast, cheap title generation
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.