kaboum-sdk — le SDK et la CLI

kaboum-sdk est un paquet pip plus une CLI kaboum qui enveloppe la boucle de création d’acteurs — rendu avec Copier, validation de la configuration émise, build et push de l’image. Il s’adresse aux kreators qui veulent des classes de base typées et un verify/publish scripté au lieu du copier + make brut.

Installation

git clone https://github.com/allcare/kaboum-sdk.git
cd kaboum-sdk
pip install -e .            # runtime (zero dependencies)
pip install -e ".[dev]"     # + pytest and ruff for development

Exige Python 3.11+. L’installation runtime n’attire rien d’autre — la validation JSON Schema a un repli sans dépendance (la validation complète Draft 2020-12 ne tourne que lorsque le jsonschema optionnel est importable).

Les classes de base typées

Du sucre optionnel : un acteur généré contient déjà des versions réelles de ces motifs dans ses propres fichiers. Tournez-vous vers les classes du SDK pour écrire de l’outillage autour des acteurs, pas à l’intérieur.

`DomainClient` — la forme du client de domaine

from kaboum_sdk.domain import DomainClient

class KalendarClient(DomainClient):
    async def health_check(self) -> bool:           # replace the stub probe
        return await self.safe_call(self._ping, fallback=False)

    async def list_bookings(self, tenant_id: str):  # domain methods ride safe_call
        return await self.safe_call(self._get(f"/bookings/{tenant_id}"),
                                    fallback=[], action="list_bookings")

La construction prend les Settings de l’acteur et rien d’autre, et journalise un événement kalendar_client_initialized (le préfixe dérive du nom de la classe). safe_call est la convention des services non critiques : un service tombé journalise un avertissement et renvoie le fallback — dégrader l’acteur, jamais le faire planter. DomainClientError porte un nom d’event stable pour le grep dans les logs ; readiness_checks() rapporte les binaires système comme un dict {check_name: ready} (vide par défaut).

`KaboumTool` et `ToolRegistry` — les conventions d’outils

from kaboum_sdk.tools import KaboumTool, build_default_registry

class SampleBookingTool(KaboumTool):
    name = "sample_booking_tool"      # snake_case, namespaced by domain
    description = "Book a table."     # what the model sees and chooses from

    def _run(self, date: str) -> str:
        return f"booked {date}"

build_default_registry([SampleBookingTool()], []).build()
# logs: tool_registry_built total=1 {'domain': 1, 'mcp': 0}

ToolRegistry déduplique par tool.name (la première inscription gagne) ; une source qui échoue journalise tool_source_failed et ne contribue rien. KaboumTool est autonome : il reflète langchain_core.tools.BaseTool (name/description/args_schema/_run/_arun) sans importer LangChain — les acteurs générés écrivent toujours de vrais outils LangChain.

Les aides de config — les annotations `x-kaoohi-*`

from kaboum_sdk.config import kaoohi_field

domain_api_key: str | None = Field(
    default=None,
    description="Domain API key",
    json_schema_extra=kaoohi_field("domain", widget="password", order=200),
)

kaoohi_field() construit le dict json_schema_extra que lit l’émetteur de configuration : section, managed_by (platform/user), indices d’UI (widget, order, placeholder, options, step, show_if, display), règles de validation, références de connecteur. Il rejette les valeurs de managed_by hors de platform/user et la combinaison fed_by_connector + creator_value (règle F de l’émetteur). merge_sections() ajoute les sections possédées par l’acteur après celles du template, dédupliquées par id ; KaoohiConfigMixin reflète la convention de sections possédées par l’acteur du template.

Le module de test

kaboum_sdk.testing porte en fabriques réutilisables les tests que le template vendore dans chaque acteur :

# tests/test_sdk_contracts.py — inside a rendered actor
from pathlib import Path
from src.main import app
from kaboum_sdk.testing import (assert_no_forbidden_verbs,
                                assert_pinned_phrases, make_contract_tests)

globals().update(make_contract_tests(app.openapi))  # topic-contract suite

PINNED = {"no_promises": "Never promise a confirmed booking."}
FORBIDDEN_VERBS = ("delete", "drop", "refund")

def test_prompt_pins_its_rules(build_prompt):
    assert_pinned_phrases(build_prompt("team_member"), PINNED)

def test_capability_boundary():
    assert_no_forbidden_verbs(Path("src"), FORBIDDEN_VERBS,
                              scanned_dirs=("booking", "agent/tools"))  # domain first

Contrat de topic (v1.0) — chaque endpoint required (POST /agent/invoke, GET /health, GET /ready, GET /metrics) doit être exposé ; les recommended manquants sont rapportés, pas échoués.
Phrases épinglées — chaque règle que le code applique reste énoncée dans le prompt ; les {placeholder}s oubliés et les prompts de rôle identiques échouent aussi.
FORBIDDEN_VERBS — scanne les callables publics et les noms d’outils à la recherche de capacités interdites. Le défaut du SDK scanne ("agent/tools",) ; passez votre module de domaine en premier via scanned_dirs, comme ci-dessus, pour correspondre au périmètre du template.

La CLI

Trois verbes, une boucle : new → validate → publish.

`kaboum new` — rendre un acteur

Enveloppe copier copy. La source par défaut est le dépôt GitHub kaboum (dernier tag) ; --local /chemin/vers/kaboum rend un checkout local à HEAD ; --ref épingle un ref git ; --data KEY=VALUE passe des réponses copier supplémentaires. La CLI ne passe jamais actor_id — l’identité est attribuée par la plateforme à l’enregistrement, jamais scaffoldée — et refuse si vous essayez.

$ kaboum new kreatorsdk2 new-actor \
    --local /path/to/kaboum --data domain_module=demosdk --defaults
Rendering actor 'kreatorsdk2' from /path/to/kaboum
Actor rendered at /path/to/new-actor
Next: cd into it, then `kaboum validate`.

`kaboum validate` — vérifier la configuration émise

Dans un acteur rendu : exécute l’émetteur de configuration vendoré en mode emit-then-check (la convention make kaoohi-config), puis valide src/kaoohi/config.json contre le schéma kaoohi vendoré et les règles d’accord A–H. Il utilise le .venv/bin/python de l’acteur quand il est présent.

$ kaboum validate smoke-actor
config.json valid against the kaoohi schema + tuning rules: .../src/kaoohi/config.json
kaboum validate OK: .../smoke-actor

Un acteur cassé échoue (exit 1) avec une puce par problème — un échec d’émetteur porte l’indice venv, les violations de schéma nomment la propriété :

kaboum validate FAILED:
  - config emitter failed to run — is the actor installed in the interpreter used?
    Try: python -m venv .venv && .venv/bin/pip install -e ".[dev]"
  - config.json: <root>: 'deployment' is a required property

`kaboum publish` — construire, pousser, enregistrer

Docker build + tag + push via le [tool.kaoohi.deployment].image_repo de l’acteur (ou --repo), tagué v<version pyproject> (ou --tag), puis affiche les étapes d’enregistrement Creator Hub à partir de https://app.kaoohi.com/home/creator/register-actor. Une confirmation est requise — une invite dans un tty, --yes pour passer — et la commande refuse de tourner de façon non interactive sans --yes. Rien n’est jamais supprimé.

$ kaboum publish .

La frontière honnête

Pour la boucle émetteur/vérification sous-jacente que kaboum validate automatise, voir ](fr/track-a/config-and-verify/).