Outils OKF : spec, repo officiel, samples, reference agent et visualizer

Pourquoi commencer par les sources officielles ?

OKF est encore jeune. Pour éviter de le transformer en buzzword, il faut commencer par les sources primaires: l'annonce Google Cloud, la spec `SPEC.md`, le README du dossier `okf/` et les bundles d'exemple dans le repo officiel.

Ces sources permettent de séparer trois niveaux: le format lui-même, les outils de démonstration et les produits Google Cloud qui s'appuient sur la même logique de contexte agent-ready.

Cette distinction est importante: vous pouvez créer un bundle OKF sans utiliser le reference agent, sans visualizer, et sans être client d'un produit managé. Les outils aident, mais le format reste le coeur du sujet.

La spec OKF : le contrat minimal du format

La spec est le document à lire pour comprendre ce qui rend un bundle conforme: des fichiers Markdown, du frontmatter YAML parseable, un champ `type` présent et non vide, des liens Markdown, des citations et une logique de bundle.

Elle est volontairement minimale. Elle ne vous impose pas une taxonomie complète, un schéma métier universel ou une plateforme d'exécution. Cette sobriété est ce qui permet au format d'être portable.

Dans un projet réel, la spec sert de garde-fou. Elle vous dit ce qu'un consommateur OKF doit pouvoir lire, mais elle laisse votre équipe décider des types métier, des dossiers, des champs additionnels et du niveau de détail.

Le README OKF : comprendre l'esprit du repo

Le README du dossier OKF est utile parce qu'il explique l'intention du repo: OKF est un format universel, vendor-neutral, basé sur Markdown et YAML, que plusieurs producteurs et consommateurs peuvent utiliser.

Il rappelle aussi que le reference agent et le visualizer sont des preuves de concept. Ils rendent le format tangible côté production et consommation, mais ils ne sont pas le produit principal.

C'est le bon document pour comprendre la philosophie: plain files, Git, portabilité, lecture humaine, lecture agent, graph-shaped knowledge et progressive disclosure via les index.

Le repo Knowledge Catalog : le point d'entrée technique

Le repo `GoogleCloudPlatform/knowledge-catalog` contient le dossier `okf/`, la spec, le README, les samples, les bundles produits, les tests et le code du reference agent.

Pour un builder, c'est l'endroit où observer la structure réelle d'un projet OKF: dossiers, bundles, commandes, exemples de visualisation, logique de génération et conventions utilisées dans les samples.

Il faut toutefois éviter de copier le repo comme une architecture obligatoire. Le repo montre une implémentation de référence et des exemples; votre bundle peut rester beaucoup plus simple.

Les bundles d'exemple : voir OKF en pratique

Les bundles d'exemple sont précieux parce qu'ils montrent OKF dans des dossiers réels. Le README officiel met en avant des bundles GA4, Stack Overflow et Bitcoin, chacun accompagné d'un visualizer.

Ces exemples montrent comment des concepts peuvent représenter des datasets, tables, références et relations. Ils permettent aussi de voir comment les liens internes deviennent un graphe navigable.

Le bon réflexe n'est pas de reproduire leur structure à l'identique. Il faut plutôt repérer les patterns: un concept par notion, des liens explicites, des références, des index et une sortie visualisable.

Le reference agent : produire un bundle automatiquement

Le reference agent est une démonstration d'un producteur OKF. Il peut enrichir un bundle à partir de sources comme BigQuery et de pages web de référence, puis écrire des concept files.

C'est utile pour comprendre comment automatiser une partie de la production: extraire des métadonnées, générer des fichiers Markdown, ajouter des descriptions, suivre des seed URLs et produire un bundle parcourable.

Mais il ne faut pas le voir comme le seul chemin. Un bundle peut être écrit à la main, généré par un script, produit par un autre agent, exporté depuis un catalogue ou construit progressivement par une équipe.

Le visualizer : explorer le graphe d'un bundle

Le visualizer officiel est une preuve de concept de consommation. Il prend un bundle OKF et génère un fichier HTML autonome qui affiche le graphe, les concepts, le frontmatter, le Markdown rendu et les backlinks.

Pédagogiquement, c'est un excellent outil: il montre immédiatement si votre bundle est lisible, s'il contient des liens utiles, si les concepts sont isolés ou si une vraie carte de connaissance commence à apparaître.

Il ne faut pas en déduire que tout usage OKF doit passer par une interface graphe. Un agent, un moteur de recherche, un script, un site de documentation ou un outil interne peuvent aussi consommer les mêmes fichiers.

Google Cloud Knowledge Catalog : produit managé ou format ouvert ?

Google Cloud Knowledge Catalog est un produit managé orienté contexte, gouvernance et discovery pour agents. Il s'inscrit dans le même paysage: rendre les données, métadonnées et connaissances plus exploitables par des systèmes IA.

OKF, lui, doit être compris comme un format ouvert. Il peut être utilisé sans déployer Knowledge Catalog, et il peut aussi servir de couche d'échange ou d'export autour de systèmes existants.

La nuance est importante pour la page: Knowledge Catalog montre la direction produit côté Google Cloud, tandis qu'OKF donne une convention portable que des équipes peuvent commencer à tester plus simplement.

Comment utiliser ces outils dans un premier projet

Pour démarrer, la séquence la plus saine est simple: lire la spec, ouvrir le README, parcourir un bundle d'exemple, regarder le visualizer, puis créer un petit bundle sur votre propre cas d'usage.

Par exemple, une équipe data peut partir du sample GA4 pour comprendre comment documenter datasets et tables, puis créer son propre bundle `revenue-analytics`. Une équipe support peut ignorer BigQuery et produire manuellement un bundle de policies, FAQ et playbooks.

Le but de cette exploration n'est pas de devenir expert du repo. C'est de comprendre les patterns minimums avant de construire une V1 utile.

Ce qu'il ne faut pas surinterpréter

Première prudence: le reference agent n'est pas une obligation. Il démontre une manière de produire des bundles, mais il ne définit pas la seule bonne méthode.

Deuxième prudence: les samples ne couvrent pas tous les cas métiers. Ils sont très utiles pour comprendre les assets data, mais un bundle support, marketing ou produit aura une structure différente.

Troisième prudence: le visualizer n'est pas la finalité. Il aide à voir le graphe, mais la valeur vient du fait que le contexte devienne portable, vérifiable et consommable par plusieurs outils.

Première exploration des outils

Cette checklist donne un parcours simple pour éviter de se perdre dans le repo et revenir vite à votre objectif: produire un premier bundle utile.

Lire ensuite

Après les outils officiels, vous pouvez revenir à la définition, vérifier les règles de conformité, regarder les exemples de fichiers ou créer votre premier bundle.

Sources officielles et lectures utiles