Vision: foundations

accepted

Status

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

Summary

Foundation service para análise de imagem e VLM (vision-language models) — OCR server-side, image captioning, object detection, document layout, e roteamento pra modelos multimodais (ClaudeGeminiGPT-4V) via gateway.

Motivation

Modelos flagship em 2026 são todos multimodais. Koder Stack tem foundation só pra áudio (voice/); vision está espalhada (kode/app OCR, eye on-device OCR, document analysis ad-hoc no kode). Sem service-foundation, cada produto reinventa a roda.

Scope

In

  • Server-side OCR
  • Image captioning
  • Object detection
  • Doc layout (PDF + tabelas)
  • Proxy pra VLMs externos via gateway
  • Kit Dart/JS no SDK

Out (yet)

  • Image generation (vai pra imaging)
  • Video (vai pra video)
  • 3D (vai pra scene3d)
  • Eye-style on-device (já existe em products/dev/konsul)

Initial design

Surfaces

  • backend/ — Go API service exposto via gateway
  • app/ — não aplicável v1 (consumido via SDK)

Key APIs

  • POST /v1/vision/ocr — extrai texto de imagem/PDF
  • POST /v1/vision/caption — gera descrição textual de imagem
  • POST /v1/vision/detect — bounding boxes + labels
  • POST /v1/vision/layout — estrutura de documento (heading, body, table, figure)

Dependencies

  • services/ai/gateway — provider routing pra VLMs externos
  • services/ai/runtime — modelos locais (Florence-2, CLIP)
  • infra/data/kdb-blob — armazenamento de imagens/resultados

Relation to existing sectors

  • Complementa voice/ (audio) cobrindo a outra metade da modalidade humana
  • Sobrepõe parcialmente com products/dev/konsul (on-device); este service cobre casos server-only

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero impl
  • G2 Performance: N/A (não há baseline self-hosted)
  • G3 Stability: N/A
  • G4 Capability: cobertura inicial OCR + caption viável local (Tesseract + Florence-2)
  • G5 Critical-path readiness: bloqueia kodeagentseye unification

Open questions

  • Q1: Quais modelos VLM rodar self-hosted vs apenas proxy?
  • Q2: Sobreposição com products/dev/konsul (on-device) — service serve casos server-only?

Next steps

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