docs · v0.7.8 · build kit

Construisez avec kolm en 60 secondes

Chaque exemple de cette page est une réponse réelle capturée depuis kolm.ai le 2026-05-11. Copiez n'importe quel bloc et collez-le dans un terminal. S'il cesse de fonctionner, ouvrez un issue.

Les blocs de code, les commandes du CLI, les endpoints d'API, les noms de variables d'environnement et les clés JSON restent en anglais, car ils sont invariants d'une langue à l'autre.

Démarrage rapide

Créez un compte, récupérez une clé, compilez une fonction de redaction à partir de deux exemples, exécutez-la sur une entrée réelle. Six lignes.

$ curl -sX POST https://kolm.ai/v1/signup \
    -H 'content-type: application/json' \
    -d '{"email":"you@example.com","plan":"free"}'
$ export KOLM_KEY=ks_...                            # depuis la réponse ci-dessus
$ curl -sX POST https://kolm.ai/v1/synthesize \
    -H "authorization: Bearer $KOLM_KEY" -H 'content-type: application/json' \
    -d '{"name":"redact","positives":[{"input":"token=sk_live_xxx","expected":"[REDACTED]"}]}'
$ curl -sX POST https://kolm.ai/v1/run \
    -H "authorization: Bearer $KOLM_KEY" -H 'content-type: application/json' \
    -d '{"concept_id":"cpt_...","input":"my token=sk_live_abc123"}'

Quarante microsecondes, un HMAC, un reçu signé (signed receipt). C'est la boucle complète.

Authentification

Token Bearer dans l'en-tête authorization. À obtenir via POST /v1/signup ou /signup. L'offre gratuite inclut 10 000 appels par mois.

curl -H "authorization: Bearer ks_..." https://kolm.ai/v1/account

Installer le CLI

npm i -g github:sneaky-hippo/kolmogorov-stack
kolm login

Inscription (Sign up)

POST/v1/signupno auth

curl -X POST https://kolm.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","plan":"free"}'

À retenir : la clé d'API n'est affichée qu'une seule fois. Conservez-la. En cas de perte, faites-la tourner via POST /v1/account/rotate-key.

Synthesize (synthèse)

Transformez une liste de paires entrée/résultat attendu en une fonction JavaScript compilée qui classifie, redact (caviarde) ou transforme. Renvoie un concept_id et un score de qualité.

POST/v1/synthesizebearer

curl -X POST https://kolm.ai/v1/synthesize \
  -H "authorization: Bearer $KOLM_KEY" \
  -H 'content-type: application/json' \
  -d '{ "name":"redact-secrets", "positives":[ { "input":"token=sk_live_xxx", "expected":"[REDACTED]" } ] }'

Le seuil du K-score est de 0,85 par défaut. Une compilation sous le seuil renvoie accepted: false avec l'axe défaillant nommé. Recompilez avec davantage d'exemples ou ajustez le spec.

Run (exécution)

Exécute un concept compilé sur une nouvelle entrée. Renvoie la sortie et un reçu signé que toute personne disposant de la même clé peut revérifier.

POST/v1/runbearer

curl -X POST https://kolm.ai/v1/run \
  -H "authorization: Bearer $KOLM_KEY" \
  -H 'content-type: application/json' \
  -d '{ "concept_id":"cpt_mp11ol06a...", "input":"my token=sk_live_abc123" }'

Reçus (Receipts)

Livré aujourd'hui : chaque artefact .kolm porte une unique signature HMAC-SHA256 sur le contenu de l'archive (manifest + hashes des couches) ; chaque réponse de /v1/run renvoie un bloc de métadonnées _kolm avec source_hash · input_hash · output_hash · version_id · issued_at que l'émetteur, ou toute personne détenant le secret de reçu partagé du tenant, peut revérifier. Architecture cible : le chaînage HMAC inter-requêtes par appel et les reçus à clé publique Ed25519 figurent dans la feuille de route, mais ne sont pas encore livrés.

Format .kolm

