Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/centralized-registry

centralized-registry

Verified


name: centralized-registry description: The single source of truth for models, schemas, pipelines, and stacks. Load when adding/changing/toggling any model, schema, pipeline, or stack. Covers MODEL_REGISTRY (52 entries / 7 families including the 22-entry ocr_vision subset + 6 CLASSICAL_OCR backends + BIEP v2 4-path ensemble), notebooks/_shared/schema.py (5 introspection helpers), deployment-choice.yaml (the enablement file), notebooks/00_control_panel.py (the 5-tab marimo control panel), and the central registry audit via mise run lint:registry. Per the centralized-model-registry + centralized-schema-registry + deployment-control-panel openspec capabilities (post-2026-08-15; §11 OCR/VLM Pipeline added 2026-08-13).

Centralized Registries — Models, Schemas, Pipelines, Stacks

Version: 2026-08-13 | Last Updated: 2026-08-13 (added §11 OCR/VLM Pipeline)

The Cianfhoghlaim platform now has one canonical source of truth for every model, schema, pipeline, and stack. This replaces the ~70 hardcoded model strings + 96 hand-written Pydantic duplicates + 54 nearly-identical CocoIndex Apps + 619 empty placeholder YAMLs that the 2026-08-15 audit found.

1. The 4 canonical artifacts

ArtifactPathPurpose
MODEL_REGISTRYmeaisinfhoghlaim/models/model_registry.py52 entries across 7 families (ocr_vision / text_llm / embedder / rerank / image_gen / voice / translation).
schema introspectionnotebooks/_shared/schema.py5 helpers: schema_introspect, schema_introspect_table, schema_introspect_full, list_dlt_sources, list_cocoindex_apps, list_baml_classes.
deployment-choice.yamlrepo rootThe canonical enablement file. Read/written by the marimo notebook + web UI + CLI.
00_control_panel notebooknotebooks/00_control_panel.pyThe 5-tab marimo control panel (Models / Pipelines / Datasets / Stacks / Registry).

2. MODEL_REGISTRY — the single source for models

The 7 families

FamilyCountExamples
ocr_vision20qwen3-vl-8b, molmo2-8b, gemma-4-26B-A4B, dots-ocr, unstract-api
text_llm13minimax-m3, qwen3.6-27b-mtp, uccix-mistral-24b, claude-sonnet-4-20250514
embedder3BAAI/bge-m3, BAAI/bge-large-en-v1.5, all-MiniLM-L6-v2
rerank3jina-reranker-v2-base-multilingual, rerank-v3.5, gte-rerank-v2
image_gen5local/image/flux2-dev, local/image/z-image-turbo, local/image/qwen-image, local/image/sdxl, local/image/fibo
voice5whisper-large, wav2vec2-irish, chatterbox, aba-tts, ResembleAI/chatterbox
translation3opus-mt, m2m100, nllb

The 2-axis key API

from meaisinfhoghlaim.models import (
    MODEL_REGISTRY,            # the registry object
    model_for,                 # resolve a single model key
    filter_models,             # filter by family (returns list[ModelRegistryEntry])
)

# Resolve a single model
default = model_for("text_llm", "default")              # → "minimax-m3"
irish  = model_for("text_llm", "irish", language="ga")  # → "uccix-mistral-24b"
embed  = model_for("embedder", "default")               # → "BAAI/bge-m3"
voice  = model_for("voice", "tts")                      # → "chatterbox"

# Filter by family
embedders = filter_models("embedder")  # → [3 ModelRegistryEntry entries]
for e in embedders:
    print(f"{e.key} ({e.upstream_id}) — {e.role}")

# Direct registry access
entry = MODEL_REGISTRY["minimax-m3"]
print(f"family={entry.family}, role={entry.role}, upstream={entry.upstream_id}")

Adding a new model

To add a new model to the registry, append a ModelRegistryEntry to the relevant family section in meaisinfhoghlaim/models/model_registry.py (one of the 7 _xxx_entries() functions):

