Provider

The Provider primitive abstracts LLM inference endpoints. A Claw can reference multiple providers with fallback chains, cost routing, and capability-based selection. At least one Provider is required in every manifest.

URI pattern: claw://local/provider/{name}

---

Schema

claw: "0.3.0"
kind: Provider
metadata:
  name: "primary-llm"
  version: "1.0.0"
spec:
  protocol: "openai-compatible"   # "openai-compatible" | "anthropic-native" | "custom"
  endpoint: "https://api.example.com/v1"
  model: "gpt-5-turbo"

  auth:
    type: "bearer"                # "bearer" | "api-key-header" | "oauth2" | "none"
    secret_ref: "LLM_API_KEY"

  streaming: true

  hints:
    cost_priority: 0.3            # 0.0 (ignore cost) to 1.0 (minimize cost)
    speed_priority: 0.5           # 0.0 (ignore speed) to 1.0 (minimize latency)
    intelligence_priority: 0.8    # 0.0 (any quality) to 1.0 (maximize quality)

  fallback:
    - provider_ref: "secondary-llm"
    - provider_ref: "local-llm"

  limits:
    tokens_per_day: 500000
    tokens_per_request: 32000
    requests_per_minute: 60
    max_context_window: 200000

  retry:
    max_attempts: 3
    backoff: "exponential"        # "exponential" | "linear" | "constant"
    initial_delay_ms: 1000

---

Key Fields

Field	Required	Description
protocol	Yes	Protocol for communicating with the LLM endpoint.
endpoint	Yes	Base URL for the inference API.
model	Yes	Model identifier string.
auth	Yes	Authentication configuration.
auth.type	Yes	One of bearer, api-key-header, oauth2, none.
auth.secret_ref	Conditional	Environment variable or secret store key. Required when auth.type is not none.
streaming	No	Enable streaming responses.
hints	No	Model selection hints following MCP’s modelPreferences pattern.
fallback	No	Ordered fallback chain of alternative providers.
limits	No	Usage limits for cost governance.
retry	No	Retry configuration for transient failures.

---

Validation Rules

• A Claw manifest MUST include at least one Provider primitive.
• The protocol, endpoint, model, and auth fields are REQUIRED.
• When auth.type is not none, auth.secret_ref MUST be present.
• Fallback providers, if declared, MUST be tried in array order. The runtime MUST NOT skip entries.
• If limits.tokens_per_day is present, the runtime MUST enforce it and reject requests that would exceed the limit with error code -32021.

---

Design Rationale

The Provider primitive normalizes multi-LLM abstraction, cascading fallback, cost-aware routing, and token governance into a single declaration. The hints field follows MCP’s modelPreferences pattern, enabling runtimes to make intelligent routing decisions across multiple providers without framework-specific configuration.