Cache (Inference Cache) — foundations RFC

Status

*ccepted*— ratificada 20260509 (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

Selfhostedfirst analysis (5 gates)

• *1 Feature parity* zero
• *2 Performance* N/A
• *3 Stability* N/A
• *4 Capability* simples
• *5 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.