KAPE

Langage KAPE

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.

Ouvrir le studio KAPE Voir les docs API

Déclaratif

Un fichier .kap décrit l’état attendu et les relations voulues ; le serveur calcule ensuite les opérations nécessaires.

Plan avant mutation

Validate et Plan sont sans effet de bord. Apply doit être explicitement activé et audité.

Clés stables

Les clés d’asset et le namespace servent à rendre les imports reproductibles et idempotents.

Syntaxe minimale

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.

Blocs de haut niveau

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.

Valeurs

Chaîne : "texte" avec échappement standard.
Nombre : entier ou décimal.
Booléen : true ou false.
Liste : [ valeur, valeur ] avec virgules ou points-virgules optionnels.
Référence : ref("asset:key") pointe vers un asset du même module.
Source : url "https://…", upload "file-key" ou s3 "bucket/key".

Cycle runtime

Validate

Parse le fichier, verifie les champs requis, les enums, les refs et les invariants de modele. Aucune mutation.

Plan

Resout les data users cote serveur, calcule les create_or_update/link/action, l’ordre de creation et les permissions necessaires.

Apply

Recalcule le plan, exige confirmation, verifie les droits effectifs, execute en transaction et persiste le run.

Audit

Expose run id, auteur, statut, evenements progressifs, assets appliques, outputs, diagnostics et idempotencyKey.

Lecture DB avec data

data lit des donnees deja presentes en base, cote serveur. Le client fournit des criteres declaratifs, le serveur applique le scope, les droits et retourne seulement les champs non sensibles utiles au plan.

Categories. users, resources, projects, tasks et autres assets peuvent etre declares comme categories de lecture.

Assets. data resources, data projects et data tasks exigent un name clair. Le serveur cherche ce nom exact dans le scope autorise.

returnFormat. La sortie peut etre list, object, string, first ou ids selon le champ consommateur.

Callback. code(...) est execute a l’apply dans un sandbox serveur avec timeout, sans acces a require, process.env, filesystem ou reseau.

Data assets et callback

Un bloc data resources, data projects ou data tasks peut declarer des filtres, un scope et un callback code(...) pour transformer la sortie autorisee.

ref et refd

ref(...) injecte une valeur ou lit un attribut. refd(...) injecte le resultat complet d’un bloc data, souvent une liste.

Assets en profondeur

Chaque asset decrit une intention produit. Le serveur traduit cette intention vers le schema DB, ajoute l’auteur, applique l’idempotence et refuse les champs hors perimetre.

asset

organization

Tenant logique et point de gouvernance. Les projets appartiennent a une organisation, et les resolutions de donnees peuvent etre bornees a ce scope.

asset

project

Espace de travail gouverne. L’auteur est l’utilisateur qui applique par defaut, ou un utilisateur resolu explicitement via data users.

asset

dataset

Collection de ressources dans un projet. Le dataset porte le regroupement metier ; la ressource reste globale et est rattachee par action link.

asset

resource

Artefact global reutilisable : fichier brut, objet structure, ressource annotee ou definition versionnee. Les attributs exposent uniquement des informations non sensibles du schema.

asset

format

Entree de registre pour documenter un format supporte, son MIME, son parseur et ses capacites sans lier le DSL a un stockage particulier. En v1 runtime, cet asset est planifiable mais son apply reel reste a brancher sur un registre persistant.

asset

task

Unite de travail creee dans un projet. Elle peut cibler une ressource, un dataset, un assignee resolu et un payload metier.

asset

contractTemplate

Modele contractuel projet applique en base. Il formalise un titre, une version, une devise, un montant par defaut et les termes HTML reutilisables avant creation de contrats individuels.

asset

model

Gabarit reutilisable pour parametrer des actions comme createTasks : labels, contraintes, langues, QA ou regles de recording. En v1 runtime, cet asset est planifiable mais son apply reel reste a brancher.

Actions en profondeur

Une action represente une mutation ou un workflow. Elle apparait toujours dans le plan avant execution, avec l’ordre, l’impact, les champs concernes et les permissions requises.

action

link

Associe une ressource globale a un dataset. L’action est idempotente : la meme cle logique met a jour les champs portes par l’action au lieu de recreer un lien.

action

ingest

Planifie l’ingestion d’une ressource depuis ses sources. Le handler materialise ou versionne la ressource selon la configuration runtime.

action

generateItems

Transforme une ressource en items de travail a partir d’une strategie parse declarative.

action

createTasks

Cree ou met a jour une tache idempotente depuis une cle d’action. Le runtime exige les droits projet/taches, accepte une ressource directe ou la premiere ressource d’un dataset, et persiste le resultat dans le run.

action

transition

Declare une transformation controlee entre deux etats ou identites de ressource, par exemple RAW vers ANNOTATED.

action

platform

Pont vers un catalogue d’actions plateforme. Chaque operation doit etre activee, schematisee, autorisee et auditee cote serveur.

Inputs, outputs et chaining

Un fichier peut retourner plusieurs outputs apres apply. Ces valeurs peuvent ensuite etre injectees comme inputs d’un autre fichier. Les references restent resolues et controlees cote serveur.

Apply, idempotence et audit

Apply exige une confirmation, une verification des droits, une transaction et un run persistant. Le run id est le point d’entree audit pour suivre les evenements et les assets appliques.

Contrats API

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.

Assets supportés

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, 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

Actions supportées

Type	Champs requis	Champs disponibles
link	dataset, resource	dataset, resource
ingest	resource	resource
generateItems	resource	resource, structure
createTasks	project	project, dataset, resource, model, title, description, taskType, type, visibility, assignee, targetLanguage, dueAt, payload
transition	from, to	from, to
platform	operation	operation, payload

Enums

projectVisibility

PRIVATE | ORG | PUBLIC

resourceVisibility

PRIVATE | PUBLIC

taskVisibility

PUBLIC | PRIVATE

taskType

POS | RECORDING | NER | DEP | TRANSLATION | REVIEW

resourceIdentity

resourceType

RAW | STRUCTURED | ANNOTATED

resourceStructure

Workflow recommandé

Écrire ou importer un fichier .kap dans le studio KAPE.
Valider la syntaxe, les champs requis, les enums et les références.
Générer le plan pour inspecter les créations, mises à jour, liens et actions.
Appliquer uniquement après revue du plan, avec permissions et audit.

Bonnes pratiques

Utilisez un namespace par organisation, environnement ou flux métier.
Gardez des clés lisibles et stables, par exemple project:demo ou resource:corpus.
Traitez le plan comme un diff d’infrastructure : relisez chaque asset et son impact avant Apply.
Donnez séparément les permissions validate, format, plan, apply et settings selon le rôle.