Skip to content

adr-provider-agnostic-llm-client

Decision

Institutionalise provider-agnostic-llm-client as an authoritative architectural pattern across the platform following Reference Architecture ratification.

Context

  • Source: governance-flow
  • Pattern: provider-agnostic-llm-client
  • Promotion Recommendation: recommendation-provider-agnostic-llm-client
  • Scope Classification: global
  • Scope Classification Artifact: pattern-scope-classification

Language model provider SDKs undergo rapid evolution and vary in invocation semantics. Decoupling agent reasoning logic from concrete model providers via a unified client abstraction pairing live router implementations with deterministic test doubles is required to avoid vendor lock-in and enable deterministic offline verification.

Scope

Applicability: Applies across all agent execution pipelines, LLM invocations, and test suites within ideas-to-life-cas and downstream projects adopting CAS governance.

Global architectural pattern governing model provider integration and testing doubles.

Consequences

Governance

All platform components must interface with LLMs through the ratified provider-agnostic abstraction; direct usage of vendor-specific SDKs is prohibited.

Execution

FlowRunner and governance steps utilize LiteLLMClient in operational runs and switch to MockLLMClient for deterministic CI/CD execution.

System Behaviour

Eliminates vendor SDK coupling, standardizes token usage and error handling, and enables zero-cost deterministic offline execution for integration tests.

Evidence Summary

Promotion Evidence

Ratified Reference Architecture in ArchGov with verified implementations across LiteLLMClient and MockLLMClient test doubles.

Promotion Criteria

Satisfied governance maturity and ratified reference architecture criteria.

Governance Risks

None identified during formal promotion review.

Traceability

Pattern Proposal

provider-agnostic-llm-client

Scope Classification

Artifact: pattern-scope-classification

Classification: global

Promotion Recommendation

recommendation-provider-agnostic-llm-client

Promotion Decision

promotion-decision-provider-agnostic-llm-client

Next Step

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