Déclaratif
Un fichier .kap décrit l’état attendu et les relations voulues ; le serveur calcule ensuite les opérations nécessaires.
NATPKAPE
KAPE est un langage déclaratif pour décrire des assets plateforme, relier des ressources à des datasets et préparer des actions sans mutation directe avant validation et planification.
Un fichier .kap décrit l’état attendu et les relations voulues ; le serveur calcule ensuite les opérations nécessaires.
Validate et Plan sont sans effet de bord. Apply doit être explicitement activé et audité.
Les clés d’asset et le namespace servent à rendre les imports reproductibles et idempotents.
Un module commence par un bloc kape, puis contient des blocs input, asset, action, data ou output. Les chaînes sont entre guillemets, les références utilisent ref("key") et les sources utilisent url, upload ou s3.
kape déclare la version du langage et le namespace.input importe des valeurs produites par un autre apply KAPE ou fournies explicitement à l’API.asset décrit une entité persistante : organisation, projet, ressource, dataset, tâche, format, modèle ou contrat.action décrit une opération planifiable : lien dataset/ressource, ingestion, génération d’items, création de tâches, transition ou action plateforme.data porte des données auxiliaires référençables par les actions futures.output déclare les valeurs retournées après apply et réutilisables comme entrées d’un autre fichier.Parse le fichier, vérifie les champs requis, les enums, les refs et les invariants de modèle. Aucune mutation.
Résout les data users côté serveur, calcule les create_or_update/link/action, l’ordre de création et les permissions nécessaires.
Recalcule le plan, exige confirmation, vérifie les droits effectifs, exécute en transaction et persiste le run. En v1, link, createTasks et generateItems sont exécutés ; ingest, transition et platform sont refusés avec UNSUPPORTED_APPLY_ACTION.
Expose run id, auteur, statut, événements progressifs, assets appliqués, outputs, diagnostics et idempotencyKey.
data lit des données déjà présentes en base, côté serveur. Le client fournit des critères déclaratifs, le serveur applique le scope, les droits et retourne seulement les champs non sensibles utiles au plan.
Catégories. users, resources, projects, tasks et autres assets peuvent être déclarés comme catégories de lecture.
Assets. data resources, data projects et data tasks exigent un name clair. Le serveur cherche ce nom exact dans le scope autorisé.
returnFormat. La sortie peut être list, object, string, first ou ids selon le champ consommateur.
Callback. code(...) est exécuté à l’apply dans un sandbox serveur avec timeout, sans accès à require, process.env, filesystem ou réseau.
Un bloc data resources, data projects ou data tasks peut déclarer des filtres, un scope et un callback code(...) pour transformer la sortie autorisée.
ref(...) injecte une valeur ou lit un attribut. refd(...) injecte le résultat complet d’un bloc data, souvent une liste.
Chaque asset décrit une intention produit. Le serveur traduit cette intention vers le schéma DB, ajoute l’auteur, applique l’idempotence et refuse les champs hors périmètre.
Tenant logique et point de gouvernance. Les projets appartiennent à une organisation, et les résolutions de données peuvent être bornées à ce scope.
Espace de travail gouverné. L’auteur est l’utilisateur qui applique par défaut, ou un utilisateur résolu explicitement via data users.
Collection de ressources dans un projet. Le dataset porte le regroupement métier ; la ressource reste globale et est rattachée par action link.
Artefact global réutilisable : fichier brut, objet structuré, ressource annotée ou définition versionnée. identity est persisté dans resource.metadata.kape.identity ; rights pilote les contributeurs, reviewers, admins ressource et contributions via projets liés.
Entrée de registre pour documenter un format supporté, son MIME, son parseur et ses capacités sans lier le DSL à un stockage particulier. En v1 runtime, cet asset est planifiable mais son apply réel reste à brancher sur un registre persistant.
Unité de travail créée dans un projet. Elle peut cibler une ressource, un dataset, un assigné résolu et un payload métier.
Modèle contractuel projet appliqué en base. Il formalise un titre, une version, une devise, un montant par défaut et les termes HTML réutilisables avant création de contrats individuels.
Gabarit réutilisable pour paramétrer des actions comme createTasks : labels, contraintes, langues, QA ou règles de recording. En v1 runtime, cet asset est planifiable mais son apply réel reste à brancher.
Une action représente une mutation ou un workflow. Elle apparaît toujours dans le plan avant exécution, avec l’ordre, l’impact, les champs concernés et les permissions requises.
Associe une ressource globale à un dataset. L’action est idempotente : la même clé logique met à jour les champs portés par l’action au lieu de recréer un lien.
Planifie l’ingestion d’une ressource depuis ses sources. En v1, l’action est déclarable et planifiable, mais refusée à l’apply avec UNSUPPORTED_APPLY_ACTION tant que le handler métier n’est pas finalisé.
Transforme réellement une ressource texte en ResourceItem. Le runtime lit contentUri/uri, utilise secureExternalFetch pour les URL, écrit par batch et conserve metadata.itemsConfig.
Crée ou met à jour une tâche idempotente depuis une clé d’action. Le runtime exige les droits projet/tâches, accepte une ressource directe ou la première ressource d’un dataset, et persiste le résultat dans le run.
Déclare une transformation contrôlée entre deux états ou identités de ressource, par exemple RAW vers ANNOTATED. En v1, l’action est planifiable mais refusée à l’apply jusqu’au moteur OCR/ASR/PARSE.
Pont vers un catalogue d’actions plateforme. En v1, l’action est planifiable mais refusée à l’apply tant que le catalogue et les handlers ne sont pas activés.
Un fichier peut retourner plusieurs outputs après apply. Ces valeurs peuvent ensuite être injectées comme inputs d’un autre fichier. Les références restent résolues et contrôlées côté serveur.
Apply exige une confirmation, une vérification des droits, une transaction et un run persistant. Le run id est le point d’entrée audit pour suivre les événements et les assets appliqués.
Les clients doivent traiter diagnostics, operations, creationOrder, resolvedData, outputs et le runId comme le contrat stable de KAPE v1. Les erreurs métier retournent un JSON exploitable ; les erreurs d’auth restent en HTTP 401/403.
| Type | Champs requis | Champs disponibles |
|---|---|---|
| organization | name | name, externalKey |
| project | org, name | org, author, name, description, visibility, defaultLanguage, defaultCurrency, defaults, budget, consentDocUrl, security, externalKey |
| dataset | project, name | project, name, description, properties, externalKey |
| resource | name, identity, visibility | name, author, description, identity, type, structure, visibility, language, sources, uri, contentUri, mime, format, annotationType, editable, rights, licenseId, rightsAttribution, gdprLawfulBasis, containsPII, consentDocUrl, rightsRestrictions, metadata, externalKey |
| format | name | name, mime, parser, externalKey |
| task | project, title, type | project, dataset, title, type, visibility, instructions, description, resource, resourceVersion, assignee, targetLanguage, dueAt, payload, externalKey |
| contractTemplate | project, title, termsHtml | project, version, title, termsHtml, currency, defaultAmountCents, externalKey |
| model | kind, payload | kind, payload, externalKey |
| Type | Champs requis | Champs disponibles |
|---|---|---|
| link | dataset, resource | dataset, resource |
| ingest | resource | resource |
| generateItems | resource | resource, structure, strategy, delimiter, clear, chunkSize, aiMetadata |
| createTasks | project | project, dataset, resource, model, title, description, taskType, type, visibility, assignee, targetLanguage, dueAt, payload |
| transition | from, to | from, to |
| platform | operation | operation, payload |
PRIVATE | ORG | PUBLIC
PRIVATE | PUBLIC
PUBLIC | PRIVATE
POS | RECORDING | NER | DEP | TRANSLATION | REVIEW
RAW_FILES | RAW_FILE | ANNOTATED_FILES | RAW_OBJECT | RAW_OBJECTS | ANNOTATED_OBJECTS
RAW | STRUCTURED | ANNOTATED
OBJECT | LINE | WORD | SENTENCE | PARAGRAPH | DOCUMENT | BLOCK