AI context tools: a formal pre-fetch enrichment registry (+ image OCR)
Added
lib/ai/tools/ — a typed context-tool registry (Phase B of the AI tooling
work). Card enrichment (what expands a raw card into substance the model can
reason over) was an inline if/else buried in ai-enrich.ts. It's now a formal
registry: a ContextTool contract (types.ts), a network-free, unit-tested
orchestrator that selects one tool per card under per-tool fan-out caps and a
concurrency bound (runner.ts), the extraction logic (extractors.ts), and
the concrete tool set (index.ts). Adding a capability is now a single entry.
Tools are pre-fetch only — they run once, before the model call, never
as an agentic loop. No extra model round-trips, and no outbound surface
beyond the card's own source. Cost- and SSRF-safe by construction.
Image OCR. The vision tool now does recognition and OCR in a single
call — it returns a short DESCRIPTION of the image plus a verbatim TEXT
transcription of any labels/numbers in it (screenshots, charts, diagrams),
instead of a description alone. No new dependency (reuses the vision path); no
second model call. Still gated by AI_IMAGE_CAPTIONS=1 (paid, off by default).
Changed
lib/ai-enrich.ts is now a thin compatibility re-export of the registry, so
existing importers (enrichCards, sha) are unchanged.
Tool results remain untrusted — they enter the prompt through the Phase-A
guardrail delimiters. New tools must follow the rules in docs/AI_SAFETY.md.
Notes
Covered by tests/ai-tools.test.ts (tool selection, cap enforcement, seed
short-circuit). No behavior change to existing enrichment beyond the richer
image output.
