AGENTS.md

1# modelgateway — SDP Runtime Assumptions
2 
3## Context Objects
4Chat completions: ChatRequest (model, messages, temp, tokens), ChatResponse (message, usage, finish reason)
5Routing: RoutingDecision (provider, fallback, policy), RoutingInput (task class, sensitivity, constraints)
6RoutingEvidence: Decision + hash + timestamp for audit
7 
8## Environment
9API keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, SDP_PROVIDER_<ID>_API_KEY
10Custom endpoints: SDP_PROVIDER_<ID>_BASE_URL
11No env vars for routing-only mode (PolicyRouter without providers)
12 
13## Configuration
14Provider (ProviderConfig): ID, key, base URL, model, timeout, retries, rate limits
15Router (RouterConfig): Default provider, fallback order, routing rules
16Tenant (TenantConfig): Tenant ID, provider, constraints, rate limits
17Constraints: Allowed providers/models, max cost per token, data residency
18 
19## Dependencies
20From `internal/kernel`: ProviderID, ModelID, ModelCapabilities, RoutingInput/Decision/Constraints, TaskClass, SensitivityLevel
21**Risk**: Kernel is shared substrate; breaking changes need coordinated updates across modelgateway, agent runtime, policy
22 
23## Allowlist Behavior
24- Checked in PolicyRouter.Route() before provider selection
25- TenantConfig.Constraints.AllowedProviders ([]ProviderID)
26- Empty list = allow all; non-empty = restrict to listed providers
27- Tenant-level override applies after policy evaluation
28 
29## Cost Envelope
30Per-request: MaxTokensPerRequest enforced before call
31Daily: MaxTokensPerDay aggregated across providers
32Cost: CostPerToken (USD/1K) * token count
33Rejection: ErrorTypeInvalidInput when limits exceeded
34Reset: Midnight UTC
35 
36## Fallback Behavior
37Ordered chain: FallbackChain attempted sequentially
38Retryable: rate limits, timeouts (ErrorTypeRateLimit, ErrorTypeTimeout)
39Non-retryable: auth failures, invalid input, model unavailable
40Max retries: ProviderConfig.MaxRetries
41Exhaustion: ProviderError "ALL_PROVIDERS_FAILED"
42