🇬🇧 English version
Politique de données des exemples
Voir aussi : Exécuter votre premier exemple · Gabarit de README d'exemple · Conformité VFS · Retour à l'index
La plupart des exemples embarqués livrent leur définition de crew (config.yaml,
ou main.ork.ts pour un crew TypeScript) et leur code, mais pas les données d'entrée sur lesquelles ils travaillent. Cette
page explique pourquoi, et comment nourrir un exemple avec vos propres données.
La politique
- Les exemples livrent de la configuration, pas des jeux de données. Un exemple
est un crew que vous pouvez lire et exécuter — pas une distribution de données.
Quand la section d'exécution d'un README dit « this example does not ship sample
data yet », c'est exactement cela : aucun fichier d'entrée n'est commité
à côté du
config.yaml. - Les exemples vitrines qui ont besoin d'une fixture en portent une minuscule.
Une poignée d'exemples livrent un petit échantillon synthétique pour tourner sans
préparation. Ceux-là ont un tableau Required data (données requises) dans leur README et un
--mountdans leur commande d'exécution ; les deux catégories se distinguent à ce tableau. - Aucune donnée propriétaire, protégée par le droit d'auteur ou personnelle n'est jamais commitée dans le dépôt.
Pourquoi
- Taille du dépôt — des corpus réalistes (PDF, datasets, scrapes) alourdiraient le clone pour tous, alors que la plupart n'exécutent que quelques exemples.
- Licences — les documents et jeux de données tiers portent leurs propres conditions ; nous ne les redistribuons pas.
- Fraîcheur — beaucoup d'exemples travaillent sur des sources vivantes (actualités, prix, pages web). Un instantané commité aujourd'hui est périmé demain ; laisser le crew récupérer des données à jour est précisément l'intérêt.
- Reproductibilité — vous contrôlez exactement ce que voit le crew, ce qui rend les exécutions auditables et les résultats vôtres.
Comment un exemple obtient ses données
Selon le crew, l'une de ces trois choses est vraie :
Les outils récupèrent leurs propres données. Les crews bâtis autour de
web_scrape,http_api,web_searchou d'outils similaires tirent des données vivantes à l'exécution. Vous ne fournissez rien — juste un profil LLM et, généralement, un sujet via--varou--initial-context. Voir la référence des flags dans Exécuter votre premier exemple.Vous montez vos propres entrées. Les crews qui lisent des fichiers locaux (PDF, CSV, JSON, une base de code) attendent que vous exposiez un répertoire hôte dans le système de fichiers virtuel du crew :
orkeon run examples/<chemin>/config.yaml \ --settings examples/appsettings/appsettings.deepseek.local.json \ --mount ./data:/data:ro ./out:/output:rwLe
config.yamldu crew référence les entrées par leur chemin virtuel (p. ex./data/report.pdf), jamais par un chemin hôte.:ropour les entrées,:rwpour tout ce que le crew écrit.Une fixture d'exemple commitée. Pour les exemples vitrines, la fixture est déjà dans le dossier de l'exemple et la commande d'exécution la monte pour vous — rien à fournir.
OĂą va la sortie
Par convention, les crews écrivent leurs résultats sur le montage /output.
Mappez-le sur un répertoire local avec --mount ./out:/output:rw ; déclarer un
montage /output:rw active aussi l'écriture automatique du résumé d'exécution.
Ajouter des données d'exemple (contributeurs)
Si votre exemple a réellement besoin d'une fixture embarquée :
- Petite et synthétique. Quelques Ko de données écrites à la main ou générées, pas un extrait du monde réel.
- Propre côté licences. Aucun contenu protégé ou personnel. Si elle doit ressembler à des données réelles, générez-la.
- Placez-la dans le dossier de l'exemple et montez-la en lecture seule depuis la
commande d'exécution (
--mount ./data:/data:ro). - Documentez-la dans un tableau Required data (données requises) du README de l'exemple, en
suivant le gabarit de README d'exemple. Ce
tableau (plus un
--mountdans la commande) est ce qui sort l'exemple de la catégorie « does not ship sample data yet ».
Jeux de données des vitrines
Dix exemples vitrines — un par catégorie, deux dans 03-finance-trading/
(34-portfolio-consensus, 40-invoice-processing) — livrent un dossier data/ embarqué
pour tourner sur de vrais fichiers sans préparation. Leurs données sortent d'un
générateur unique :
python3 scripts/generate-vitrine-data.py # (re)génère chaque dossier data/ de vitrine
python3 scripts/generate-vitrine-data.py --check # ne vérifie aucun fichier : affiche un avis et sort avec 0
Les vitrines RAG (rag/*/data/) et les exemples de scripting (scripting/data/)
portent leurs propres petits corpus écrits à la main ; le générateur ne les gère pas.
Règles suivies par ces fixtures, en plus du « petite et synthétique » ci-dessus :
- Déterministes. Le générateur utilise une graine RNG fixe : le relancer reproduit les fichiers commités à l'octet près. Ne modifiez jamais un fichier généré à la main — modifiez le générateur et relancez-le.
- Synthétiques et petites. Données synthétiques uniquement (rien de réel, personnel ou propriétaire) et moins de 100 Ko par fichier, sauf nécessité justifiée dans le README.
- Aucune dépendance externe. CSV/JSON viennent de la stdlib Python ; les PDF
sont écrits par un mini-writer intégré (police Helvetica standard, texte
extractible par
pdf_reader). Le script tourne sur un Python 3.9+ nu. - Les tâches nomment les chemins virtuels. Les descriptions de tâches
(
config.yamloumain.ork.ts) référencent les chemins VFS concrets (p. ex./data/experiment-measurements.csv) pour que l'agent lise le fichier livré au lieu d'inventer un chemin que le VFS rejetterait.
Quels outils déclenchent l'exigence de données
Un outil ne déclenche l'exigence « livrer une fixture » que s'il lit un chemin
fourni par l'appelant à travers le VFS — csv_reader, pdf_reader, file_read,
directory_read, docx_reader et similaires. Les outils qui n'exigent pas par
eux-mêmes de fichier embarqué : json_tool (opère sur des chaînes JSON inline),
file_write (écrit seulement), http_api / web_scrape (ressources distantes) et
relational_database_query (chaîne de connexion fournie par l'appelant). Un exemple
bâti uniquement sur ceux-là n'a besoin d'aucune donnée montée ; voir
examples/09-experimental/97-multi-party-negotiation, qui ne monte rien et reçoit
son scénario via --initial-context — son data/procurement-brief.md est un brief
lisible Ă condenser dans ce flag, qu'aucun outil ne lit.
Vérifier une fixture
Utilisez le flag de dry-run du runner pour confirmer que le crew se charge sous résolution stricte des outils et que le montage de données est accepté, sans appeler de LLM :
orkeon run examples/<chemin>/config.yaml \
--mount examples/<chemin>/data:/data:ro --validate
Une ligne VALIDATION OK: … (agents=N, tasks=M, tools resolved=K) signifie le
succès.
Piège de syntaxe des montages. Les valeurs répétées de
--mountse passent séparées par des espaces sous un seul flag —--mount a:/data:ro b:/output:rw— et non comme deux flags--mountséparés (le parseur CLI rejette une option répétée).