def _text_llm_entries() -> dict[str, ModelRegistryEntry]:
    entries = {
        # ... existing entries ...
        "my-new-model-v1": ModelRegistryEntry(
            key="my-new-model-v1",
            family="text_llm",
            role="default",  # or any free-form role string
            display_name="My New Model v1",
            unsloth_id=None,  # or "unsloth/my-new-model-GGUF" if local
            mlx_id=None,
            upstream_id="myorg/my-new-model",  # canonical HF ID
            backend="hf",  # or "openai", "google", "anthropic", etc.
            available=True,
            litellm_alias="my-new-model-alias",  # None if not via LiteLLM
            env_var="MY_NEW_MODEL_API_KEY",
            notes="Used by the X agent (per the audit 2026-08-15).",
        ),
    }
    return entries

Then run mise run lint:registry to verify no drift was introduced.

Audit drift

mise run lint:registry            # reports 0 hardcoded model strings
mise run lint:registry --strict   # exits non-zero if drift detected

The lint walks agents/, baml_src/, notebooks/, web/, orchestration/, spaces/ and uses AST-aware regex against a tight family-prefix whitelist. New strings (not in the canonical MODEL_REGISTRY key set) trip the linter.

List all models

mise run models:list            # 52 entries grouped by family
mise run models:count           # just the counts (informational)

3. Schema introspection — discover the lakehouse

5 helpers in notebooks/_shared/schema.py:

from notebooks._shared.schema import (
    schema_introspect,               # every BIEP DuckDB table + column metadata
    schema_introspect_table,         # the canonical column metadata for any table
    schema_introspect_full,          # DuckDB + LanceDB + BAML union (control panel Tab 3)
    list_dlt_sources,                # all 920 @dlt.source + 4900 @dlt.resource functions
    list_cocoindex_apps,             # all CocoIndex Apps + their LanceDB mount targets
    list_baml_classes,               # all 838 BAML classes + their parent files
    read_deployment_choice,          # read deployment-choice.yaml (atomic + fcntl.flock)
    write_deployment_choice,         # write deployment-choice.yaml (atomic + fcntl.flock)
    deployment_choice_path,          # canonical path to deployment-choice.yaml
)

Usage

from notebooks._shared.db import connect_md
conn = connect_md()

# 1. Discover the lakehouse schema
rows = schema_introspect_full(conn)  # DuckDB + Lance + BAML
print(f"Found {len(rows)} columns across all tables")

# 2. Check what DLT sources are wired
sources = list_dlt_sources()
print(f"Found {len(sources)} DLT sources/resources")

# 3. Check what CocoIndex Apps are loaded
apps = list_cocoindex_apps()
print(f"Found {len(apps)} CocoIndex Apps")

# 4. Check what BAML classes are extracted
classes = list_baml_classes()
print(f"Found {len(classes)} BAML classes")

# 5. Read/write deployment-choice.yaml
state = read_deployment_choice()
state["enabled_models"]["my-new-model-v1"] = True
write_deployment_choice(state)

4. Deployment control panel

Open the 5-tab marimo notebook

mise run notebook:control-panel
# or: marimo edit notebooks/00_control_panel.py

The 5 tabs:

  1. Models — every MODEL_REGISTRY entry grouped by family. Toggle on/off.
  2. Pipelines — every DLT source + every CocoIndex App. Toggle on/off.
  3. Datasets — read-only view of every BIEP DuckDB table + LanceDB mount + BAML class (via schema_introspect_full).
  4. Stacks — every Docker Compose stack. Toggle on/off.
  5. Registry — full MODEL_REGISTRY view + drift count.

The deployment-choice.yaml file

The notebook reads/writes deployment-choice.yaml at the repo root:

version: 1

enabled_models:
  minimax-m3: true
  uccix-mistral-24b: true
  qwen3-vl-8b: true
  # ... 50+ entries ...

enabled_pipelines:
  ireland_jurisdiction_pipeline: true
  european_nations_embedding_factory: true
  # ... 28 entries ...

enabled_stacks:
  litellm: true
  langfuse: true
  # ... 8 high-priority stacks ...

monitoring:
  registry_audit: true
  baml_ts_codegen: true

