Cache (Inference Cache): foundations

accepted

Status

accepted — ratificada 2026-05-09 (mesmo dia da abertura) como parte da onda piloto de bootstrap servicesai. Implementação iniciada em `servicesaicache; tickets em servicesaicachebacklogpending/{001..005}`.

Summary

Cache de respostas de inference — análogo OpenAI prompt cache, Helicone, Portkey. Reduz custo + latência do gateway.

Motivation

Gateway roteia mas não cacheia. Custo gateway sobe linear com chamadas; mesmo prompt repetido paga 100%. Helicone/Portkey reportam 30-60% economia em workloads típicos.

Scope

In

  • Exact-match cache
  • Semantic cache (via embed)
  • TTL configurável
  • Per-tenant quotas
  • Invalidação

Out (yet)

  • KV cache do modelo (escopo de runtime)
  • Edge cache (escopo de jet)

Initial design

Surfaces

  • backend/ — middleware Go integrado ao gateway + API ops
  • app/ — não aplicável v1

Key APIs

  • middleware do gateway (X-Cache: HIT/MISS header)
  • GET /v1/cache/stats — métricas
  • DELETE /v1/cache/keys — invalidação manual

Dependencies

  • services/ai/gateway — integração via middleware
  • services/ai/embed — semantic match
  • infra/data/kdb-kv — backend de storage

Relation to existing sectors

  • Subsistema do gateway (transparent cache layer)
  • Consome embed para semantic dedup

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero
  • G2 Performance: N/A
  • G3 Stability: N/A
  • G4 Capability: simples
  • G5 Critical-path readiness: destrava economia substancial

Open questions

  • Q1: Cache de respostas com tools — invalida sempre?
  • Q2: TTL default por endpoint?

Next steps

  1. Ratificar esta RFC (1 round de comments).
  2. Criar sector dir services/ai/cache/ com koder.toml, README.md, skeleton.
  3. Abrir tickets de implementação em services/ai/cache/backlog/pending/.
  4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.