akko-catalog-sync — auto-enrichissement catalog + couche sémantique¶

akko-catalog-sync répond au problème du catalog froid : quand un opérateur ajoute un nouveau dataset, schéma ou catalog, OpenMetadata reste vide (aucune description, aucun tag, aucune FK), la collection Milvus utilisée par ADEN ne peut pas le retrouver via recherche sémantique, et le recall@5 du NL→SQL chute pour cette nouvelle source.

Le daemon parcourt l'inventaire des tables OM, échantillonne 5 % de chaque table via Trino TABLESAMPLE BERNOULLI, anonymise les lignes (masking Presidio), envoie un prompt RAG court à un LLM Ollama local (qwen2.5:3b via la passerelle LiteLLM), puis écrit le résultat dans OM + Milvus. Les samples ne sortent jamais du cluster.

Sprint 63 / ADR-049 — squelette livré, chemin MVP

La phase 63.1 (cette release) livre le squelette du service, le chemin OM PATCH et Milvus upsert, et un toggle off par défaut. Les phases 63.4–63.7 ajoutent la découverte des FK implicites, le minage du query log et une UI cockpit accept/reject. Voir ADR-049.

Architecture¶

flowchart LR
  subgraph Triggers
    CRON[CronJob 6h]
    HOOK[POST /sync<br/>webhook]
    CLI[Manuel --table=fqn]
  end
  subgraph Daemon["akko-catalog-sync (FastAPI)"]
    DISC[Discovery<br/>OM list + watermark]
    SAMP[Sampler<br/>Trino TABLESAMPLE 5%]
    ENR[Enrich<br/>Ollama qwen2.5:3b<br/>≤20 mots]
    PUB[Publish<br/>OM PATCH + Milvus upsert]
  end
  subgraph Backends
    OM[(OpenMetadata)]
    TR[(Trino)]
    LL[LiteLLM → Ollama]
    MV[(Milvus<br/>collection : catalog)]
  end
  CRON --> DISC
  HOOK --> DISC
  CLI --> DISC
  DISC --> SAMP --> ENR --> PUB
  DISC --> OM
  SAMP --> TR
  ENR --> LL
  PUB --> OM
  PUB --> MV

Garantie de souveraineté¶

La NetworkPolicy livrée par le chart n'autorise que :

kube-dns (UDP/TCP 53)
Egress same-namespace vers OpenMetadata (8585), Trino (8080), LiteLLM (4000), Milvus (19530), Postgres (5432)

Aucun egress public n'est permis. C'est le seul auto-enricher de catalog OSS basé LLM avec cette garantie — DataHub Cloud route les samples via AWS Bedrock, Atlan / Coalesce / Select Star / Secoda sont SaaS par design.

API¶

Endpoint	Méthode	Rôle
`/healthz`	GET	Probe liveness / readiness
`/metrics`	GET	Exposition Prometheus
`/status`	GET	Snapshot des feature flags + config
`/sync`	POST	Exécute un cycle discover → sample → enrich → publish

Body de POST /sync :

{
  "fqns": ["iceberg.banking.transactions"],
  "since_ms": 0,
  "dry_run": true,
  "limit": 50
}

Le défaut est dry_run=true (positionné dans les values du chart). L'UI cockpit "Sync staged changes" passe à false quand l'opérateur accepte un delta.

Configuration (zero hardcoding)¶

Chaque URL, modèle et toggle est lu depuis des env vars câblées par le sub-chart Helm. Aucun nom d'hôte, mot de passe ou ID de modèle n'est codé en dur dans le code Python. Les valeurs sont dans helm/akko/charts/akko-catalog-sync/values.yaml.

Flags clés (gated par global.features.catalogSyncEnabled) :

features.llmDescriptions — active/désactive le path LLM description
features.piiLlmVote — vote majoritaire Presidio + LLM pour le tagging PII
features.fkDiscovery — phase 63.4 fingerprint matching
features.queryMiner — phase 63.5 minage du query log VictoriaLogs
features.milvusPush — push de l'enrichissement vers la collection ADEN

Métriques¶

akko_catalog_sync_tables_processed_total{outcome="ok|dry_run|error|sample_failed"}
akko_catalog_sync_llm_latency_seconds (histogramme)
akko_catalog_sync_publish_failures_total{sink="openmetadata|milvus"}

Smoke test¶

Après activation du daemon (global.features.catalogSyncEnabled=true) et provisionnement du Secret OM bot-token :

kubectl -n akko run csync-curl --rm -it --image=curlimages/curl:8.10.1 -- \
  sh -c 'curl -sX POST -H "Content-Type: application/json" \
    -d "{\"limit\":3,\"dry_run\":true}" \
    http://akko-akko-catalog-sync:8000/sync | head -c 4000'

Le résultat attendu : un tableau JSON de 3 entrées, chacune avec une description ≤20 mots générée et om_updated:false (dry-run).