08 - Liens et graphe
Liens et graphe : comment OKF transforme des fichiers Markdown en carte de connaissance
Dans OKF, le graphe n'est pas une ontologie lourde. C'est une carte pragmatique construite à partir de liens Markdown, de citations, d'index et de fichiers que les humains comme les agents peuvent parcourir.
Pourquoi parler de graphe dans OKF ?
Un bundle OKF est d'abord un dossier de fichiers Markdown. Mais dès que ces fichiers se citent, se relient et pointent vers des sources, le dossier devient plus qu'une arborescence: il devient une carte de connaissance.
Cette carte aide les agents à naviguer. Une métrique peut pointer vers les tables qui la composent, une décision peut pointer vers les métriques qu'elle impacte, un playbook peut pointer vers les APIs qu'il appelle, et une source peut soutenir plusieurs affirmations.
Le graphe OKF reste volontairement simple. Les liens sont des liens Markdown standards. Il n'y a pas de langage de requête imposé, pas de modèle relationnel obligatoire, pas de typage centralisé des arêtes. Cette sobriété rend le format lisible, portable et facile à maintenir.
Le dossier donne l'ordre, les liens donnent le sens
L'arborescence indique où se trouvent les concepts: `metrics/`, `tables/`, `playbooks/`, `sources/`. Elle donne un rangement utile, mais elle ne suffit pas à expliquer les dépendances réelles entre les connaissances.
Les liens complètent cette structure. Ils montrent qu'une métrique dépend d'une table, qu'un playbook utilise une API, qu'une décision influence une règle de calcul ou qu'une affirmation doit être vérifiée dans une source.
Pour un lecteur humain, ces liens accélèrent la compréhension. Pour un agent, ils réduisent l'improvisation: au lieu de chercher au hasard dans tout le bundle, il suit les chemins explicites que l'équipe a laissés.
Liens absolus : la forme recommandée
La spec OKF recommande les liens absolus relatifs à la racine du bundle. Ils commencent par `/`, comme `/tables/orders.md` ou `/metrics/mrr.md`. Ce format reste stable quand un fichier est déplacé dans son sous-dossier.
Un lien absolu est particulièrement utile quand plusieurs zones du bundle pointent vers le même concept. Un playbook support, une métrique finance et une décision produit peuvent tous pointer vers la même table sans dépendre de leur emplacement local.
Exemple: `Voir [Orders](/tables/orders.md) pour le grain de commande.` Le chemin est clair pour un humain, facile à parser pour un agent, et exploitable par un visualizer.
Liens relatifs : utiles pour les fichiers voisins
Les liens relatifs restent possibles. Ils sont pratiques dans un même sous-dossier, par exemple `./customers.md` depuis `tables/orders.md`, ou `../sources/revenue-dashboard.md` depuis un concept situé plus bas dans l'arbre.
Ils demandent toutefois plus d'attention lors des déplacements de fichiers. Si un concept change de dossier, un lien relatif peut casser plus facilement qu'un lien absolu bundle-relative.
La règle simple pour une V1: utilisez les liens absolus par défaut, puis les liens relatifs uniquement quand ils rendent le fichier vraiment plus lisible localement.
La relation vit dans la phrase autour du lien
OKF ne demande pas de typer formellement chaque relation. Un lien de A vers B indique qu'il existe une relation, mais le sens précis est porté par la phrase autour du lien.
Par exemple, `MRR depends on [Orders](/tables/orders.md)` exprime une dépendance. `Refund playbook uses [Create Ticket API](/apis/create-ticket.md)` exprime un usage. `Pricing v2 replaces [Pricing v1](/decisions/pricing-v1.md)` exprime une évolution.
Cette approche est moins stricte qu'un modèle RDF ou qu'une ontologie métier, mais elle correspond bien au niveau de maturité d'OKF v0.1: assez structuré pour être consommé, assez souple pour rester facile à écrire.
Citations : relier une affirmation à une preuve
Les citations sont un autre type de lien, mais avec un rôle différent. Elles ne servent pas seulement à naviguer: elles servent à vérifier. Quand un concept affirme une définition, une règle ou une décision, la citation indique la source qui soutient cette affirmation.
La spec recommande de placer les citations en bas de document, dans une section `# Citations`, avec des liens numérotés. Ces liens peuvent pointer vers des URLs externes, des chemins internes ou des concepts `sources/` dans le bundle.
Pour un agent, les citations sont précieuses parce qu'elles permettent de répondre avec plus de prudence: il peut distinguer une information sourcée d'une note non vérifiée.
index.md : naviguer sans tout charger
`index.md` n'est pas un concept file classique. Son rôle est d'aider la navigation progressive: un humain ou un agent peut lire l'index d'un dossier, comprendre ce qui existe, puis ouvrir seulement les concepts utiles.
Cette logique évite de charger tout le bundle dans le contexte d'un agent. On commence par une carte locale, puis on suit les liens pertinents. C'est exactement ce dont les agents ont besoin pour travailler sur des corpus qui grossissent.
Un bon `index.md` liste les concepts, les sous-dossiers et de courtes descriptions. Il ne remplace pas les liens dans les concepts, mais il donne une première orientation.
Backlinks et visualizers : lire le graphe dans les deux sens
Un lien Markdown va dans un sens: A pointe vers B. Mais un visualizer peut aussi calculer les backlinks: quels concepts pointent vers B ? Cette lecture inverse est très utile pour comprendre l'importance d'une source, d'une table ou d'une décision.
Le visualizer du repo officiel OKF est un proof of concept de consommation: il rend un bundle sous forme de graphe, permet de sélectionner un concept, affiche son frontmatter, son body Markdown et les backlinks calculés.
C'est important pour la pédagogie: OKF n'est pas seulement un format d'écriture. C'est aussi un format qui rend possible plusieurs interfaces de lecture: documentation, recherche, graphe, assistant agentique ou audit humain.
Liens cassés : pourquoi OKF reste tolérant
La spec OKF demande aux consommateurs de tolérer les liens cassés. Un lien dont la cible n'existe pas encore ne rend pas le bundle invalide. Il peut simplement signaler une connaissance à écrire plus tard.
Cette tolérance est très importante dans un format jeune et partiellement généré par agents. Un bundle peut être utile même s'il n'est pas complet. Les outils doivent aider à repérer les trous, pas bloquer toute la lecture.
En pratique, il faut quand même surveiller ces liens. Un lien cassé durable peut indiquer une dette de documentation, un fichier déplacé ou une source supprimée. La bonne posture est: tolérer à la lecture, corriger à la maintenance.
Exemple concret : métrique, table, playbook et source
Voici un mini-graphe en Markdown. Il montre comment quelques fichiers suffisent à créer une carte exploitable: une métrique dépend d'une table et d'une décision, un playbook utilise une table et une API, et une source soutient les deux.
Le point important n'est pas la sophistication technique. Le point important est que chaque relation soit lisible dans une phrase. Un agent peut suivre ces chemins sans interpréter une base de graphe propriétaire.
# metrics/mrr.md
Monthly Recurring Revenue depends on [Orders](/tables/orders.md)
and follows the pricing rules described in [Pricing v2](/decisions/pricing-v2.md).
# playbooks/refund-request.md
Before approving a refund, check the latest customer order in
[Orders](/tables/orders.md), then create a ticket with
[Create Ticket API](/apis/create-ticket.md).
# tables/orders.md
The orders table is used by [MRR](/metrics/mrr.md) and is documented
from the [Revenue dashboard source](/sources/revenue-dashboard.md).
# sources/revenue-dashboard.md
This source supports the metric definition in [MRR](/metrics/mrr.md)
and the schema notes in [Orders](/tables/orders.md).`[Orders](/tables/orders.md)`
Référence stable depuis n'importe quel fichier du bundle.
`[Customers](./customers.md)`
Lien pratique entre fichiers voisins dans le même dossier.
`[1] [Dashboard](https://bi.example.com)`
Preuve externe ou interne qui soutient une affirmation.
`* [MRR](metrics/mrr.md) - définition revenue`
Navigation progressive sans ouvrir tout le bundle.
`Orders` est cité par `MRR` et `Refund playbook`
Lecture inverse produite par un visualizer ou un outil de recherche.
Erreurs fréquentes à éviter
La première erreur est de créer des liens sans phrase explicative. Un lien brut donne une destination, mais pas le sens de la relation. Ajoutez toujours quelques mots autour du lien: dépend de, utilise, remplace, prouve, cite, rejoint.
La deuxième erreur est de vouloir modéliser toutes les relations trop tôt. OKF v0.1 n'a pas besoin d'une ontologie complète pour être utile. Commencez par les liens qui réduisent vraiment l'ambiguïté dans les workflows.
La troisième erreur est d'oublier les citations. Un graphe sans preuves peut donner une impression de cohérence, mais rester fragile. Les sources rendent la carte plus fiable et plus facile à auditer.
Lire ensuite
Après les liens et le graphe, la suite logique est de comprendre les règles de conformité: ce qu'un bundle doit absolument respecter, et ce que les consommateurs OKF doivent volontairement tolérer.
Revenir au rôle du frontmatter, du body Markdown, des liens et citations.
Exemples de fichiersVoir des modèles concrets de concepts reliés.
ConformitéComprendre les règles minimales et la tolérance aux liens cassés.
OKF vs RAGVoir comment un graphe mieux structuré améliore la matière première du retrieval.
WorkflowMettre en place une maintenance régulière des liens et citations.
Premier bundleChoisir les premiers concepts à relier sans viser un graphe complet.
Sources officielles et lectures utiles
Source primaire: règles de cross-linking, citations, index files et conformité.
OKF README.mdPrésentation officielle du visualizer, des backlinks et de la lecture graph-shaped.
Knowledge Catalog repoRepo officiel avec reference agent, visualizer, samples et bundles.
Google Cloud - Introducing OKFAnnonce officielle pour comprendre pourquoi le contexte portable devient stratégique.
Cytoscape.jsLibrairie utilisée dans le visualizer officiel pour afficher le graphe côté navigateur.
Les points à retenir
Le graphe OKF est volontairement pragmatique: des fichiers Markdown deviennent une carte grâce aux liens, aux citations, aux index et aux backlinks calculés. Les liens absolus sont recommandés, les liens relatifs restent possibles, le sens de la relation vit dans la phrase, et les liens cassés doivent être tolérés à la lecture puis corrigés dans la maintenance.
