ADR-0008: LLM access behind a stable provider interface

• Status: Accepted
• Date: 2026-06-24
• Deciders: jka
• Decision: D8

Context

rio integrates AI agents, but specific model services change constantly: APIs are versioned and renamed, vendors come and go, and local model servers each have their own conventions. Wire details of any one service should never reach the core.

Decision

The core defines a stable provider interface: given a conversation and the available tools, stream assistant output and tool-call requests. Concrete providers implement it and absorb the service-specific wire details (HTTP, JSON, SSE, authentication). Providers are extensions, not core modules. rio's own providers dogfood the interface: a hosted one (Claude) and an OpenAI-compatible one that also covers local servers such as Ollama and llama-server.

A provider is a protocol participant over the thin extension seam. It does not need the full plugin platform of ADR-0016 to ADR-0019, so providers could ship with the first agent slice.

Consequences

• Vendor churn is contained in provider code.
• The provider contract has to stay small and be versioned once outsiders build against it. ADR-0065 hardened it with a second implementation and ADR-0066 versioned it as provider-api.
• The division between the core loop and providers is described in ADR-0020.