Export et import OKF · Aiqbee Hive

Déplacez des Brains sous forme de bundles Markdown portables : ce qui est restitué à l'identique et ce qui est signalé.

OKF (Open Knowledge Format, version 0.2) est un format de connaissances en fichiers simples : une arborescence de fichiers markdown, chacun avec un petit en-tête YAML. Hive peut exporter n’importe quel brain sous forme de bundle .zip OKF et importer un bundle en tant que nouveau brain. Comme il ne s’agit que de markdown, un bundle est lisible dans n’importe quel éditeur, comparable dans git et compris par d’autres outils compatibles OKF.

Les propriétaires de brains peuvent exporter leurs propres brains (Paramètres → Exporter en OKF), et tout utilisateur connecté peut importer un bundle comme nouveau brain lui appartenant (Brains → Nouveau brain → Importer un bundle OKF). Les administrateurs peuvent exporter et importer n'importe quel brain depuis la page Brains de l'administration. L'export et l'import JSON (compatibles avec la plateforme SaaS Aiqbee) restent réservés aux administrateurs (Importer du JSON demande un propriétaire, comme l'import OKF). L'export OKF n'est pas proposé via MCP.

Export et import en libre-service

L'export est réservé au propriétaire du brain (copropriétaires inclus). Il contient chaque neurone que le propriétaire peut lire, y compris les neurones de types à sécurité avancée. Les brains de la bibliothèque ne peuvent être exportés par personne ; exportez plutôt le brain source (voir Place de marché & bibliothèque).
L'import crée un nouveau brain dont vous êtes propriétaire. Il compte dans la licence comme n'importe quel autre brain, et la limite de téléversement de 50 Mio s'applique. Deux imports au maximum peuvent s'exécuter en même temps sur la Hive et chaque utilisateur peut en avoir un en cours ; si l'import est signalé comme occupé, réessayez dans un instant.

Exporter un brain

En tant qu'administrateur, dans Admin → Brains, cliquez sur l'icône zip (Exporter en OKF (.zip)) dans la ligne d'un brain, ou ouvrez le brain et cliquez sur Exporter en OKF. Le fichier téléchargé s'appelle <brain-name>-okf.zip.

Le bundle contient un dossier de premier niveau contenant :

Chemin	Ce qu'il contient
`index.md`	Page de sommaire. Sa seule clé d’en-tête est `okf_version: "0.2"`.
`log.md`	Un journal daté : d’abord l’export lui-même, puis une ligne par date de création.
`<type>/index.md`	Un dossier par type de neurone — même un type sans neurone — listant ses neurones.
`<type>/<neuron>.md`	Un fichier par neurone : l'en-tête, votre contenu tel qu'il est stocké, et une liste Related de ses synapses sortantes.
`_aiqbee/brain.md`	Le manifeste du Brain : nom, description, indicateur de modification MCP, types de neurone et registre des champs de métadonnées.

Les noms de fichiers et de dossiers sont des versions en minuscules et en ASCII uniquement des noms de types et de neurones (un conflit reçoit -2, -3…). Ils ne servent qu’à la présentation : ce sont les identifiants contenus dans les fichiers, et non les noms de fichiers, qui pilotent un nouvel import.

Importer un bundle

Vous pouvez aussi initialiser un tout nouveau Brain à partir d'un bundle en une seule étape : Nouveau Brain, sur la même page, vous permet de choisir le propriétaire, de nommer le Brain et de joindre un export .json ou un .zip OKF facultatif. Le quota de Brains de la licence est vérifié d'abord, et vous êtes averti si des licences supplémentaires doivent être achetées.

En tant qu'administrateur, cliquez sur Importer un bundle OKF dans Admin → Brains et remplissez la boîte de dialogue (les utilisateurs qui importent pour eux-mêmes passent par Brains → Nouveau brain et n'ont pas de champ propriétaire) :

Bundle OKF (.zip) — le fichier à importer.
Nom du brain (facultatif) — par défaut, le nom figurant dans le manifeste du bundle, sinon le nom du fichier zip. Si le nom est déjà pris, Hive le rend unique.
Propriétaire (obligatoire) — l’utilisateur actif qui sera propriétaire du nouveau brain. La session d’administration n’est pas un utilisateur ; vous en choisissez donc un.

Un import crée toujours un nouveau brain. Il ne fusionne jamais avec un brain existant et ne le met jamais à jour. C’est tout ou rien : si une erreur fatale est détectée, rien n’est écrit et vous recevez un seul message en indiquant la raison. Les embeddings ne font pas partie du bundle ; Hive commence à les générer dès la fin de l’import, comme pour l’import JSON, de sorte que la recherche sémantique du nouveau brain peut être brièvement en retard avec un gros bundle.

Bundles issus d’autres outils

Un bundle OKF générique (sans clés Aiqbee) peut aussi être importé :

Chaque fichier .md devient un neurone. Son type de neurone provient de l’en-tête type, sinon du nom du dossier, sinon de Concept.
Le nom du neurone est le title, sinon le premier titre #, sinon le nom du fichier. Les titres en double sont autorisés.
Les liens Markdown entre fichiers deviennent des synapses ; le texte après un élément de liste * [Title](link) - description devient la description de la synapse. Les liens dans des blocs de code, vers des sites web, ou qui ne se résolvent pas ne sont pas des synapses (les liens non résolus sont signalés comme liens rompus).
index.md et log.md sont ignorés.

