> ## Documentation Index
> Fetch the complete documentation index at: https://dev-doc.dualmindlab.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Modes

> Understand single chat and dual-chat arena mode in DualMind Lab — when to use each mode and how they work.

## Why two modes?

DualMind offers two distinct chat modes serving different purposes:

| Mode            | Models   | Use Case                                                                                                        | Voting |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------ |
| **Single Chat** | 1 model  | Quick AI responses                                                                                              | No     |
| **Dual Chat**   | 2 models | <Tooltip tip="Models are anonymized as 'Model A' and 'Model B' until the user votes">Blind comparison</Tooltip> | Yes    |

## Single Chat

### Purpose

Single chat provides a straightforward AI inference endpoint. Send a prompt, receive a response.

**Use Cases**:

* Building chatbots with consistent model choice
* Testing specific model behavior
* Production applications requiring predictable responses
* Conversations where model identity matters

### How It Works

<Steps>
  <Step title="Model Selection">
    Client specifies model name OR requests random selection.
  </Step>

  <Step title="Provider Routing">
    Backend routes to Groq (primary) or Bytez (fallback).
  </Step>

  <Step title="Inference">
    AI model processes prompt and generates response.
  </Step>

  <Step title="Response">
    Client receives message, model info, usage stats, and timing.
  </Step>
</Steps>

### Characteristics

| Aspect             | Behavior                              |
| ------------------ | ------------------------------------- |
| Response time      | \~1-3 seconds typical                 |
| Model choice       | Explicit or random                    |
| Database writes    | Message logged if `threadId` provided |
| Streaming support  | Yes (via SSE endpoint)                |
| Parallel execution | No (single model)                     |

<Info>
  Single chat is the foundation. Dual chat builds on this by running two parallel single-chat executions.
</Info>

## Dual Chat (Arena Mode)

### Purpose

Dual chat compares two models with the **same prompt** under **identical conditions**. Users vote on which response is better, creating comparative quality data.

**Use Cases**:

* Benchmarking model quality
* Collecting user preferences
* Building model leaderboards
* Running blind comparisons (users don't see model names until after voting)

### How It Works

<Steps>
  <Step title="Model Pairing">
    Backend selects two models based on selection mode (random, topper, or manual).
  </Step>

  <Step title="Parallel Execution">
    Both models receive identical prompt simultaneously via `Task.WhenAll()`.
  </Step>

  <Step title="Independent Fallback">
    Each model has its own 45s timeout and independent fallback chain.
  </Step>

  <Step title="Arena Verdict">
    Backend calculates winner by response length and token count.
  </Step>

  <Step title="Comparison Logging">
    Comparison record created with both responses and timing metrics.
  </Step>
</Steps>

### Selection Modes

<Tabs>
  <Tab title="Random">
    **Mode**: `random`

    Selects two different models randomly from active model pool.

    **Why use this?**

    * Unbiased comparisons
    * Discovering unexpected model differences
    * Equal exposure for all models
    * Building diverse comparison dataset
  </Tab>

  <Tab title="Topper">
    **Mode**: `topper`

    Pairs top-performing model (highest win rate) against random model.

    **Why use this?**

    * Benchmark new models against current leader
    * Challenge the champion
    * Test if top model maintains quality
    * Accelerate model ranking stabilization
  </Tab>

  <Tab title="Manual">
    **Mode**: `manual`

    Client explicitly specifies both models.

    **Why use this?**

    * Controlled A/B testing
    * Specific model matchups
    * Reproducing comparisons
    * Custom tournament brackets
  </Tab>
</Tabs>

### Parallel Execution

Both models execute simultaneously, **not sequentially**.

**Performance Benefit**:

```
Sequential: Model1 (2s) + Model2 (2s) = 4 seconds total
Parallel:   max(Model1 (2s), Model2 (2s)) = ~2 seconds total
```

<Warning>
  If one model fails, the other completes independently. Partial failures result in single-model response rather than complete failure.
</Warning>

### Arena Verdict

The system automatically computes a comparison verdict:

| Metric           | Calculation                              |
| ---------------- | ---------------------------------------- |
| Winner by length | Model with longer response text          |
| Winner by tokens | Model with higher completion token count |
| Verdict text     | Human-readable summary                   |

**Example Verdict**:

> "Agent 2 (Mixtral) provided a slightly longer response with more detailed explanations"

<Note>
  Automatic verdict is informational only. User votes determine actual winner for statistics.
</Note>

## Key Differences

| Feature            | Single Chat                | Dual Chat                          |
| ------------------ | -------------------------- | ---------------------------------- |
| Models executed    | 1                          | 2                                  |
| Execution          | Sequential (with fallback) | Parallel                           |
| Comparison ID      | None                       | Generated UUID                     |
| Voting support     | No                         | Yes                                |
| Response structure | { message, model, usage }  | { agent1, agent2, arena }          |
| Performance        | Faster (1 model)           | Slower (2 models) but parallelized |
| Database writes    | 1 message                  | 2 messages + 1 comparison          |

## When to Use Each Mode

### Choose Single Chat When:

* Building a chatbot with consistent model behavior
* Model identity is known and important
* Minimizing latency (faster than dual-chat)
* User doesn't need to compare models
* Streaming response (SSE) is priority

### Choose Dual Chat When:

* Quality comparison is the goal
* Collecting user votes on model preference
* Building leaderboards or benchmarks
* Running blind tests (hide model names initially)
* Research requires comparative data

## Streaming Considerations

**Single Chat**: Full streaming support via SSE endpoint

**Dual Chat**: No streaming support currently

**Why no dual-chat streaming?**

* Complexity: Two parallel SSE streams harder to manage client-side
* Use case: Arena comparisons typically need full responses for fair comparison
* Future: Could support if use case emerges

<Info>
  For long prompts in dual-chat, consider using single-chat SSE endpoint twice sequentially if streaming is needed.
</Info>

## Database Persistence

### Single Chat Writes

If `threadId` provided:

* 1 row in `thread_messages` table
* Model response, prompt, timing stored
* Links to thread for conversation history

### Dual Chat Writes

Always writes:

* 1 row in `comparisons` table (comparison ID, both models, responses, timing)
* 1 row in `thread_messages` (if `threadId` provided)
* Links message to comparison via `comparison_id` foreign key

Future votes reference the comparison ID.

## Model Selection Transparency

### Single Chat

Model name returned in response. User always knows which model generated response.

### Dual Chat

Models identified as "agent1" and "agent2" in response. Model names included, enabling:

* **Revealed Arena**: Show model names immediately
* **Blind Arena**: Hide names until after vote (client-side logic)

<Tip>
  For unbiased voting, hide model names until user submits vote. This prevents brand bias affecting quality assessment.
</Tip>

## Next Steps

<CardGroup cols="2">
  <Card title="Model Selection" icon="robot" href="/concepts/model-selection">
    How models are chosen for inference
  </Card>

  <Card title="Voting System" icon="thumbs-up" href="/concepts/voting">
    How user votes affect statistics
  </Card>

  <Card title="Streaming Protocol" icon="stream" href="/concepts/streaming">
    SSE implementation for single chat
  </Card>

  <Card title="Thread Management" icon="folder" href="/concepts/threads">
    Persisting conversations
  </Card>
</CardGroup>