# Track: Qwen, Llama & Grok Vendor Integration + Capability Matrix

**Status:** Active (spec approved 2026-06-06)
**Initialized:** 2026-06-06
**Owner:** Tier 2 Tech Lead
**Priority:** High (extends vendor matrix; foundational for future open-source / self-hosted support)

---

## 1. Overview

This track adds first-class support for three new AI vendors — **Qwen** (via Alibaba DashScope native API), **Llama** (via Ollama local, OpenRouter cloud, and custom base URL), and **Grok** (via xAI's OpenAI-compatible endpoint) — alongside a new **Vendor Capability Matrix** that declares per-(vendor, model) feature support and lets the GUI adapt dynamically instead of hard-coding per-vendor UI branches.

The track also refactors the existing **MiniMax** provider to use a new shared OpenAI-compatible send helper, eliminating the duplicate OpenAI-compatible request/response logic that the new vendors would otherwise introduce. This is a data-oriented refactor (Fleury / Acton / Lottes framing): the shared helper is the algorithm that operates on a normalized message data structure; each vendor's entry point is a thin adapter that translates vendor-specific request/response shapes into the normalized form at the boundary.

The follow-up track "Anthropic / Gemini / DeepSeek Capability Matrix Migration" (see §13.1) will migrate the remaining three providers onto the same matrix in a separate effort. This track stays focused on the greenfield additions + the safe MiniMax refactor.

## 2. Goals (Priority Order)

| Priority | Goal | Rationale |
|---|---|---|
| **A (foundational)** | Vendor Capability Matrix framework. Per-(vendor, model) feature declarations. UX reads the matrix to enable/disable UI elements. | The user's stated architectural goal: "aggregate all those granular features into a feature support listing... the ux can adjust what's available." Per Casey Muratori's module-layer-boundary pattern: `ai_client` is the authoritative owner of "what can vendor X do"; `gui_2` adapts to that surface. |
| **A (primary value)** | Qwen via DashScope native SDK. Wire Qwen-Plus, Qwen-Max, Qwen-Long (1M+ context), Qwen-VL-Plus, Qwen-VL-Max (vision), Qwen-Audio. | Qwen has a meaningful unique API surface (vs OpenAI-compatible). DashScope native SDK unlocks features that the OpenAI-compatible mode loses (Qwen-Audio, Qwen-Long custom chunking, Qwen-VL-Max enhanced vision). |
| **A (primary value)** | Llama via Ollama (local) + OpenRouter (cloud) + custom base URL. | Llama has no first-party API. The "vendor" is the model family; the backend is per-project config. Ollama covers local; OpenRouter is the universal cloud aggregator (Together, Groq, Fireworks, etc. all flow through it); custom URL is the escape hatch for self-hosted / unusual backends. |
| **A (primary value)** | Grok via xAI (OpenAI-compatible). Wire Grok-2, Grok-2-Vision. | xAI's API is OpenAI-compatible; the value is filling in the matrix entry and exposing Grok-2-Vision for the screenshot feature. |
| **B (architectural)** | Shared OpenAI-compatible helper in `src/openai_compatible.py`. MiniMax, Llama, Grok all call into it. | Data-oriented design: share the algorithm (HTTP call, response parsing, tool-call detection, streaming, history repair, error classification) on a normalized data structure. Each vendor entry point is a thin adapter. |
| **B (architectural)** | MiniMax refactored to use the shared helper. | MiniMax is already OpenAI-compatible; pure win, ~250 lines of duplicated logic deleted. Mitigated by existing `tests/test_minimax_provider.py`. |
| **C (optimization)** | Capability matrix v1 populates for the 4 OpenAI-compatible vendors + Qwen. Anthropic/Gemini/DeepSeek get "pending migration" entries; the UX does not read them yet. | Half-baked matrix is worse than no matrix. Populating for the vendors that share the new helper keeps the matrix meaningful without risking regressions in the unique-API vendors. |
| **C (optimization)** | UX adapts to the matrix: vision button hidden when `vision: false`; cache panel hidden when `caching: false`; cost panel shows "—" when `cost_tracking: false` (e.g., local backends). | The whole point of the matrix. Specific UI adaptations listed in §8. |

### 2.1 Non-Goals (this track)

- **Not** migrating Anthropic, Gemini, or DeepSeek to the capability matrix. They have genuinely unique APIs (4-breakpoint caching, genai SDK, raw HTTP) and their migration belongs in a separate, careful track. Stub entries: "pending_migration".
- **Not** adding audio input support (Qwen-Audio's audio files). Audio is a deferred capability (§6).
- **Not** adding server-side code execution. Deferred to §6.
- **Not** changing the AI Settings panel layout beyond the minimum needed to expose the new providers and the capability-driven UI adaptations.
- **Not** adding model fine-tuning management for any of the three new vendors.
- **Not** adding batch API support for any of the three new vendors.

## 3. Architecture

### 3.1 Data-Oriented Design (Fleury / Acton / Lottes)

The user's design philosophy (referencing Ryan Fleury's code/data separation, Mike Acton's data-oriented design, Timothy Lottes' cache-aware algorithms) translates concretely to:

- **The data is the API.** The "OpenAI-compatible send" operates on a normalized data structure: `messages: list[dict]`, `tools: list[dict]`, `model_capabilities: VendorCapabilities`, `response: NormalizedResponse`. The structure is laid out linearly (SoA where applicable) and processed in bulk.
- **The algorithm is shared.** One function: `send_openai_compatible(client, model, messages, tools, capabilities, *, stream_callback=None) -> NormalizedResponse`. It handles HTTP, response parsing, tool-call detection, streaming chunk aggregation, error classification, history repair, and token usage extraction — all on the normalized data.
- **The adapters are per-vendor.** Each vendor's `_send_<vendor>()` is a thin function that:
  1. Initializes the vendor-specific client (OpenAI SDK with vendor's base URL + auth, or DashScope SDK).
  2. Loads the vendor's history (`_minimax_history`, `_llama_history`, etc.) and capabilities from the registry.
  3. Calls `send_openai_compatible(...)` (or, for Qwen, the DashScope-specific helper).
  4. Updates the vendor's history with the normalized response.
  5. Returns the text content to `ai_client.send()`.

> **Coordination with `data_oriented_error_handling_20260606`.** This track is *upstream* of the Fleury-pattern `Result[T]` refactor. The shared helper should return `Result[NormalizedResponse, ErrorInfo]` from day 1 (rather than `NormalizedResponse` and raise `ProviderError` on failure), so the subsequent data_oriented_error_handling track is a small mechanical pass over the new code rather than a second migration. Per nagent_review Pitfall #4 (provider history divergence), the helper is also a natural place to add an `ErrorKind.PROVIDER_HISTORY_DIVERGED_FROM_UI` error case. **Concrete change in code:** `def send_openai_compatible(...) -> Result[NormalizedResponse, ErrorInfo]`. The `Result` type is imported from the new `src/result_types.py` (created by the data_oriented_error_handling track); for this track, the helper can stub it locally as a `Tuple[NormalizedResponse, Optional[ErrorInfo]]` and the data_oriented_error_handling track does the mechanical conversion. Either way, the *error shape* is `ErrorInfo`, defined in this spec's §5.1 below.

This means:
- **Adding a new OpenAI-compatible vendor** = 50 lines of glue (client init + capability declaration + history storage), not 300 lines of duplicated logic.
- **Anthropic/Gemini/DeepKeep** stay per-vendor code paths; the data-oriented refactor doesn't apply to them because their unique APIs are not OpenAI-compatible-shaped.
- **"Base paths are unique"** (the user's wording) means: `_send_qwen()`, `_send_llama()`, `_send_grok()`, `_send_minimax()` are the unique entry points; everything they call into is shared.

### 3.1.1 Architectural principle: "Use the best API per vendor" (added 2026-06-11, revised after Grok consultation)

**Per the user's correction, the track's prior assumption — "all OpenAI-compatible" — was incomplete. The right principle is: **use each vendor's native SDK or REST API when one exists, falling back to OpenAI-compatible only when no native option exists.**

The OpenAI-compatible shim (the `send_openai_compatible` helper) is the highest-leverage part of the spec: every vendor that uses it gets the same request/response/tool-calling/error/streaming logic with zero duplication. The question is **which vendors should use it** vs. which should have a native adapter.

**Confirmed best API per vendor (Grok-consulted 2026-06-11):**

| Vendor | API / Approach | Decision |
|---|---|---|
| **Qwen** | Alibaba DashScope native SDK (not OpenAI-compatible) | **NATIVE** — OpenAI-compatible mode drops Qwen-Audio, Qwen-Long custom chunking, Qwen-VL-Max enhanced vision. Phase 2 ships this. |
| **xAI (Grok)** | xAI official OpenAI-compatible (`https://api.x.ai/v1`) | **OPENAI-COMPATIBLE** — Per Grok's own confirmation, the OpenAI-compatible endpoint is "fully compatible and clean" with "no meaningful unique native surface lost." Phase 3 ships this. |
| **MiniMax** | OpenAI-compatible (`https://api.minimax.io/v1`) | **OPENAI-COMPATIBLE** — Already fully compatible. Phase 4 refactor is a pure win. |
| **DeepSeek** | OpenAI-compatible (`https://api.deepseek.com`) | **OPENAI-COMPATIBLE** — Drop-in compatible by design; offers an `/anthropic`-compatible path too. Follow-up track. |
| **Ollama** (Llama local backend) | Ollama's `/v1/chat/completions` (OpenAI-compatible) is the v1 choice; native `/api/chat` is a possible v2 | **OPENAI-COMPATIBLE in v1** — Ollama's compat endpoint supports streaming, tools, vision, JSON mode. Native `/api/chat` has extras (`think` param, `images: list[str]`, structured outputs); deferred to follow-up. |
| **Meta Llama API** (Llama cloud-native) | Meta's native REST API | **NATIVE (NEW BACKEND, FOLLOW-UP)** — Add as a 4th Llama backend. Deferred pending verification of Meta's API spec. |
| **Gemini** | Google `genai` SDK / Gemini native API (NOT OpenAI-compatible) | **NATIVE (FOLLOW-UP)** — OpenAI-comp loses explicit context caching (big cost win), Grounding with Google Search, native video/multimodal. The deferred follow-up track. |
| **Anthropic** | Anthropic official SDK / Messages API (NOT OpenAI-compatible) | **NATIVE (FOLLOW-UP)** — Native gives prompt caching (`cache_control` ephemeral, 50-90% savings), PDF processing, citations, extended thinking, Computer Use. OpenAI-comp layer exists but loses too much. The deferred follow-up track. |

**Implications for the capability matrix:** as native APIs add features, the matrix grows. The current v1 matrix has 7 fields (vision, tool_calling, caching, streaming, model_discovery, context_window, cost_tracking). Future expansion (per the deferred list in §3.3, refined by Grok's consultation) will add:

- `audio` (Qwen-Audio, others)
- `video` (Gemini native, others)
- `grounding` / `search` (Gemini Grounding with Google Search, Grok's `x_search` and `web_search`)
- `computer_use` (Anthropic, beta/agentic)
- `local` (boolean — true for Ollama; useful for UX "free local" badge)
- `reasoning` / `extended_thinking` (Grok `reasoning_effort`, Anthropic extended thinking, Ollama `think`)
- `web_search`, `x_search`, `code_execution`, `file_search`, `mcp_support` (per-vendor server-side tools)
- `structured_output` (response_format / format support)

The matrix IS the aggregate tracker; the GUI filters UI elements based on what's in the matrix. **The matrix's job is to be the canonical source of truth for "what can this vendor/model do"; the GUI never hard-codes per-vendor branches.** Any new capability a vendor adds (server-side tools, native cost reporting, prompt caching) goes into the matrix; the UI filters based on it.

**This track's Phase 3 ships the OpenAI-compatible Grok + Llama (3 backends) as the canonical implementation per Grok's confirmation; the native-API work for Llama (Ollama native, Meta Llama API) is deferred to follow-up tracks documented in §13.1.**

### 3.2 Module Layout

```
src/
  ai_client.py                    # Modified: refactor _send_minimax; add _send_qwen/_send_llama/_send_grok
  vendor_capabilities.py           # NEW: VendorCapabilities dataclass, registry, get_capabilities()
  openai_compatible.py             # NEW: shared OpenAI-compatible send helper
  cost_tracker.py                  # Modified: add Qwen/Llama/Grok pricing
  models.py                        # Modified: add provider metadata for Qwen/Llama/Grok. NOTE: `models.PROVIDERS` (line 79-86) is the existing single source of truth for the (vendor, model) enumeration. The capability registry in `vendor_capabilities.py` reads from this constant — it does NOT introduce a parallel list.
  gui_2.py                         # Modified: register Qwen/Llama/Grok in PROVIDERS; capability-driven UI
  app_controller.py                # Modified: same
  credentials_template.toml        # Modified: add [qwen], [llama], [grok] sections
```

```
tests/
  test_vendor_capabilities.py      # NEW: capability matrix tests
  test_openai_compatible.py        # NEW: shared helper tests
  test_qwen_provider.py            # NEW: Qwen-specific tests (DashScope adapter, history repair, error classification)
  test_llama_provider.py           # NEW: Llama-specific tests (multi-backend, model discovery)
  test_grok_provider.py            # NEW: Grok-specific tests (xAI endpoint, Grok-2-Vision)
  test_minimax_provider.py         # Modified: verify refactor preserves behavior
```

### 3.3 Capability Matrix v1 — 7 Capabilities

| Capability | Type | Purpose | UX Effect |
|---|---|---|---|
| `vision` | `bool` | Can accept image inputs (screenshots). | Screenshot button enabled/disabled in message panel. |
| `tool_calling` | `bool` | Supports function/tool calls. | Tool system toggle; "Tools enabled" indicator. |
| `caching` | `bool` | Supports server-side prompt caching (Gemini explicit, Anthropic ephemeral). | Cache panel visible/hidden. Cache indicators in token budget. |
| `streaming` | `bool` | Supports streaming responses. | Stream progress bar visible/hidden. |
| `model_discovery` | `bool` | Backend exposes `/v1/models` (or equivalent) for live model list. | "Fetch Models" button enabled/disabled. |
| `context_window` | `int` | Maximum input tokens for this model. | Token budget panel max. |
| `cost_tracking` | `bool` | Per-token pricing known. | Cost panel shows estimate; hides with "—" for unknown. |

**Deferred to v2 (separate track):**
- `audio_input` (Qwen-Audio only)
- `pdf_input` (Gemini, Anthropic)
- `server_side_code_execution` (Anthropic, OpenAI, Gemini)
- `image_generation`, `fine_tuning`, `batch_api` (none currently)

### 3.4 Per-(vendor, model) Capabilities

Capabilities are declared per-model, not per-vendor, because a vendor can have both vision and text-only models (Qwen: Qwen-VL-Plus vs Qwen-Plus; Llama: 3.2-Vision vs 3.2-1B/3B; Grok: Grok-2-Vision vs Grok-2).

```python
@dataclass(frozen=True)
class VendorCapabilities:
 vendor: str                        # "qwen" | "llama" | "grok" | "minimax" | "anthropic" | "gemini" | ...
 model: str                         # the model name, e.g. "qwen-vl-max" or "*" for vendor default
 vision: bool = False
 tool_calling: bool = True
 caching: bool = False
 streaming: bool = True
 model_discovery: bool = True
 context_window: int = 8192         # tokens
 cost_tracking: bool = True         # False for local backends where cost is unknown/free
 cost_input_per_mtok: float = 0.0   # USD per million input tokens
 cost_output_per_mtok: float = 0.0  # USD per million output tokens
 notes: str = ""
```

**Lookup pattern:** `get_capabilities(vendor, model) -> VendorCapabilities`. The registry is a flat dict keyed by `(vendor, model)`. Lookups fall back to the vendor's default entry if a specific model isn't registered.

**Registry source of truth:** `src/vendor_capabilities.py` has a hardcoded `_REGISTRY: dict[tuple[str, str], VendorCapabilities]` populated at import time. The data is in code (not TOML) because:
- It's referenced by `_send_<vendor>()` per call (hot path; can't afford file I/O).
- Changes are tied to vendor SDK updates and are code-reviewed.
- TOML is for user-config (credentials, project settings); vendor capabilities are platform facts.

## 4. Per-Vendor Designs

### 4.1 Qwen via DashScope Native SDK

**Why native (not OpenAI-compatible mode):** DashScope's native API unlocks Qwen-Audio, Qwen-Long (1M+ context with custom chunking), Qwen-VL-Max (enhanced vision), and DashScope-specific tool format with `parameters` schema. OpenAI-compatible mode loses these.

**SDK:** `dashscope` (added to `pyproject.toml` dependencies).

**State (module-level globals, following the existing pattern):**
```python
_qwen_client: dashscope.Generation | None = None
_qwen_history: list[dict[str, Any]] = []
_qwen_history_lock: threading.Lock = threading.Lock()
```

**Credentials:** `credentials.toml` `[qwen]` section with `api_key` and optional `region` (default: `china`; alternatives: `international`).

**Configuration per-project (TOML):** `provider = "qwen"`, `qwen_model = "qwen-max"`. Optional `qwen_region = "international"`.

**Models shipped in the capability registry (v1):**

| Model | vision | tool_calling | caching | context_window | cost_input | cost_output |
|---|---|---|---|---|---|---|
| `qwen-turbo` | false | true | false | 1,000,000 | $0.05 | $0.10 |
| `qwen-plus` | false | true | false | 131,072 | $0.40 | $1.20 |
| `qwen-max` | false | true | false | 32,768 | $2.00 | $6.00 |
| `qwen-long` | false | true | false | 1,000,000 | $0.07 | $0.28 |
| `qwen-vl-plus` | true | true | false | 131,072 | $0.21 | $0.63 |
| `qwen-vl-max` | true | true | false | 32,768 | $0.50 | $1.50 |
| `qwen-audio` | false | true | false | 32,768 | $0.10 | $0.30 |

(Pricing from Alibaba Cloud DashScope public pricing as of 2026-06-06; update if needed.)

**Entry point:** `_send_qwen()` in `src/ai_client.py`. Calls a DashScope-specific helper (not the OpenAI-compatible one) because DashScope's request/response shape differs.

**Tool format translation:** DashScope uses a slightly different tool schema than OpenAI. The Qwen adapter translates from the normalized tool definitions (OpenAI-shaped) to DashScope's `tools: list[dict]` with `parameters: dict` schema.

**Vision / audio:** Qwen-VL accepts image URLs or base64; the adapter handles the multipart encoding for the OpenAI-compatible `image_url` content type. **Qwen-Audio in v1 is text-only** — the `audio_input` capability is deferred to v2 (see §3.3). Users can still select Qwen-Audio in v1 for text-only tasks; the audio attachment button is hidden via the (absent) audio capability check.

**Error classification:** `_classify_qwen_error()` maps DashScope exceptions to `ProviderError` kinds (`quota`, `rate_limit`, `auth`, `balance`, `network`).

**Model discovery:** DashScope exposes a `list_models` API. `_list_qwen_models()` returns the hardcoded registry (DashScope doesn't have a great runtime discovery API; the hardcoded list is the source of truth).

**Vision support:** Qwen-Audio and Qwen-VL-* register `vision: true`. The UX's screenshot button is enabled for those models. For Qwen-Audio, the screenshot button is replaced with an audio attachment button (deferred to v2; for v1, audio attachment is wired but the button is hidden — see §6).

### 4.2 Llama (Ollama + OpenRouter + Custom URL)

**Why three backends:** Llama has no first-party API. The "vendor" is the model family; the backend is per-project config.
- **Ollama** (local, ubiquitous): OpenAI-compatible at `http://localhost:11434/v1`. Free.
- **OpenRouter** (cloud aggregator): OpenAI-compatible at `https://openrouter.ai/api/v1`. Single API key covers Together, Groq, Fireworks, etc.
- **Custom URL** (escape hatch): any OpenAI-compatible endpoint. For self-hosted vLLM, llama.cpp, LM Studio, or any unusual cloud.

**SDK:** `openai` (already a dependency, used for MiniMax).

**State (module-level globals):**
```python
_llama_client: OpenAI | None = None
_llama_history: list[dict[str, Any]] = []
_llama_history_lock: threading.Lock = threading.Lock()
_llama_base_url: str = "http://localhost:11434/v1"  # default
_llama_api_key: str = "ollama"                      # Ollama doesn't require auth
```

**Credentials:** `credentials.toml` `[llama]` section with `api_key` (empty for Ollama) and `base_url`.

**Configuration per-project (TOML):** `provider = "llama"`, `llama_model = "llama-3.3-70b"`, `llama_base_url = "https://openrouter.ai/api/v1"`, `llama_api_key_env = "OPENROUTER_API_KEY"` (optional env override).

**Models shipped in the capability registry (v1):**

| Model | vision | tool_calling | caching | context_window | cost_input | cost_output |
|---|---|---|---|---|---|---|
| `llama-3.1-8b-instant` | false | true | false | 131,072 | $0.05 (Groq) | $0.08 |
| `llama-3.1-70b-versatile` | false | true | false | 131,072 | $0.59 (Groq) | $0.79 |
| `llama-3.1-405b-reasoning` | false | true | false | 131,072 | $3.00 (OpenRouter avg) | $3.00 |
| `llama-3.2-1b-preview` | false | true | false | 131,072 | $0.04 | $0.04 |
| `llama-3.2-3b-preview` | false | true | false | 131,072 | $0.06 | $0.06 |
| `llama-3.2-11b-vision-preview` | true | true | false | 131,072 | $0.18 | $0.18 |
| `llama-3.2-90b-vision-preview` | true | true | false | 131,072 | $0.90 | $0.90 |
| `llama-3.3-70b-specdec` | false | true | false | 131,072 | $0.59 (Groq) | $0.79 |
| `llama-*` (wildcard) | model-specific | true | false | 131,072 | $0 | $0 |

(Pricing varies by backend; registry entries represent the most common case. Cost overrides per-project allowed via TOML.)

**Local backend default:** When `llama_base_url` is `http://localhost:11434/v1` and `llama_api_key` is empty, `cost_tracking: false` (free). UX cost panel shows "Free (local)" instead of an estimate.

**Entry point:** `_send_llama()` in `src/ai_client.py`. Calls the shared `send_openai_compatible()` helper.

**Tool format:** Native OpenAI (Llama backends all use OpenAI's tool format). No translation needed.

**Error classification:** `_classify_llama_error()` — same as MiniMax's error classifier (OpenAI SDK errors are uniform across backends).

**Model discovery:** Ollama exposes `GET /api/tags` (not `/v1/models`); OpenRouter exposes `GET /v1/models`. The Llama adapter probes both endpoints and unions the results. For custom URLs, falls back to the hardcoded registry.

### 4.3 Grok via xAI (OpenAI-Compatible) — confirmed 2026-06-11

**Per Grok's consultation (2026-06-11): the OpenAI-compatible endpoint at `https://api.x.ai/v1` is the canonical, fully-featured approach.** xAI's API is "fully compatible and clean" with "no meaningful unique native surface lost" by using the OpenAI-compatible shim. This section was previously labeled "Native REST API" based on a user impression that the native endpoint had unique features (prompt_cache_key, reasoning_effort, server-side tools, cost_in_usd_ticks) that the shim loses; Grok's actual recommendation is that the shim is fine.

**SDK:** `openai` (already a dependency). Set `base_url="https://api.x.ai/v1"` and pass the xAI API key as the Bearer token (handled automatically by the OpenAI SDK).

**State:**
```python
_grok_client: OpenAI | None = None
_grok_history: list[dict[str, Any]] = []
_grok_history_lock: threading.Lock = threading.Lock()
```

**Credentials:** `credentials.toml` `[grok]` section with `api_key`. (xAI's `base_url` is hardcoded to `https://api.x.ai/v1`.)

**Configuration per-project (TOML):** `provider = "grok"`, `grok_model = "grok-2"`.

**Models shipped in the capability registry (v1):**

| Model | vision | tool_calling | context_window | cost_input | cost_output |
|---|---|---|---|---|---|
| `grok-2` | false | true | 131,072 | $2.00 | $10.00 |
| `grok-2-vision` | true | true | 32,768 | $2.00 | $10.00 |
| `grok-beta` | false | true | 131,072 | $5.00 | $15.00 |

(Pricing from x.ai public pricing as of 2026-06-06; update if needed. `caching` stays `False` in v1 since Grok's OpenAI-compatible shim doesn't expose `prompt_cache_key`.)

**Entry point:** `_send_grok()` in `src/ai_client.py`. Calls `send_openai_compatible()` with the xAI base URL (via the OpenAI SDK).

**Tool format:** Native OpenAI. No translation needed.

**Vision:** Grok-2-Vision accepts image URLs or base64. The OpenAI-compatible helper already handles vision via the OpenAI SDK's multimodal message format.

**Error classification:** Same as OpenAI-compatible vendors (uniform error shape via the openai SDK).

**Model discovery:** xAI exposes `GET /v1/models`. Standard OpenAI-compatible discovery.

## 5. Shared OpenAI-Compatible Helper

### 5.1 Module: `src/openai_compatible.py`

```python
from dataclasses import dataclass
from typing import Any, Callable, Optional
from openai import OpenAI, OpenAIError

@dataclass(frozen=True)
class NormalizedResponse:
 text: str
 tool_calls: list[dict[str, Any]]
 usage_input_tokens: int
 usage_output_tokens: int
 usage_cache_read_tokens: int
 usage_cache_creation_tokens: int
 raw_response: Any

@dataclass
class OpenAICompatibleRequest:
 messages: list[dict[str, Any]]
 tools: Optional[list[dict[str, Any]]] = None
 model: str = ""
 temperature: float = 0.0
 top_p: float = 1.0
 max_tokens: int = 8192
 stream: bool = False
 stream_callback: Optional[Callable[[str], None]] = None

def send_openai_compatible(
 client: OpenAI,
 request: OpenAICompatibleRequest,
 *,
 capabilities: VendorCapabilities,
) -> NormalizedResponse: ...
```

The helper:
1. Translates `request.messages` into the OpenAI SDK's `messages` parameter (passthrough — already in OpenAI shape).
2. Translates `request.tools` if non-None (passthrough for now; future: strip unsupported fields based on `capabilities`).
3. Calls `client.chat.completions.create(...)` with the right `model`, `temperature`, `top_p`, `max_tokens`, `stream`, `tools`, `tool_choice="auto"`.
4. If streaming: aggregates chunks; calls `stream_callback(text_chunk)` for each text delta; collects final usage from the last chunk.
5. If non-streaming: parses the response in one shot.
6. Returns a `NormalizedResponse` with text, tool calls (in OpenAI shape), usage stats.
7. On exception: classifies the OpenAI exception and re-raises as `ProviderError` (using `_classify_openai_compatible_error()`).

The helper is the **algorithm on the data**. Per-vendor adapters (Llama, Grok, MiniMax) are the **boundary code that converts vendor-specific state to/from the normalized form**.

### 5.2 Refactor of `_send_minimax()`

**Before:** ~250 lines of inline OpenAI-compatible send logic (lines 2103-2264 of `src/ai_client.py` per the existing grep). Mixes client init, message building, API call, response parsing, tool call handling, history repair, error classification.

**After:** ~50 lines. `_send_minimax()` becomes:
```python
def _send_minimax(md_content, user_message, base_dir, file_items, discussion_history, ...):
 _ensure_minimax_client()
 with _minimax_history_lock:
 _repair_minimax_history(_minimax_history)
 if discussion_history and not _minimax_history:
 _minimax_history.extend(_parse_discussion_history(discussion_history))
 _minimax_history.append({"role": "user", "content": _build_user_content(...)})
 
 request = OpenAICompatibleRequest(
 messages=_minimax_history,
 tools=_build_tools(...),
 model=_model,
 temperature=_temperature,
 top_p=_top_p,
 max_tokens=_max_tokens,
 stream=True,
 stream_callback=stream_callback,
 )
 caps = get_capabilities("minimax", _model)
 response = send_openai_compatible(_minimax_client, request, capabilities=caps)
 
 # Append response to history (same logic as today)
 ...
 return response.text
```

The behavior is identical; the code is shorter. `tests/test_minimax_provider.py` is the safety net (existing test coverage should pass without modification).

## 6. UX Adaptation (Capability-Driven UI)

The GUI reads `get_capabilities(active_vendor, active_model)` once per render frame and stores it in a local. Specific adaptations:

| UI Element | Behavior based on matrix |
|---|---|
| **Screenshot button** (Message panel) | Enabled iff `vision: true`. Tooltip explains why if disabled. |
| **Audio attachment button** (Message panel) | **Deferred to v2.** Stub: always hidden in v1 (the `audio_input` capability is not in the v1 matrix; v1 has no audio UI at all). |
| **Tools enabled toggle** (Message panel) | Enabled iff `tool_calling: true`. |
| **Cache panel** (Operations Hub) | Visible iff `caching: true`. |
| **Cache indicators** (Token budget) | Shown iff `caching: true`. |
| **Stream progress** (Response panel) | Visible iff `streaming: true`. |
| **Fetch Models button** (AI Settings) | Enabled iff `model_discovery: true`. |
| **Token budget max** (Token budget) | Set to `capabilities.context_window`. |
| **Cost estimate** (MMA Dashboard) | Shown iff `cost_tracking: true`; shows "Free (local)" for `cost_tracking: false` + `base_url` containing `localhost`/`127.0.0.1`; shows "—" for other `cost_tracking: false` cases. |

The adaptations are gated on the capability value, not on vendor name. The `gui_2.py` change is one new helper: `def _get_active_capabilities(self) -> VendorCapabilities: return get_capabilities(self._provider, self._model)`. The render functions query this once at the top of their scope.

> **Important: the matrix is a *declarative read*, not a behavioral dispatch.** Per nagent_review Pitfall #1 (opaque function calling in the Application is the correct choice; nagent's regex-tag protocol is right for the Meta-Tooling, not the Application), the capability matrix must not introduce new per-vendor code paths in the GUI. UI elements that depend on capabilities should be *visible/enabled/disabled/hidden* based on the matrix value, but the *behavior* they invoke is unchanged. Concretely:
> - The screenshot button is *hidden* when `vision: false` — but when it *is* shown, it calls the same `mcp_client.dispatch("image_attachment", ...)` it always did.
> - The cost panel shows "—" when `cost_tracking: false` — but the *underlying cost computation* is the same function; only the display differs.
> - The cache panel is *hidden* when `caching: false` — but the cache calls themselves are not gated on the matrix; they're gated on the provider's actual cache availability (which the matrix *describes*, not *enforces*).
>
> This is the same data-oriented principle as the rest of the track: the matrix is *data*, the behavior is *code*, and they meet only at the UI render boundary.

## 7. Configuration

### 7.1 `pyproject.toml` — new dependency

```toml
[project]
dependencies = [
 ...
 "dashscope>=1.14.0",  # NEW
 "openai>=1.0.0",       # already a dependency
]
```

### 7.2 `credentials.toml` — new sections

```toml
[qwen]
api_key = "YOUR_DASHSCOPE_KEY"
# region = "china"  # default; "international" also valid

[llama]
# api_key = "YOUR_OPENROUTER_KEY"  # required for OpenRouter; empty for Ollama
# base_url = "https://openrouter.ai/api/v1"  # default for cloud; "http://localhost:11434/v1" for Ollama

[grok]
api_key = "YOUR_XAI_KEY"
```

### 7.3 Per-project TOML — provider selection

```toml
[ai]
provider = "qwen"          # "qwen" | "llama" | "grok" | (existing: "gemini", "anthropic", ...)
model = "qwen-vl-max"
qwen_region = "china"      # vendor-specific
# OR
llama_base_url = "https://openrouter.ai/api/v1"
llama_api_key_env = "OPENROUTER_API_KEY"  # optional: read key from env
# OR
grok_model = "grok-2-vision"
```

## 8. Testing Strategy

| Test File | Purpose | Coverage Target |
|---|---|---|
| `tests/test_vendor_capabilities.py` | Registry lookup, fallback to vendor default, per-model overrides. | 100% |
| `tests/test_openai_compatible.py` | Request building, response parsing, streaming aggregation, tool call detection, error classification. | 90% |
| `tests/test_qwen_provider.py` | DashScope adapter, tool format translation, Qwen-VL vision, Qwen-Audio stub. | 80% |
| `tests/test_llama_provider.py` | Multi-backend (Ollama mock + OpenRouter mock), model discovery union, custom URL fallback. | 80% |
| `tests/test_grok_provider.py` | xAI endpoint, Grok-2-Vision vision, model discovery. | 80% |
| `tests/test_minimax_provider.py` (modified) | Verify refactor preserves behavior. Existing tests should pass unmodified. | 100% (regression) |

**Mocking strategy:** All tests use `unittest.mock.patch` on the vendor SDKs (DashScope, OpenAI). No real API calls. The `RUN_REAL_AI_TESTS=1` env var continues to gate opt-in real-API tests (out of scope for this track).

**Integration verification:** Manual smoke test in the GUI: select Qwen provider, send a message with a tool call, confirm the tool executes. Repeat for Llama and Grok. Document the smoke test results in the Phase 4 checkpoint git note.

## 9. Migration / Rollout

| Phase | What | Risk |
|---|---|---|
| **Phase 1 — Capability matrix framework + shared helper** | Add `src/vendor_capabilities.py` and `src/openai_compatible.py`. Add unit tests for both. Add `dashscope` to `pyproject.toml`. No user-facing changes. | Low. New files, no modifications to `ai_client.py`. |
| **Phase 2 — Qwen via DashScope** | Implement `_send_qwen()` in `src/ai_client.py`. Add `[qwen]` to credentials template. Register `qwen` in `PROVIDERS` lists. Populate capability registry for Qwen models. | Medium. New SDK, new code path, new credentials section. |
| **Phase 3 — Grok + Llama via shared helper** | Implement `_send_grok()` and `_send_llama()`. Both call `send_openai_compatible()`. Add `[grok]` and `[llama]` credentials sections. Register in PROVIDERS lists. | Medium. New code paths, but lighter than Qwen (OpenAI-compatible). |
| **Phase 4 — MiniMax refactor** | Refactor `_send_minimax()` to use the shared helper. Verify all existing `tests/test_minimax_provider.py` tests pass. | Medium-High. Touching working code. Mitigated by existing test coverage. |
| **Phase 5 — UX adaptation + integration** | Add `_get_active_capabilities()` to `gui_2.py`. Apply the 9 UI adaptations from §6. Run the full test suite. | Low. UI-only changes. |
| **Phase 6 — Docs + archive** | Update `docs/guide_ai_client.md` to document the new vendors, the capability matrix, and the shared helper. Update `docs/guide_models.md` for the new PROVIDERS entries. Archive the track. **Docs touchpoint (added 2026-06-08):** `docs/guide_ai_client.md` "AI Client" row in the docs index should be updated to list 8 providers (was 5) and the new `send_openai_compatible()` helper section. The 2026-06-08 docs refresh introduced `docs/guide_context_aggregation.md` which references the `aggregate.run()` pipeline that all new providers use; verify the cross-link is still accurate. | Low. |

Each phase has its own checkpoint commit and git note.

## 10. Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| MiniMax refactor breaks existing behavior. | Medium | High (regresses a working provider) | `tests/test_minimax_provider.py` is the safety net. Run it after every change. If it fails, the refactor is incorrect — fix forward, don't revert. |
| DashScope SDK has API differences from documentation (e.g., response shape). | Medium | Medium | Pin to a specific DashScope version (`>=1.14.0,<2.0.0`). Test against the actual SDK in CI. |
| OpenRouter pricing varies by underlying model; registry entries may be inaccurate. | High | Low (cost estimates are advisory) | Cost panel shows "Estimate" with a tooltip. Add a "Pricing source: x" line. |
| Ollama's `/api/tags` shape differs from `/v1/models`; the union function may miss models. | Low | Low (model list is a convenience) | Fall back to the hardcoded registry. Manual override per-project via TOML. |
| Capability matrix drift: a model ships a new feature (e.g., Qwen-Plus gains vision) but the registry says `vision: false`. | Medium | Low (user sees a missing feature) | Document the update process: edit `src/vendor_capabilities.py`, add a test, commit. Make the registry the canonical place to look. |
| Local backends (Ollama) need CORS / firewall configured for the GUI to talk to them. | Low | Medium (user can't connect) | Document the Ollama setup in the credentials template comments. Reference the Ollama docs for `OLLAMA_ORIGINS`. |
| Llama backends may rate-limit aggressively (especially free tiers of OpenRouter). | Medium | Low | The existing `_classify_openai_compatible_error()` already maps 429 to `rate_limit`. The error UI surfaces this clearly. |

## 11. Out of Scope (Explicit)

- **Audio input support** (Qwen-Audio, future Grok-Audio). Deferred to a follow-up track that adds an audio attachment button to the message panel and a `audio_input` capability to the matrix.
- **Server-side code execution** (Anthropic, OpenAI, Gemini). Deferred; the matrix has a placeholder entry `server_side_code_execution: false` for all v1 vendors.
- **Anthropic / Gemini / DeepSeek capability matrix migration**. Tracked as a separate track ("Open-Vendor Matrix Migration Phase 2" — see §13.1). Their unique APIs need careful, vendor-by-vendor migration.
- **Batch API support** for any of the three new vendors. Not requested.
- **Fine-tuning management** for any of the three new vendors. Not requested.
- **Image generation** (DALL-E, Midjourney, etc.). Not in scope; the matrix has a placeholder `image_generation: false`.
- **PDF input** (Gemini, Anthropic). Deferred.

## 12. Open Questions

1. **Per-model cost overrides:** Should `manual_slop.toml` allow per-project cost overrides for Llama backends (since pricing varies by which underlying provider OpenRouter routes to)? (Proposal: yes; add `llama_cost_input` / `llama_cost_output` to the per-project TOML.)
2. **Default Llama base URL:** Should the default be Ollama (`localhost:11434`) or OpenRouter? (Proposal: Ollama for the "first-time user gets a working setup" experience; OpenRouter requires an API key.)
3. **DashScope region selection:** How does the user pick `china` vs `international`? Per-project TOML (`qwen_region = "international"`) or env var (`DASHSCOPE_REGION`)? (Proposal: both; TOML wins.)
4. **Qwen-Coder and Qwen-Math specialized models:** Include in v1 or defer? (Proposal: defer to v1.1; the matrix entry is trivial but the model-specific prompting optimization is out of scope.)

## 13. See Also

### 13.1 Follow-up Tracks (separate plans)

**A. "Anthropic / Gemini / DeepSeek Capability Matrix Migration"** — Migrates the three remaining providers onto the same capability matrix. Required pre-work: ensure the matrix's per-model lookup pattern handles the `caching: true` (Anthropic 4-breakpoint, Gemini explicit) and `pdf_input: true` (Anthropic, Gemini) capabilities. Each provider keeps its unique per-vendor code path (the 4-breakpoint system, the genai SDK); the matrix entries are populated so the UX can adapt. This is a separate track because the migration of each unique-API provider is non-trivial and the risk of regressing the existing working code is high.

**B. "Llama Native APIs (Ollama native + Meta Llama API)"** — Per §3.1.1's revised assessment (after Grok's consultation), xAI's OpenAI-compatible endpoint is the canonical full-featured approach — NO Grok native refactor is needed. The follow-up for Llama backends is:
- **Llama (Ollama backend)** → Ollama native `/api/chat`; adds `think` param (low/medium/high), `images: list[str]` in messages (cleaner base64 than OpenAI's `image_url` content type), `thinking` field in responses, `format` for structured outputs. The Phase 3 Red tests are written for the OpenAI-compatible shim; the native tests would mock `requests.post` to `/api/chat`.
- **Llama (Meta Llama API backend)** → New 4th Llama backend; uses Meta's native REST API. Currently deferred pending verification of Meta's API spec (the `llama.developer.meta.com/docs/overview` URL returned 400 on fetch this session; needs re-verification when the docs are available).
- **Capability matrix expansion** → Add fields for the new native features per Grok's consultation: `audio`, `video`, `grounding`/`search`, `computer_use`, `local`, `reasoning`/`extended_thinking`, `web_search`, `x_search`, `code_execution`, `file_search`, `mcp_support`, `structured_output`. Each addition is a registry change + a UI adaptation in Phase 5.
- **Test rewrites** → The Phase 3 Llama Red tests in `test_llama_provider.py` would be extended with 2 more tests: native Ollama (`/api/chat` with `think` param, `images: list[str]`) and Meta Llama API. The Grok Red tests do NOT need rewriting.

**Footnote (added 2026-06-11, in case context expires):** As of the end of Phase 4, only `_send_minimax` has a working tool-call loop. The Phase 3 (Grok, Llama) and Phase 2 (Qwen) entry points are single-shot — they call `send_openai_compatible` once and return, without executing tool_calls. If the user notices "tool execution doesn't work for Qwen/Grok/Llama" after Phase 5 ships, the fix is to either (a) inline the tool loop in each entry point (mirroring MiniMax's pattern) or (b) better, lift the loop into a shared `run_with_tool_loop(client, request, capabilities, *, pre_tool_callback, qa_callback, patch_callback, base_dir, vendor_name)` helper that wraps `send_openai_compatible` and is called from all 4 vendor entry points. Option (b) is the data-oriented-design win (algorithm = HTTP mechanics, policy = tool dispatch) and avoids the 4-way duplication that already exists in `_send_anthropic`/`_send_gemini`/`_send_gemini_cli`/`_send_deepseek`. Defer to a separate follow-up track; not in scope for this one.

**Footnote (added 2026-06-11, in case context expires):** As of the end of Phase 5, only **adaptation 1 of 9** from spec §6 is applied to `src/gui_2.py` (Screenshot button iff vision, at `render_files_and_media:3030`). The remaining 8 adaptations are deferred to a follow-up track:
- 2: Tools toggle iff tool_calling
- 3: Cache panel iff caching
- 4: Stream progress iff streaming
- 5: Fetch Models iff model_discovery
- 6: Token budget max = context_window
- 7-9: Cost panel (estimate / "Free (local)" for localhost / "—" for other cost_tracking=false)

The pattern is established: `caps = app._get_active_capabilities(); imgui.begin_disabled(not caps.<field>); ...UI...; imgui.end_disabled(); if not caps.<field>: imgui.same_line(); imgui.text_disabled("(reason)")`. Each remaining adaptation is a mechanical application of this pattern at its specific render site. The follow-up track will need to locate each render site (tools toggle, cache panel, stream progress, fetch models button, token budget, cost panel) and apply the wrapping. The helper `_get_active_capabilities()` is already in place (added in t5.1).

### 13.2 Project References

- `docs/guide_ai_client.md` — current `ai_client.py` architecture; will be updated in Phase 6 to document the matrix and the shared helper. Specifically: the per-provider history globals (`_anthropic_history`, `_deepseek_history`, `_minimax_history`) documented at lines 123-132 are the **state-management shape** that the new 3 vendors should follow in Phase 2/3. (Per `guide_state_lifecycle.md §4`, the per-provider lock pattern is the established convention.)
- `docs/guide_models.md` — current PROVIDERS constant and provider metadata; will be updated in Phase 6. Per `docs/guide_models.md §"Data Models"`, the FileItem schema (line 510) is the model layer the capability matrix composes with, not replaces.
- `docs/guide_context_aggregation.md` — added 2026-06-08; documents the `aggregate.py` pipeline that all new providers will route through. The new provider adapters' "build file items" stage should compose with `aggregate.build_file_items()` and the 7 `view_mode` values, not introduce a parallel aggregation path.
- `conductor/tracks/nagent_review_20260608/report.md` — added 2026-06-08; specifically §1 (Durable work), §5 (The loop), and §15 Pitfalls #2 and #4 (per-provider history globals and stateful singleton) inform the data-oriented framing of this track.
- `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` — added 2026-06-08; specifically §1 (state visibility), §2 (readable conversation log), and §9 (edit-the-input) inform the helper's `Result` return type recommendation.
- `conductor/tracks/openai_integration_20260308/` — closest prior art (single provider, OpenAI-compatible).
- `conductor/tracks/zhipu_integration_20260308/` — second prior art (single provider, custom API).
- `conductor/tracks/startup_speedup_20260606/` — example of an active track in this project (same convention).
- `conductor/tracks/test_batching_refactor_20260606/` — second example of an active track in this project.
- `conductor/product.md` "Multi-Provider Integration" — product-level overview of the multi-provider architecture.
- `conductor/product-guidelines.md` "Modular Controller Pattern" — the convention this track follows for `vendor_capabilities.py` and `openai_compatible.py` as standalone modules.

### 13.3 External References

- **Ryan Fleury on code/data separation** — informs the data-oriented design (vendor capabilities as data, helper as algorithm, per-vendor code as boundary adapter).
- **Mike Acton on data-oriented design** — informs the SoA-like layout of the capability matrix and the "transform data, don't mutate state" framing.
- **Timothy Lottes on cache-aware algorithms** — informs the helper's streaming aggregation (bulk-process chunks, minimize per-chunk overhead).
- **Alibaba DashScope documentation** — `https://help.aliyun.com/zh/model-studio/` for the native API reference.
- **OpenRouter API documentation** — `https://openrouter.ai/docs` for the cloud aggregator.
- **Ollama OpenAI compatibility** — `https://github.com/ollama/ollama/blob/main/docs/openai.md` for the local backend.
- **xAI API documentation** — `https://docs.x.ai/` for the Grok endpoint.
