ADR-0005: Model-Provider-Abstraktion

Kontext

mvest soll nicht an einen einzelnen LLM-Anbieter gebunden sein. Gründe: unterschiedliche Stärken pro Modell, deutliche Kostendifferenzen, Provider-Ausfälle, und für den Critic-Agent ist Provider-Diversität ein zentraler Verifikations-Hebel (siehe ADR-0003).

Pydantic AI (ADR-0004) bringt Multi-Provider-Support nativ mit. Dennoch braucht es eine eigene Konfigurations-Schicht, damit pro Agent eindeutig festgelegt werden kann, welches Modell zum Einsatz kommt, und damit Wechsel ohne Code-Änderung möglich sind.

Entscheidungstreiber

• Kein Provider-Lock-in — wechselbar pro Agent, idealerweise ohne Code-Änderung.
• Pro-Agent-Tuning: günstige/kleine Modelle für leichte Schritte (Screener), große für synthetische Schritte (Strategy).
• Critic-Diversität: Critic-Agent muss auf einem anderen Provider laufen als Strategy. Konfiguration muss diese Garantie ermöglichen.
• Fallback-Strategie: wenn Primary-Provider ausfällt, definierter Fallback (oder klares Fail-Verhalten).
• Cost-Tracking: Token-Verbrauch pro Provider/Modell/Agent erfassen.
• Reversibilität: Modellauswahl darf nicht im Code festgenagelt sein — gehört in Konfiguration.

Entscheidung

Wir nutzen Pydantic AIs eingebaute Provider-Abstraktion als technische Basis und ergänzen sie um eine eigene Konfigurations-Schicht:

Provider-Auswahl (unterstützt in v1)

Konfigurations-Schema

Modellauswahl pro Agent erfolgt in einer Konfigurationsdatei (config/agents.yaml), nicht im Code:

# config/agents.yaml
agents:
  screener:
    primary:  { provider: anthropic, model: claude-haiku-4-5 }
    fallback: { provider: openai,    model: gpt-4o-mini }

  research:
    primary:  { provider: anthropic, model: claude-sonnet-4-6 }
    fallback: { provider: openai,    model: gpt-4o }

  analyst:
    primary:  { provider: anthropic, model: claude-sonnet-4-6 }
    fallback: { provider: google,    model: gemini-pro }

  strategy:
    primary:  { provider: anthropic, model: claude-opus-4-7 }
    fallback: { provider: openai,    model: gpt-5 }

  critic:
    # MUSS anderer Provider als strategy sein
    primary:  { provider: openai,    model: gpt-5 }
    fallback: { provider: google,    model: gemini-pro }
    constraint: provider_must_differ_from: strategy

  risk_assessment:
    primary:  { provider: anthropic, model: claude-haiku-4-5 }
    fallback: { provider: openai,    model: gpt-4o-mini }

Eigene Schicht über Pydantic AI

Ein AgentModelFactory liest die Konfiguration und erzeugt Pydantic-AI-Model-Instanzen:

class AgentModelSpec(BaseModel):
    provider: ProviderId          # enum: anthropic | openai | google | ...
    model: str                    # modell-id-string (provider-spezifisch)

class AgentConfig(BaseModel):
    primary: AgentModelSpec
    fallback: AgentModelSpec | None = None
    constraint: dict | None = None  # z. B. provider_must_differ_from

def build_model(spec: AgentModelSpec) -> pydantic_ai.Model:
    match spec.provider:
        case ProviderId.ANTHROPIC: return AnthropicModel(spec.model)
        case ProviderId.OPENAI:    return OpenAIModel(spec.model)
        ...

Fallback-Strategie

• Trigger: Primary-Provider liefert HTTP-5xx, Rate-Limit-Error, oder Timeout (> konfigurierbar).
• Verhalten: Falls fallback definiert ist → Retry mit Fallback-Model; used_model wird im Decision-Log markiert. Falls kein Fallback definiert → Agent-Step schlägt fehl, Coordinator entscheidet (Skip mit Markierung vs. Abort des Runs).
• Keine automatischen Cascading-Fallbacks — höchstens ein Fallback pro Step, sonst wird die Kosten- und Verifikations-Lage intransparent.

Constraint-Validierung

Beim App-Start wird die Konfiguration validiert. Constraint provider_must_differ_from: strategy beim Critic prüft, dass Provider von Critic und Strategy verschieden sind — andernfalls Start-Abbruch mit klarer Fehlermeldung.

API-Keys & Secrets

• Alle Provider-Keys in .env (gitignored).
• .env.example listet alle möglichen Keys mit leerem Wert.
• App-Start prüft, dass für alle in der Konfiguration referenzierten Provider die entsprechenden Env-Vars gesetzt sind. Fehlende Keys → klarer Start-Fehler.

Cost-Tracking

• Jeder Agent-Call protokolliert: Provider, Modell, Input-Tokens, Output-Tokens, geschätzte Kosten in USD.
• Diese Daten gehen ins Decision-Log (ADR-0012) und werden in der Web-UI pro Run aggregiert.
• Preise pro Modell werden in config/pricing.yaml gepflegt (manuell aktualisierbar, fern von Code-Logik).

Konsequenzen

Positiv

• Provider-Wechsel ohne Code-Änderung — nur YAML.
• Critic-Diversität deklarativ erzwungen.
• Kosten transparent und pro Agent zuordenbar.
• Lokale Modelle (Ollama) als Dev-Loop ohne Kosten-Risiko möglich.

Negativ / Trade-offs

• Modell-IDs sind provider-spezifische Strings — Tippfehler scheitern erst zur Laufzeit. Mitigation: Schema-Validation beim App-Start, Test der Connectivity zu allen konfigurierten Providern.
• Pricing-Tabelle manuell pflegen — Mitigation: Eintrag im Decision-Log mit „price_table_version" für Rückverfolgbarkeit.
• Fallbacks erhöhen Komplexität (Decision-Log muss used_model tracken, Critic-Constraint muss auch im Fallback gelten). Mitigation: Constraint-Check gilt für Primary und Fallback.