The same file is read/written by the web UI control panel (deferred to issue #143) and the CLI (deferred to issue #146).

5. ADK agent construction (LiteLlm migration)

After the 2026-08-15 drift fix, every ADK agent routes through the LiteLLM gateway via the canonical litellm_model("minimax") helper:

from agents.adk.litellm_agent import make_litellm_agent, litellm_model

# Option A: Use the make_litellm_agent helper
agent = make_litellm_agent(
    name="my_agent",
    description="Routes through the Cianfhoghlaim minimax LiteLLM gateway.",
    model_alias="minimax",
    tools=[my_tool],
    instruction="...",
)

# Option B: Use litellm_model with LlmAgent directly
from google.adk.agents import LlmAgent
agent = LlmAgent(
    name="my_agent",
    model=litellm_model("minimax"),
    description="...",
)

The 32 hardcoded LlmAgent(model=config.model_name) sites that were bypassing the registry are now all routed through MODEL_REGISTRY.

6. Dagster JurisdictionAssetsBase

The base class for the 10 per-jurisdiction Dagster asset wrappers. Lives at orchestration/defs/2_materials/_base/jurisdiction_assets_base.py:

from orchestration.defs.2_materials._base.jurisdiction_assets_base import (
    JurisdictionAssetsBase,
    IrelandAssets,                # the reference implementation
    make_jurisdiction_assets,     # dynamic factory for one-line rollouts
    all_jurisdiction_assets,      # list of all 10 AssetsDefinition
)

Each per-jurisdiction file becomes a ~30-LOC subclass instead of the current ~378-LOC. Full rollout saves ~3,300 LOC across 10 files (issue #146).

7. CocoIndex factory pattern

The canonical example: cocoindex_flows/european_nations/_factory.py collapses 40 nation CocoIndex Apps into one factory. See cocoindex/AGENTS.md "The factory pattern" section.

7. CocoIndex factory pattern

The canonical example: cocoindex_flows/european_nations/_factory.py collapses 40 nation CocoIndex Apps into one factory. See cocoindex/AGENTS.md "The factory pattern" section.

Marimo v14 Helper Modules

The canonical shared notebook helpers are:

  • notebooks/_shared/marimo_patterns.py — reusable v14 dashboard patterns and CLI/interactive execution helpers.
  • notebooks/_shared/area_shims/biiep_v3_dashboard.py — BIEP v3 dashboard surface and area-specific shims.
  • notebooks/_shared/ragas_gauge.py — RAGAS evaluation gauge rendering.

Use LITELLM_BASE_URL for LLM routing in notebooks and helper modules; do not introduce hardcoded gateway URLs. The helpers support the 17 BIEP v3 dashboards, the 7 grouped dashboards, and the consolidated notebooks/sync_health.py sync-health dashboard.

8. The 3 openspec capabilities

SpecOne-liner
centralized-model-registryThe 4 canonical artifacts + the 4 Requirements (registry family coverage, no-hardcode-consumption, model_for() API, lint:registry audit).
centralized-schema-registryBAML is the source of truth + Pydantic + Zod are codegen + 96 Pydantic dupes removed + schema_introspect_full().
deployment-control-panelThe marimo notebook + web UI + CLI for picking models/pipelines/datasets/stacks.

9. Reference

  • openspec/changes/archive/2026-08-15-centralized-model-schema-registry-and-deployment-control-panel-v1/ (the archived change record)

Pre-commit hook

A pre-commit hook blocks commits that introduce hardcoded model strings:

mise run pre-commit-install  # install the hook
mise run pre-commit-run      # run on all files manually
git commit --no-verify       # skip (rare)

The hook runs mise run lint:registry (which invokes scripts/registry_audit.py) and fails the commit if any hardcoded model name/ID is found in agents/, baml_src/, notebooks/, web/, orchestration/, spaces/, or meaisinfhoghlaim/ that isn't routed through MODEL_REGISTRY.

  • openspec/specs/centralized-model-registry/spec.md (4 Requirements)
  • openspec/specs/centralized-schema-registry/spec.md (4 Requirements)
  • openspec/specs/deployment-control-panel/spec.md (5 Requirements)
  • meaisinfhoghlaim/models/model_registry.py:MODEL_REGISTRY
  • notebooks/_shared/schema.py (5 helpers)
  • notebooks/00_control_panel.py (the 5-tab notebook)
  • scripts/registry_audit.py (the drift detector)
  • agents/adk/litellm_agent.py (the LiteLlm helper)
  • orchestration/defs/2_materials/_base/jurisdiction_assets_base.py
  • cocoindex_flows/european_nations/_factory.py (the factory pattern)
  • deployment-choice.yaml (the canonical enablement file)

10. The 6 follow-up issues

#TitleWork
#141Complete remaining MODEL_REGISTRY migrations (Phase 1.3-1.10 + 1.12-1.19)15 remaining model hardcodes
#142Activate BAML TypeScript codegen (baml_client_ts/)TS codegen via Node @baml/cli
#143Build web UI control panel5 TanStack Start routes
#144Pydantic dedup rollout (7 remaining subjects)~1320 LOC reduction
#145CocoIndex factory rollout (Irish LC + BI parity)14 files → 2 factories
#146Dagster JurisdictionAssetsBase rollout~3300 LOC reduction

11. OCR/VLM Pipeline

The OCR/VLM surface lives under meaisinfhoghlaim/. This section is the canonical entrypoint for any agent adding, modifying, or evaluating vision models, OCR backends, PDF converters, alignment methods, or the BIEP v2 4-path ensemble.

11.1 The ocr_vision family in MODEL_REGISTRY

The ocr_vision family is a 22-entry subset view of MODEL_REGISTRY exposed via MODEL_REGISTRY.filter(family="ocr_vision"). Each entry groups by role into 4 tiers:

TierModels
tier1_heavy (≥ 27B params, full-document)qwen3-vl-30b-a3b, qwen3.6-27b-mtp
tier2_medium (8-12B params, page-level)gemma-4-12B, gemma-4-26B-A4B, glm-4.6v-flash, qwen3-vl-8b, internvl3-8b
tier3_light (≤ 4B params, fast inference)gemma-4-E2B, gemma-4-E4B, qwen3-vl-4b
specialist (single-purpose OCR/VLM)deepseek-ocr-2, olmocr-2-7b-1025, granite-docling-258M, uccix-mistral-24b, uccix-llama-3.1-8b, dots-ocr, paddleocr-vl-1.6, molmo2-4b, molmo2-8b, unstract-api, docling-serve
legacy (deprecated, kept for back-compat)uccix-llama2-13b, llama-3.2-vision-11b

Resolve via the canonical 2-axis key:

from meaisinfhoghlaim.models import MODEL_REGISTRY

# Pick the M4-Max optimal model
m4_max = MODEL_REGISTRY.resolve("ocr_vision", "tier1_heavy")
# → "qwen3-vl-30b-a3b"

# Pick by language
irish_specialist = MODEL_REGISTRY.filter(family="ocr_vision", role="specialist")
# → 11 entries (deepseek-ocr-2, olmocr-2-7b-1025, ...)

# List all available (non-legacy)
available = MODEL_REGISTRY.filter(family="ocr_vision", available=True)
# → 20 entries (excludes the 2 legacy entries)

11.2 The 6 CLASSICAL_OCR backends

The classical OCR registry (meaisinfhoghlaim/models/registry.py:CLASSICAL_OCR) holds 6 Docker-backed backends — each runs as a separate Compose stack at bonneagar/stacks/ocr-classical/<name>/:

KeyImagePortNotes
docling-servedocker.io/ds4sd/docling-serve:latest5001IBM Docling — 258M params, DocTags layout. The "safety net" when VLM extraction fails.
paddleocrdocker.io/paddlepaddle/paddleocr:latest8888PaddlePaddle OCR — multilingual, first-party GGUF.
paddleocr-vldocker.io/paddlepaddle/paddleocr-vl:latest8889PaddleOCR-VL — vision-language variant for diagrams.
tesseractdocker.io/tesseractshadow/tesseract4re:latest8880Tesseract 4 + LSTM. English/Irish/Latin scripts.
pylaiadocker.io/ocrhn/pylaia:latest8881PyLaia HTR — best for handwritten Irish manuscripts.
trocrdocker.io/microsoft/trocr:latest8882Microsoft TrOCR — transformer-based HTR for printed + handwritten.

All 6 are wrapped by meaisinfhoghlaim/backends/adapters.py:OCRAdapterRegistry (the 4th backend protocol) and are reachable via the select_ocr_backend() helper:

from meaisinfhoghlaim.models.registry import CLASSICAL_OCR, select_ocr_backend
backend = select_ocr_backend(task="handwritten_irish", quality="high")
# → "pylaia" (the optimal choice for handwritten Irish manuscripts)

11.3 The BIEP v2 4-path ensemble (EnsembledExtractor)

The flagship extraction pipeline. Located at meaisinfhoghlaim/ocr/ensemble/ensembled_extractor.py:EnsembledExtractor. Runs 4 OCR paths in parallel via asyncio.gather:

PathToolInputOutput format
1. BAMLDocling-serve → text → BAML functionPDFTyped Pydantic row
2. UnstractDocling-serve → Unstract workflow → JSONPDFStructured JSON
3. qwen3_vlqwen3-vl-8b page-level image → JSONPage imagesStructured JSON
4. gemma4gemma-4-26B-A4B page-level image → JSONPage imagesStructured JSON

Each path output lands in its own per-jurisdiction DuckLake table. The RAGAS biiep_extraction_consensus metric then votes the canonical row.

Webhook emission (post-2026-08-15): on every successful extraction, the canonical envelope is POSTed to os.getenv("OCR_WEBHOOK_URL", "") via httpx.AsyncClient (fire-and-forget). Schema (per british-isles-education-pipeline-v3 spec delta):

{
  "document_id": "<uuid>",
  "capability": "<forms|layout|tables+latex|doctags|gaelic|english>",
  "backend_used": "<paddleocr|mlx-omni|olmocr|docling-serve|llama-swap|dots-ocr>",
  "model": "<model name>",
  "result_url": "<s3://lakehouse/ocr/...>",
  "duration_ms": <int>,
  "trace_id": "<opentelemetry trace id>",
  "completed_at": "<iso-8601 utc>"
}

Invocation:

from meaisinfhoghlaim.ocr.ensemble.ensembled_extractor import EnsembledExtractor

extractor = EnsembledExtractor(
    document_id="<uuid>",
    pdf_path="leabharlann/ncca/lc_mathematics_2024.pdf",
    jurisdiction="ireland",
)
result = await extractor.extract()
# `result` is a RAGAS-voted Envelope with the canonical row

11.4 The 7 PDF converters (meaisinfhoghlaim/document_factory/)

Each converter transforms a PDF into markdown/dict/structured output. All live under meaisinfhoghlaim/document_factory/converters/:

ConverterModuleBest for
doclingdocling_converter.pyLayout-aware extraction (DocTags)
markermarker_converter.pyHigh-quality markdown + figure extraction
unstructuredunstructured_converter.pyPartitioning + element classification
deepseekocrdeepseekocr_converter.pyCompressed-document specialist (DeepSeek-OCR-2)
pymupdf4llmpymupdf4llm_converter.pyFast text extraction (PyMuPDF4LLM)
curriculum_document../curriculum_document.pyCurriculum document representation
pdf_factory../pdf_factory.pyOrchestrator — picks the right converter per document

The pdf_factory is the canonical entrypoint — it routes each PDF to the optimal converter based on document type, language, and quality requirements.

11.5 The 4 alignment methods + ColPaliAligner

meaisinfhoghlaim/alignment/aligner.py ships 4 methods for Irish-English cross-lingual alignment:

MethodBest forQuality
VecAlignLarge parallel corporaHigh (deep embedding)
HunAlignMedium corpora, sentence-levelMedium (HMM-based)
GaoisAlignIrish terminology alignmentHigh (Gaois-trained)
HybridProduction (VecAlign + HunAlign fallback)Highest

Plus the ColPaliAligner (colpali_aligner.py) for manuscript bbox extraction — uses ColPali vision embeddings to map extracted text back to manuscript page coordinates.

from meaisinfhoghlaim.alignment import aligner

a = aligner.IrishEnglishAligner(method="hybrid")
result = a.align_parallel_texts(
    irish=["Tá an lá go hálainn.", "Is maith liom an Ghaeilge."],
    english=["The day is beautiful.", "I like Irish."],
)
# → AlignmentResult with per-sentence confidence scores

11.6 The Irish HTR dataset

meaisinfhoghlaim/datasets/irish_htr_dataset.py (25KB) is the canonical training dataset for Irish handwriting recognition (HTR). Built from 3 sources:

  1. NLI manuscripts (National Library of Ireland) — scanned 18th-19th century Irish-language manuscripts
  2. RIA archives (Royal Irish Academy) — handwritten letters + diaries
  3. School copybooks — modern (20th century) school copybook scans

The dataset is the training source for the pylaia classical backend + the uccix-mistral-24b specialist VLM.

11.7 The M4-Max dispatch helper

meaisinfhoghlaim/models/registry.py:select_optimal_for_m4_max() returns the recommended OCR/VLM model for the M4 Max 64GB workstation:

from meaisinfhoghlaim.models.registry import select_optimal_for_m4_max

m4_max_model = select_optimal_for_m4_max()
# → "gemma-4-26B-A4B" (the M4-Max optimal choice)

# With a constraint
m4_max_irish = select_optimal_for_m4_max(task="irish_handwritten")
# → "uccix-mistral-24b" (the Irish HTR specialist)

11.8 llama-swap GGUF inference

The local inference path is configured by meaisinfhoghlaim/models/llama_swap_config.yaml (the llama-swap GGUF server config). It exposes all 22 VISION_MODELS entries as GGUF endpoints behind a single OpenAI-compatible API:

# llama_swap_config.yaml — relevant snippet
models:
  "qwen3-vl-8b":
    name: "Qwen3-VL-8B-Instruct"
    gguf: "unsloth/Qwen3-VL-8B-Instruct-GGUF"
    cmd: >-
      llama-server -m unsloth/Qwen3-VL-8B-Instruct-GGUF/qwen3-vl-8b-instruct-q4_k_m.gguf
      --port 8080 --host 0.0.0.0 -ngl 99

The docling-serve classical backend is the safety net — when llama-swap is unavailable, the adapter falls back automatically.

11.9 BAML clients_ocr_ensemble.baml patterns

baml_src/clients_ocr_ensemble.baml declares the 3 ensemble clients used by the BIEP v2 4-path pipeline:

ClientProviderUsed by
LocalVisionllama-swapPath 3 (qwen3_vl) + Path 4 (gemma4)
ExtractEnStrongBAML function (calls Path 1)Path 1 (BAML)
UnstractFlowUnstract APIPath 2 (Unstract)

Each client references MODEL_REGISTRY (no hardcoded model strings) and exposes a typed BAML function that the BIEP v2 pipeline consumes.

11.10 RAGAS-voted chunk emission

The EnsembledExtractor emits RAGAS-voted chunks after the 4-path consensus. The voting metric is biiep_extraction_consensus (registered in scripts/ragas_metrics.py). Each chunk carries:

  • chunk_id (UUID)
  • document_id (parent PDF)
  • path_votes (4 booleans — which paths agreed)
  • consensus_score (RAGAS score, 0-1)
  • text (the canonical chunk text)
  • bbox (page-level coordinates, from ColPali)

11.11 The meaisinfhoghlaim/ocr/ back-compat shim

The nested meaisinfhoghlaim/ocr/ sub-package exists for back-compat only. It re-exports VISION_MODELS + the ensemble with a DeprecationWarning:

# LEGACY — emits DeprecationWarning
from meaisinfhoghlaim.ocr.models.registry import VISION_MODELS

# CANONICAL — no warning
from meaisinfhoghlaim.models.registry import VISION_MODELS

The canonical home for all OCR/VLM models is meaisinfhoghlaim.models.registry (per the v4 platform convention: the outer models/ package is canonical). The meaisinfhoghlaim/ocr/ shim will be removed in v5 of the registry.

11.12 The image_generation_agent consumer (NEW 2026-08-13)

The image_generation_agent (registered in agents/agent_registry.py:AGENT_REGISTRY as the 13th main agent, per Phase L of the 2026-08-13-web-monorepo-consolidation-and-agent-integration-v1 change) consumes the 5 image_gen MODEL_REGISTRY entries for 2D asset generation + Babylon.js texture creation.

The agent's 5 tools live at agents/adk/tools/image_generation.py:

ToolPurposeRole
list_image_modelsList the 5 image_gen entries + availability(inspector)
generate_2d_assetGenerate a 2D image (subject illustration, sprite, diagram)default, fast, bilingual, legacy
generate_textureGenerate a Babylon.js PBR texturediagrams
style_matchGenerate N style-preserved variantsdefault
cocoindex_registerRegister the generated asset in the CocoIndex(always)

The BAML client wiring is at baml_src/clients_image_gen.baml with 5 client blocks (ImageGenDefault + ImageGenFast + ImageGenBilingual + ImageGenLegacy + ImageGenDiagrams). Each client routes via model_for('image_gen', role) — never hardcodes a model string.

The CocoIndex flow is at cocoindex_flows/media/image_generation_flow.py (R1–R4 conformance + the canonical bge-m3 embedder + LanceDB target table cianhoghlaim.media.image_gen_chunks).

11.13 Quick routing — "I want to add X, where do I go?"

If you want to...Look at...
Add a new OCR/VLM modelmeaisinfhoghlaim/models/registry.py:VISION_MODELS (or model_registry.py:MODEL_REGISTRY for the 7-family view)
Add a new classical OCR backendmeaisinfhoghlaim/models/registry.py:CLASSICAL_OCR + bonneagar/stacks/ocr-classical/<name>/
Add a new image_gen modelmeaisinfhoghlaim/models/model_registry.py:MODEL_REGISTRY (family=image_gen) + agents/adk/image_generation_agent.py
Add a new image_gen BAML clientbaml_src/clients_image_gen.baml + agents/adk/tools/image_generation.py
Run the image_gen agentagents/adk/image_generation_agent.py:image_generation_agent
Wire a model into BAMLbaml_src/clients_ocr_ensemble.baml (the 3 ensemble clients)
Run the 4-path ensemblemeaisinfhoghlaim/ocr/ensemble/ensembled_extractor.py:EnsembledExtractor
Add a new PDF convertermeaisinfhoghlaim/document_factory/converters/<name>_converter.py + register in pdf_factory.py
Add a new alignment methodmeaisinfhoghlaim/alignment/aligner.py:AlignmentMethod (StrEnum)
Evaluate a new OCR backendmeaisinfhoghlaim/evaluation/ (the OCR evaluation harness)
Train an Irish HTR modelmeaisinfhoghlaim/datasets/irish_htr_dataset.py (25KB training data)
Configure local inferencemeaisinfhoghlaim/models/llama_swap_config.yaml (the llama-swap config)
Pick the optimal M4-Max modelselect_optimal_for_m4_max() (the dispatch helper)

11.14 Cross-references

12. Firecrawl MCP — the external search surface (NEW 2026-08-14)

Per the 2026-08-14-firecrawl-mcp-ccc-dual-search-v1 change, Firecrawl MCP is the canonical external search surface (analogous to how ccc is the internal code search surface and Cognee is the internal docs search surface). The FirecrawlMCPClient wrapper at agents/meaisinfhoghlaim/firecrawl_mcp/client.py exposes all 12 MCP tools with Pydantic validation + Langfuse @observe. The agent routing table for ccc vs cognee vs firecrawl_search is documented at AGENTS.md §"Triple-search architecture" and the dual-search-architecture spec. The Firecrawl API key lives in Infisical under the firecrawl-api-key secret (per the .agents/skills/secrets-management/SKILL.md contract). The agent reference corpus (built by the Phase 4a change) federates firecrawl_search + Cognee + Graphiti + LanceDB over the docs_index table.


Last updated: 2026-08-13 (added §11.12 image_generation_agent consumer row + the 5 image_gen BAML clients + the CocoIndex flow + the 5 tools; updated the routing table with the image_gen entry). Owner: Build agent.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall