Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
347
AirPlan/docs/architecture/provider-capability-matrix-v1.md
Normal file
347
AirPlan/docs/architecture/provider-capability-matrix-v1.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# AirCoding Provider Capability Matrix V1
|
||||
|
||||
Date: 2026-05-27
|
||||
Status: Canonical provider/model capability contract for V1.0.0 Alpha skeleton
|
||||
|
||||
This document defines how AirCoding represents provider/model capabilities, selects models, handles conversion limits, and records fallback behavior.
|
||||
|
||||
AirCoding's internal canonical message format is Anthropic content blocks. Provider adapters own conversion.
|
||||
|
||||
## 1. Goals
|
||||
|
||||
The provider capability matrix must answer:
|
||||
|
||||
1. Can this model/tool path execute the requested task?
|
||||
2. Which capabilities are native vs emulated?
|
||||
3. What quality/risk tier is acceptable for the task?
|
||||
4. What conversion or feature loss must be recorded?
|
||||
5. When should Scheduler force a model vs let an agent choose?
|
||||
|
||||
## 2. Provider Identity
|
||||
|
||||
```ts
|
||||
type ProviderKind =
|
||||
| "anthropic"
|
||||
| "openai"
|
||||
| "openrouter"
|
||||
| "ollama"
|
||||
| "anthropic_compatible"
|
||||
| "openai_compatible"
|
||||
| "custom"
|
||||
|
||||
interface ProviderIdentity {
|
||||
provider_id: string
|
||||
provider_kind: ProviderKind
|
||||
display_name: string
|
||||
base_url?: string
|
||||
auth_ref?: string
|
||||
local: boolean
|
||||
}
|
||||
```
|
||||
|
||||
Secrets are referenced by `auth_ref`; they are never embedded in session DB events or artifacts.
|
||||
|
||||
## 3. Model Capability Matrix
|
||||
|
||||
```ts
|
||||
interface ProviderCapabilityMatrix {
|
||||
provider_id: string
|
||||
provider_kind: ProviderKind
|
||||
model_id: string
|
||||
display_name?: string
|
||||
enabled: boolean
|
||||
quality_tier: "frontier" | "strong" | "standard" | "cheap" | "local" | "unknown"
|
||||
cost_tier: "high" | "medium" | "low" | "free" | "unknown"
|
||||
context_window_tokens?: number
|
||||
max_output_tokens?: number
|
||||
supports: {
|
||||
text_input: boolean
|
||||
text_output: boolean
|
||||
streaming: boolean
|
||||
tool_use: boolean
|
||||
parallel_tool_use: boolean
|
||||
structured_output: boolean
|
||||
json_mode: boolean
|
||||
thinking: boolean
|
||||
prompt_cache: boolean
|
||||
system_prompt: boolean
|
||||
image_input: boolean
|
||||
image_output: boolean
|
||||
audio_input: boolean
|
||||
audio_output: boolean
|
||||
file_input: boolean
|
||||
computer_use: boolean
|
||||
long_context: boolean
|
||||
batch: boolean
|
||||
}
|
||||
conversion: {
|
||||
from_anthropic_canonical: "lossless" | "lossy" | "unsupported"
|
||||
tool_schema: "native" | "converted" | "emulated" | "unsupported"
|
||||
image_input: "native" | "artifact_link" | "unsupported"
|
||||
thinking: "native" | "stripped" | "unsupported"
|
||||
cache_control: "native" | "ignored" | "unsupported"
|
||||
}
|
||||
limits?: {
|
||||
requests_per_minute?: number
|
||||
tokens_per_minute?: number
|
||||
concurrent_requests?: number
|
||||
max_tool_schema_bytes?: number
|
||||
max_image_count?: number
|
||||
max_file_bytes?: number
|
||||
}
|
||||
default_use?: {
|
||||
main?: boolean
|
||||
architecture?: boolean
|
||||
execute?: boolean
|
||||
review?: boolean
|
||||
debug?: boolean
|
||||
compact?: boolean
|
||||
mine_experience?: boolean
|
||||
}
|
||||
notes?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Capability Semantics
|
||||
|
||||
### `tool_use`
|
||||
|
||||
Native model-driven tool invocation.
|
||||
|
||||
If false, agents may still call deterministic internal tools outside model tool-use, but the model cannot choose tool calls directly in a single turn. This is lower quality for coding execution.
|
||||
|
||||
### `parallel_tool_use`
|
||||
|
||||
Model can request multiple tool calls in one turn. Scheduler/ToolRegistry may still serialize unsafe tools.
|
||||
|
||||
### `structured_output` / `json_mode`
|
||||
|
||||
Used for WorkerResult, review reports, scheduler decisions, and impact assessments. If unavailable, runtime validates best-effort parsed JSON and may retry with stricter prompt.
|
||||
|
||||
### `thinking`
|
||||
|
||||
Model supports a distinct reasoning/thinking channel or equivalent. If converted/stripped, the adapter must ensure hidden reasoning is not persisted as user-visible content.
|
||||
|
||||
### `prompt_cache`
|
||||
|
||||
Provider supports cache-control or equivalent prompt reuse. If unsupported, ContextAssembler still works but cost may be higher.
|
||||
|
||||
### `image_input`
|
||||
|
||||
Required for screenshot/UI analysis, diagram analysis, and image-based debugging.
|
||||
|
||||
### `image_output`
|
||||
|
||||
Required for first-class image generation. If unavailable, `ui-design-assets` falls back to SVG/assets/prompts.
|
||||
|
||||
### `computer_use`
|
||||
|
||||
Post-MVP. V1 uses explicit tools for GUI/screenshot/network rather than opaque computer-use loops.
|
||||
|
||||
## 5. Task Capability Requirements
|
||||
|
||||
```ts
|
||||
interface ModelRequirement {
|
||||
required: Partial<ProviderCapabilityMatrix["supports"]>
|
||||
preferred?: Partial<ProviderCapabilityMatrix["supports"]>
|
||||
min_quality_tier?: "frontier" | "strong" | "standard" | "cheap" | "local"
|
||||
max_cost_tier?: "high" | "medium" | "low" | "free"
|
||||
min_context_window_tokens?: number
|
||||
allow_lossy_conversion?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
Default requirements by task type:
|
||||
|
||||
| Task type | Required | Preferred | Quality floor |
|
||||
|---|---|---|---|
|
||||
| Main conversation | streaming, tool_use | prompt_cache, long_context | strong |
|
||||
| Architecture Designer | structured_output, long_context | thinking, prompt_cache | frontier/strong |
|
||||
| Executor | tool_use, structured_output | thinking, long_context | frontier/strong |
|
||||
| Reviewer | structured_output | image_input for UI artifacts | strong |
|
||||
| Debugger | tool_use, structured_output | long_context, image_input | strong |
|
||||
| Compactor | long_context or large enough context | prompt_cache | standard |
|
||||
| ExperienceMiner | structured_output | long_context | standard |
|
||||
| UI screenshot analysis | image_input | structured_output | strong |
|
||||
| Image generation | image_output | image editing | provider-specific |
|
||||
|
||||
## 6. Scheduler Model Assignment
|
||||
|
||||
Scheduler chooses one of:
|
||||
|
||||
```ts
|
||||
type ModelAssignmentMode = "scheduler_forced" | "agent_select"
|
||||
|
||||
interface ModelAssignment {
|
||||
mode: ModelAssignmentMode
|
||||
provider_id?: string
|
||||
model_id?: string
|
||||
allowed_models?: Array<{ provider_id: string; model_id: string }>
|
||||
requirement: ModelRequirement
|
||||
reason: string
|
||||
}
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
|
||||
1. Use `scheduler_forced` for cross-model review, high-risk tasks, repeated failures, and deterministic comparisons.
|
||||
2. Use `agent_select` for normal implementation/debug tasks when multiple acceptable models exist.
|
||||
3. Use strong/frontier models for code-changing tasks where hidden complexity may exist.
|
||||
4. Use cheaper models for summarization, indexing, and low-risk classification when evidence can be validated.
|
||||
5. Escalate if no model satisfies required capabilities.
|
||||
|
||||
## 7. Provider Adapter Contract
|
||||
|
||||
```ts
|
||||
interface ProviderAdapter {
|
||||
provider_id: string
|
||||
list_models(): Promise<ProviderCapabilityMatrix[]>
|
||||
validate_model(model_id: string): Promise<ProviderCapabilityMatrix>
|
||||
complete(input: ProviderCompletionInput): AsyncIterable<ProviderStreamEvent>
|
||||
count_tokens?(input: unknown): Promise<number>
|
||||
}
|
||||
|
||||
interface ProviderCompletionInput {
|
||||
model_id: string
|
||||
canonical_format: "anthropic"
|
||||
messages: unknown[]
|
||||
tools?: unknown[]
|
||||
tool_choice?: unknown
|
||||
system?: unknown
|
||||
max_output_tokens?: number
|
||||
temperature?: number
|
||||
metadata?: Record<string, unknown>
|
||||
}
|
||||
```
|
||||
|
||||
Adapter responsibilities:
|
||||
|
||||
1. Convert Anthropic canonical messages to provider format.
|
||||
2. Convert provider output back to Anthropic canonical content blocks or RuntimeEvents.
|
||||
3. Validate tool-call and structured-output compatibility.
|
||||
4. Record conversion omissions/losses.
|
||||
5. Never leak credentials into logs, events, artifacts, or model-visible messages.
|
||||
|
||||
## 8. Conversion Loss Handling
|
||||
|
||||
Conversion result:
|
||||
|
||||
```ts
|
||||
interface ProviderConversionReport {
|
||||
status: "lossless" | "lossy" | "unsupported"
|
||||
omissions: string[]
|
||||
warnings: string[]
|
||||
required_confirmation?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. Lossless conversion continues silently.
|
||||
2. Lossy conversion may continue only if `allow_lossy_conversion` is true and omitted features are not required.
|
||||
3. Unsupported required feature blocks before model call.
|
||||
4. Thinking/cache-control stripping is allowed only when not required by task policy.
|
||||
5. Tool schema truncation or unsupported required tool use blocks.
|
||||
|
||||
## 9. Configuration Locations
|
||||
|
||||
Global provider/model config:
|
||||
|
||||
```text
|
||||
~/.air/models.yaml
|
||||
```
|
||||
|
||||
Project override:
|
||||
|
||||
```text
|
||||
<project>/.air/shared/models.yaml
|
||||
```
|
||||
|
||||
Session records store selected `model_provider_id` and `model_id`, but not secrets.
|
||||
|
||||
Example config shape:
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
- provider_id: anthropic-main
|
||||
provider_kind: anthropic
|
||||
display_name: Anthropic
|
||||
auth_ref: env:ANTHROPIC_API_KEY
|
||||
enabled: true
|
||||
models:
|
||||
- model_id: claude-opus-4-7
|
||||
quality_tier: frontier
|
||||
cost_tier: high
|
||||
default_use:
|
||||
architecture: true
|
||||
execute: true
|
||||
review: true
|
||||
- model_id: claude-sonnet-4-6
|
||||
quality_tier: strong
|
||||
cost_tier: medium
|
||||
default_use:
|
||||
main: true
|
||||
debug: true
|
||||
compact: true
|
||||
```
|
||||
|
||||
## 10. Doctor Checks
|
||||
|
||||
Doctor validates:
|
||||
|
||||
```text
|
||||
provider config parseability
|
||||
auth_ref existence without printing secret values
|
||||
base_url reachability when allowed
|
||||
model list/validation where provider supports it
|
||||
required default model coverage by role
|
||||
capability mismatch warnings
|
||||
rate-limit metadata if configured
|
||||
```
|
||||
|
||||
Doctor must not persist or print API keys.
|
||||
|
||||
## 11. Fallback Policy
|
||||
|
||||
Fallback order:
|
||||
|
||||
1. Same provider, same quality tier, compatible model.
|
||||
2. Same provider, higher quality tier if allowed.
|
||||
3. Different provider with lossless/acceptable conversion.
|
||||
4. Lower quality tier only for non-code-changing or explicitly allowed tasks.
|
||||
5. Block and ask Main Agent/user if no safe fallback exists.
|
||||
|
||||
Fallback must record:
|
||||
|
||||
```text
|
||||
original provider/model
|
||||
selected provider/model
|
||||
reason
|
||||
capability differences
|
||||
conversion report
|
||||
```
|
||||
|
||||
## 12. V1.0.0 Alpha Cut Line
|
||||
|
||||
V1.0.0 Alpha skeleton must implement:
|
||||
|
||||
1. `ProviderCapabilityMatrix` contract.
|
||||
2. Global/project model config loading.
|
||||
3. Anthropic and OpenAI-compatible adapter interfaces.
|
||||
4. Capability-based model selection.
|
||||
5. Conversion report and omission handling.
|
||||
6. Scheduler model assignment integration.
|
||||
7. Doctor provider checks.
|
||||
8. Session persistence of chosen provider/model IDs.
|
||||
|
||||
Post-MVP:
|
||||
|
||||
```text
|
||||
automatic provider benchmarking
|
||||
cost optimizer
|
||||
multi-provider speculative review
|
||||
batch processing
|
||||
computer-use models
|
||||
native image-generation providers
|
||||
local model quality calibration
|
||||
```
|
||||
Reference in New Issue
Block a user