Un zip signé contenant cinq fichiers : spec.json (la recette), policy.json (les gates), recall/ (sidecar facultatif), verifier.js (vérification peu coûteuse de la sortie) et receipt.json (la chaîne HMAC). Schéma complet sur /spec.

K-score

Par artefact, pas par modèle. Chaque .kolm compilé obtient son propre K-score à partir de son propre jeu d'évaluation ; ce score qualifie cet artefact, pas le modèle de base sous-jacent. Un scalaire unique, avec une gate à 0,85 pour pouvoir publier. Calculé comme 0,40·A + 0,15·(S + L + C + V), où A = accuracy (précision), S = specificity (spécificité), L = latency (latence), C = cost (coût), V = verifiability (vérifiabilité). Détail complet sur /k-score.

CLI

Huit verbes couvrent toute la boucle. Même authentification que l'API ; kolm login stocke la clé dans ~/.kolm/config.json.

kolm init              # scaffold kolm.yaml + examples/
kolm compile           # synthesize · signature · écrit .kolm
kolm run file.kolm     # exécute, émet le reçu
kolm tune --airgap     # entraîne un adapter LoRA à partir des runs capturés
kolm rag attach docs/  # construit le sidecar BM25
kolm serve --mcp       # serveur MCP local pour Claude Code / Cursor
kolm install claude-code   # branche un harness d'agent
kolm doctor            # vérifie env, clés, port, version

MCP serve

kolm serve --mcp expose vos artefacts locaux comme outils MCP via stdio (le mode par défaut de MCP). Le client le lance comme sous-processus ; kolm install <harness> --apply écrit la configuration de spawn au bon endroit pour claude-code / cursor / continue / cline. L'option --http ajoute un endpoint HTTP JSON-RPC facultatif sur 127.0.0.1:8765.

Accès distant

Le déploiement par défaut est local. kolm serve --local lie le runtime à votre machine ; votre ordinateur portable, votre téléphone ou votre agent de coding y accèdent via votre propre réseau. Vos prompts et vos sorties ne touchent jamais notre infrastructure, car il n'y en a pas à toucher.

Pour les équipes qui veulent un accès hébergé sans avoir à faire confiance à un fournisseur, faites tourner le même .kolm à l'intérieur d'un TEE (Trusted Execution Environment, environnement d'exécution de confiance). Les enclaves matérielles (AWS Nitro, GCP Confidential, Azure SEV) scellent le modèle, ses poids et les données de la requête, de sorte que ni kolm ni le fournisseur cloud ne peuvent les lire. Relativement sûr, relativement privé. Ce n'est pas une garantie cryptographique, mais c'est la formulation la plus honnête pour de l'inférence hébergée dans le cloud.

Compatibilité OpenAI

Le runtime expose /v1/chat/completions, /v1/models et /v1/embeddings sur localhost:8765. Pointez n'importe quel client compatible OpenAI vers cette adresse ; les tool calls et le streaming fonctionnent comme documenté. Chaque requête émet un reçu signé.

Compliance packs

Un compliance pack est un bundle versionné de (recipe.json + evidence.md + dpia.md + mrm.md + controls.md). Il encode la forme réglementaire d'une tâche : quelles redactions sont obligatoires, quels champs doivent être validés, ce que les auditeurs vont demander, pour que votre équipe d'ingénierie construise contre la même cible que celle validée par votre équipe juridique.

Trois packs sont livrés aujourd'hui, chacun sous data/compliance-packs/<pack>/ : HIPAA (redaction PHI, seuil K 0,92), SR 11-7 (Fed Model Risk Management) et SOX-lite (ITGC pour l'IA).

À propos de cette traduction

Cette version française couvre uniquement la synthèse ; les blocs de code, les commandes du CLI, les endpoints d'API, les formes JSON et les codes d'erreur restent en anglais car ils ne changent pas d'une langue à l'autre. Pour la référence complète, tous les tutoriels et les exemples les plus récents, consultez la documentation canonique en anglais : kolm.ai/docs.