Skip to content

ADR-043 — ADEN vector semantic catalog (Milvus collection catalog)

  • Status : Accepted
  • Date : 2026-04-28
  • Sprint : 58 (closed Sprint 60.4)
  • Drivers : founder expert reco — semantic recall@5 ADEN < 60 % sur schemas larges → bascule sur recherche vectorielle catalog-wide
  • Related : ADR-041 (ADEN scope-first), ADR-042 (RAG strategy), ADR-049 (Catalog Sync Daemon — alimente cette collection)

Context

ADEN traduit un prompt langage naturel → SQL Trino. Le pipeline historique itérait OPA.allowed? table par table (N appels) puis posait une heuristique fuzzy-match sur les noms de colonnes pour décider quelles tables charger dans le contexte LLM. Sur 100+ tables fédérées, le rappel chutait à ~55 % (banking + healthcare + retail demos).

Decision

Indexer chaque table autorisée dans une collection Milvus dédiée catalog :

  • Embedding model : nomic-embed-text-v2 via LiteLLM (768 dim, COSINE similarity, IVF_FLAT index).
  • Schéma record : { fqn, embedding, description, columns_summary, domain_tags, last_synced_at }.
  • Source d'enrichissement : vector_catalog.py côté ADEN + Catalog Sync Daemon (ADR-049) côté maintenance.
  • Requête : top-K=10 sur la projection des tables que l'utilisateur a le droit de lire (filtré par OPA scope-first ADR-041).

Consequences

  • + Recall@5 mesuré 60 % → 85 % sur les 16 questions de la marathon Sprint 58.
  • + Latence de retrieval ~120 ms p50 (Milvus en pod adjacent), reste imperceptible vs latence LLM.
  • − Une dépendance de plus à Milvus (déjà présent pour RAG ADR-042).
  • − L'embedding doit être rafraîchi quand le catalogue change — d'où ADR-049 Catalog Sync Daemon.

Implementation pointers

  • docker/aden/vector_catalog.py:1-271 — schéma + ingestion.
  • helm/akko/charts/akko-init/templates/aden-catalog-indexer-cronjob.yaml — refresh quotidien.
  • MEMORY.md → ADR-043 ADEN vector semantic catalog search (entry).