bDS/MISTRAL_PLAN.md

Plan: Add Mistral AI as Alternative Chat Provider

Context

bDS currently routes all AI chat through the OpenCode Zen gateway (opencode.ai/zen/v1/...) with two code paths: Anthropic Messages API and OpenAI-compatible. The user wants Mistral AI added as a direct alternative provider with frontier models that support chat completion, tool use, and vision. Mistral's API is OpenAI-compatible (api.mistral.ai/v1/chat/completions), making integration straightforward.

Target Models

• Mistral Large 3 (mistral-large-2512) - frontier, vision, tools, 40k ctx
• Mistral Medium 3.1 (mistral-medium-2508) - frontier, vision, tools, 40k ctx
• Mistral Small 3.2 (mistral-small-2506) - vision, tools, 128k ctx

Files to Modify

1. src/main/engine/OpenCodeManager.ts - Core provider logic

A. Add Mistral constants (near lines 23-25)

• MISTRAL_API_URL = 'https://api.mistral.ai/v1/chat/completions'
• MISTRAL_MODELS_URL = 'https://api.mistral.ai/v1/models'

B. Add Mistral models to MODEL_DISPLAY_NAMES (lines 28-69)

'mistral-large-2512': 'Mistral Large 3'
'mistral-medium-2508': 'Mistral Medium 3.1'
'mistral-small-2506': 'Mistral Small 3.2'

C. Update detectProvider() (lines 1839-1845)

• Add: if (id.startsWith('mistral') || id.startsWith('ministral')) return 'mistral';

D. Add Mistral API key storage

• New field: private mistralApiKey: string = ''
• New methods: setMistralApiKey(), getMistralApiKey(), validateMistralApiKey()
• Load on init from settings key 'mistral_api_key'

E. Add Mistral request path in sendMessage()

• Route provider === 'mistral' to new sendMistralRequest() method
• Similar to OpenAI path but:
  • URL: MISTRAL_API_URL (direct, not through OpenCode gateway)
  • Auth: Authorization: Bearer ${this.mistralApiKey}
  • No tool_choice: "required" — use "any" for Mistral's equivalent
  • Context budget: 35,000 tokens (vs 150k for OpenCode) for 40k-ctx models, 120k for Small 3.2

F. Vision format for Mistral

• In view_image tool result handling: use image_url format with base64 data URI
• Format: { type: 'image_url', image_url: { url: 'data:image/webp;base64,...' } }
• Same as OpenAI path (Mistral is compatible here)

G. Update getAvailableModels()

• When Mistral key is set, include Mistral models in returned list
• Add provider field to model entries so UI can group them

H. Update analyzeMediaImage() (lines 2066-2192)

• Support Mistral models for image metadata analysis (title/alt/caption generation)
• When a Mistral model is selected, use Mistral vision format (image_url with base64 data URI)
• Route to api.mistral.ai with Mistral API key

2. src/main/engine/ChatEngine.ts - Settings persistence

A. Add Mistral key helpers

• getMistralApiKey() - read from settings table
• setMistralApiKey(key) - persist to settings table
• Settings key: 'mistral_api_key'

3. src/main/ipc/chatHandlers.ts - IPC bridge

A. Add Mistral-specific handlers

• chat:setMistralApiKey - validate + persist Mistral key
• chat:getMistralApiKey - return masked key
• chat:validateMistralApiKey - test key against Mistral API

B. Update chat:getAvailableModels

• Include Mistral models when Mistral key is configured
• Return provider info per model

C. Update chat:checkReady

• Report readiness for both providers independently

4. src/main/shared/electronApi.ts - Type definitions

A. Extend ChatModel interface

• Add provider: 'opencode' | 'mistral' field (already optional, ensure populated)

B. Add Mistral IPC methods to ElectronAPI.chat

• setMistralApiKey(key: string)
• getMistralApiKey()
• validateMistralApiKey(key: string)

5. src/renderer/components/SettingsView.tsx - UI settings

A. Add Mistral API key section

• Separate input field for Mistral API key (below OpenCode key)
• Same pattern: masked display, change button, validation on save

B. Update model selector

• Group models by provider in dropdown (optgroup: "OpenCode Zen", "Mistral AI")
• Show provider badge next to selected model

6. src/renderer/components/ChatPanel/ChatPanel.tsx - Chat UI

A. Update model selector in chat

• Group by provider in dropdown
• Only show models for configured providers

7. Preload/IPC registration

A. src/main/ipc/handlers.ts or preload

• Register new Mistral IPC channels
• Expose in preload bridge

8. MCP Server - src/main/engine/MCPServer.ts

• No changes needed — MCP server exposes tools for external AI agents to call; no bDS-side AI runs during MCP requests

Implementation Order

1. Tests first (per AGENTS.md)
2. Types (electronApi.ts)
3. Engine (OpenCodeManager.ts — constants, detection, key storage, request path)
4. Persistence (ChatEngine.ts — settings helpers)
5. IPC (chatHandlers.ts — new handlers)
6. UI (SettingsView.tsx, ChatPanel.tsx — key input, model grouping)
7. Build verification

Key Differences to Handle

Aspect	OpenCode/OpenAI	Mistral
Base URL	opencode.ai/zen/v1/...	api.mistral.ai/v1/...
Auth header	Bearer ${openCodeKey}	Bearer ${mistralKey}
Tool choice forced	"required"	"any"
Parallel tools	not set	parallel_tool_calls: true
Context budget	150k tokens	35k (Large/Medium), 120k (Small)
Vision format	image_url block	image_url block (same)
Streaming	SSE deltas	SSE deltas (same)

Verification

1. Run npm test — all existing + new tests pass
2. Run npm run build — clean build
3. Manual: set Mistral API key in Settings, verify validation
4. Manual: select Mistral Large 3, send chat message, verify response streams
5. Manual: use view_image tool in chat with Mistral model, verify vision works
6. Manual: verify tool calling works (search_posts, list_posts, etc.)
7. Manual: verify OpenCode models still work unchanged

Resolved Decisions

1. analyzeMediaImage() — Mistral models will be usable for image metadata analysis
2. MCP server — N/A; MCP server only exposes tools, no bDS-side AI runs during MCP requests
3. Model dropdown grouping — Use <optgroup> labels ("OpenCode Zen", "Mistral AI")