ADR-007: AI Provider — Gemini 1.5 Flash

Status

Accepted

Context

We wanted optional, on-demand summaries that feel near-instant but don’t crush wallets. Users should be able to paste their own key, yet the system should still work with a team-provided fallback for demos.

Options considered

  • Gemini 1.5 Flash — Fast, inexpensive, simple REST interface.
  • OpenAI GPT-4o mini — Great quality, pricier, slightly higher latency.
  • Anthropic Claude 3 Haiku — Strong summaries, more complex pricing.

Decision

Gemini 1.5 Flash wins the first round. /api/ai/summarize plucks the user’s stored key (or the fallback GEMINI_API_KEY), calls the REST endpoint, and caches the TL;DR in items.metadata.ai_summary. The full flow lives in web/src/app/api/ai/summarize/route.ts.

Consequences

Upside

  • Users stay in control of their spend: no key, no summary.
  • Cost per call is low, response times are solid.
  • We store provider metadata alongside summaries, ready to pivot later.

Trade-offs

  • Response format is specific to Gemini; switching providers means adapting parsing logic.
  • Requires users to enable billing on their Google Cloud project.
  • Summarizer route: web/src/app/api/ai/summarize/route.ts
  • API key storage: web/src/app/api/ai/key/route.ts
  • Related ADRs: ADR-002, ADR-001