Skip to content

adr-provider-agnostic-llm-gateway

Decision

Adopt and institutionalise provider-agnostic-llm-gateway as a global core pattern, standardising decoupling between agentic reasoning workflows and downstream model providers.

Context

  • Source: promotion-decision-workflow
  • Pattern: provider-agnostic-llm-gateway
  • Promotion Recommendation: recommendation-provider-agnostic-llm-gateway
  • Scope Classification: global
  • Scope Classification Artifact: pattern-scope-classification

Multiple candidate patterns converged on encapsulating external model interaction behind a unified interface with live router (LiteLLMClient) and deterministic test double (MockLLMClient) implementations to eliminate vendor coupling and enable hermetic offline CI.

Scope

Applicability: Global across all autonomous agent execution components, governance evaluation steps, and test suites.

Standard architectural facade mandatory for all LLM interactions across continuous architecture workflows.

Consequences

Governance

Centralises model invocation governance, establishes auditable routing policies, and enforces unified call contracts across all projects.

Execution

Allows transparent switching between production multi-model gateways and zero-cost deterministic mock doubles during CI test execution.

System Behaviour

Decouples reasoning logic from provider API churn, normalises error handling, and eliminates flakiness during integration testing.

Evidence Summary

Promotion Evidence

Validated by current architecture state components (LiteLLMClient, MockLLMClient in src/cas_runner/llm/), cross-project applicability, recurring signals, and verified production usage.

Promotion Criteria

Satisfied significance, reusability, recurrence, evidence quality, governance maturity, and strategic alignment criteria.

Governance Risks

Subtle provider streaming semantic differences across multi-model deployments must be monitored and normalised.

Traceability

Pattern Proposal

provider-agnostic-llm-gateway

Scope Classification

Artifact: pattern-scope-classification

Classification: global

Promotion Recommendation

recommendation-provider-agnostic-llm-gateway

Promotion Decision

promotion-decision-provider-agnostic-llm-gateway

Next Step

  • Submit ADR to Architecture Forum for formal institutionalisation
  • Generate global pattern record in knowledge/global/patterns/