Skip to content

ADR-002: LLM provider for rationale generation

Status: Accepted. Silent-fallback semantics for the Clarifier are superseded by ADR-008. Source: prd.md §19

Context

The recommendation engine generates a human-readable rationale for the Next-Best-Action shown to the executive. Calling Bedrock requires AWS credentials and IAM model-access grants that may exceed the time budget on Day 1.

Decision

Default to Bedrock; fall back to direct Anthropic API if Bedrock IAM/credentials block progress past 11:00 Day 2. The fallback is a configuration switch (USE_BEDROCK=false), not a silent runtime substitution. See docs/open-questions-resolved.md row Q1 for the resolution.

Consequences

  • The recommendation rationale path always has a working LLM backend on demo day, regardless of which credentialing path completes first.
  • The eventual production stack uses Bedrock (matching ADR-007's metric-aware Clarifier and ADR-005's widget builder).
  • The widget Clarifier's silent-fallback behavior introduced via this ADR was superseded by ADR-008. In live mode, Bedrock failures surface as a structured BuilderModeError instead of substituting MockLlm. The decision-rationale fallback under ADR-003 (templated string on Bedrock error) is unchanged and still in force — it is not the silent-substitution failure mode ADR-008 forbids.

Cross-references

  • ADR-003 — the templated fallback for the rationale path itself.
  • ADR-005 — the Clarifier consumes Bedrock; its mock fallback was governed by ADR-002 and is now governed by ADR-008.
  • ADR-008 — supersedes ADR-002's silent-fallback semantics for the Clarifier specifically.