Ce qui est restitué à l'identique

Exporter un brain Aiqbee puis importer le bundle recrée exactement les éléments suivants :

Nom du brain (avant tout suffixe d’unicité), description et paramètre d’édition MCP.
Types de neurone — noms, descriptions, indicateur de type fichier, types vides et types aux noms en double.
Neurones — nom, contenu octet pour octet (y compris vide ou absent), date du contenu, métadonnées et date de création.
Synapses — direction, description, et liens en double ou vers soi-même.
Le registre des champs de métadonnées.

Volontairement non repris :

Contrôle d’accès — autorisations de brain, d’utilisateur, de groupe et de compte de service, accès par type de neurone, sécurité avancée et paramètres d’audit. Les utilisateurs et les groupes appartiennent à un seul Hive ; le nouveau brain reçoit les valeurs par défaut et le propriétaire choisi.
Identifiants de ligne (de nouveaux sont générés), compteurs de version et embeddings.
Pièces jointes. Hive ne stocke aucun blob de fichier ; seul le contenu texte est donc exporté, et tout fichier non markdown d’un bundle importé (images, HTML) est ignoré et listé.

Le rapport d'import et les avertissements

Un import réussi affiche une page de résultat avec un lien vers le nouveau brain, le nombre de types de neurones, de neurones, de synapses, de champs de métadonnées et de fichiers ignorés, ainsi que des avertissements regroupés. Les avertissements ne bloquent jamais l’import ; ils indiquent ce qui a été ajusté :

Groupe	Signification
Fichiers ignorés	Fichiers non importés : encodage de texte invalide, en-tête YAML illisible ou trop volumineux, ou en-tête qui n’est pas un bloc clé/valeur.
Valeurs de repli appliquées	Une valeur était invalide ou manquante et une valeur par défaut a été utilisée — un type repris du dossier, un nom tronqué à 255 caractères, une date illisible.
Liens rompus	Liens qui ne pointent vers aucun fichier du bundle. Les 20 premiers sont affichés, ainsi que le total.
Clés de frontmatter non mappées	Clés OKF standard telles que `tags`, `sources`, `status` et toute clé inconnue. Hive n'a pas encore de place pour elles ; elles sont donc ignorées et comptabilisées.
Métadonnées supprimées ou ajustées	Valeurs de métadonnées qui n'ont pas passé la validation de leur champ déclaré.
Fichiers non .md ignorés	Chaque entrée non markdown, avec sa taille déclarée. Elles ne sont jamais décompressées.

Limites et bundles rejetés

Ces vérifications s'exécutent avant toute écriture. Un bundle qui en enfreint une est rejeté d'emblée :

Téléversez jusqu'à 50 Mio ; au plus 25 000 entrées zip et 20 000 fichiers de concept ; chaque fichier .md d'au plus 8 Mio, et 256 Mio de Markdown au total. Le frontmatter est limité à 512 Kio par fichier et 32 Mio au total, et un bundle peut définir au plus 500 000 synapses.
Chemins qui sortent du bundle (../), chemins absolus, liens symboliques, entrées chiffrées, chemins trop longs ou trop profonds, et deux entrées dont les noms ne diffèrent que par la casse.
Fichiers qui ne sont pas des archives zip.
Un bundle sans concept à importer.

L'export applique les mêmes limites : un Brain trop volumineux pour être réimporté n'est pas exporté en OKF (vous en êtes informé et dirigé vers l'export JSON), de sorte qu'un bundle téléchargé peut toujours être réimporté. Chaque formulaire d'import ne peut être soumis qu'une fois ; recharger la page de résultat ne crée donc jamais un second Brain.

Rien n'est extrait sur le disque, et les en-têtes YAML sont analysés en toute sécurité (sans balises, ancres ni alias) : un bundle hostile ne peut donc ni exécuter de code ni écrire de fichiers.

L'import compte aussi dans votre licence : la limite de Brains et le plafond de neurones mutualisé sont vérifiés par rapport à la taille du bundle, et une licence expirée (mode lecture seule) refuse l'import. Le message indique la limite atteinte. Voir Licences & niveaux.

Métadonnées et licence

Déclarer un champ de métadonnées est une fonctionnalité payante (voir Métadonnées des neurones). Ce que fait un import dépend de la licence du Hive qui le reçoit :

Avec le droit Métadonnées — le registre de champs est créé et les métadonnées de chaque neurone sont validées par rapport à celui-ci.
Sans ce droit — le registre n’est pas créé, mais les valeurs de métadonnées des neurones sont tout de même stockées. Elles sont inertes (visibles, mais inutilisables comme filtres) tant que les champs ne sont pas déclarés, exactement comme après l’expiration d’une licence. Le rapport comporte un avertissement en ce sens.

Comme toujours, les métadonnées servent à étiqueter et ne constituent pas un contrôle d’accès. Elles suivent le bundle auprès de quiconque peut ouvrir le zip.