kaboum-sdk — the SDK and CLI

kaboum-sdk is a pip package plus a kaboum CLI wrapping the actor creation loop — render with Copier, validate the emitted config, build and push the image. It is for kreators who want typed base classes and a scripted verify/publish instead of raw copier + make.

Install

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

Requires Python 3.11+. The runtime install pulls in nothing else — JSON Schema validation has a dependency-free fallback (full Draft 2020-12 validation runs only when the optional jsonschema is importable).

The typed base classes

Optional sugar: a generated actor already contains real versions of these patterns in its own files. Reach for the SDK classes when writing tooling around actors, not inside them.

`DomainClient` — the domain client shape

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")

Construction takes the actor Settings and nothing else, and logs a kalendar_client_initialized event (the prefix derives from the class name). safe_call is the non-critical-service convention: a down service logs a warning and returns the fallback — degrade the actor, never crash it. DomainClientError carries a stable event name for log grepping; readiness_checks() reports system binaries as a {check_name: ready} dict (empty by default).

`KaboumTool` and `ToolRegistry` — tool conventions

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 dedupes by tool.name (first registration wins); a failing source logs tool_source_failed and contributes nothing. KaboumTool is standalone: it mirrors langchain_core.tools.BaseTool (name/description/args_schema/_run/_arun) without importing LangChain — generated actors still write real LangChain tools.

Config helpers — the `x-kaoohi-*` annotations

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() builds the json_schema_extra dict the config emitter reads: section, managed_by (platform/user), UI hints (widget, order, placeholder, options, step, show_if, display), validation rules, connector references. It rejects managed_by values outside platform/user and the fed_by_connector + creator_value combination (emitter rule F). merge_sections() appends actor-owned sections after the template’s, deduped by id; KaoohiConfigMixin mirrors the template’s actor-owned-sections convention.

The testing module

kaboum_sdk.testing ports the tests the template vendors into every actor into reusable factories:

# 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

Topic contract (v1.0) — every required endpoint (POST /agent/invoke, GET /health, GET /ready, GET /metrics) must be exposed; missing recommended ones are reported, not failed.
Pinned phrases — every rule the code enforces stays stated in the prompt; leftover {placeholder}s and identical role prompts also fail.
FORBIDDEN_VERBS — scans public callables and tool names for forbidden capabilities. The SDK default scans ("agent/tools",); pass your domain module first via scanned_dirs, as above, to match the template’s scope.

The CLI

Three verbs, one loop: new → validate → publish.

`kaboum new` — render an actor

Wraps copier copy. Default source is the kaboum GitHub repo (latest tag); --local /path/to/kaboum renders a local checkout at HEAD; --ref pins a git ref; --data KEY=VALUE passes extra copier answers through. The CLI never passes actor_id — identity is assigned by the platform at registration, never scaffolded — and refuses if you try.

$ 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` — check the emitted config

In a rendered actor: runs the vendored config emitter in emit-then-check mode (the make kaoohi-config convention), then validates src/kaoohi/config.json against the vendored kaoohi schema and tuning rules A–H. It uses the actor’s .venv/bin/python when present.

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

A broken actor fails (exit 1) with one bullet per problem — an emitter failure carries the venv hint, schema violations name the property:

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` — build, push, register

Docker build + tag + push using the actor’s [tool.kaoohi.deployment].image_repo (or --repo), tagged v<pyproject version> (or --tag), then prints the Creator Hub registration steps starting at https://app.kaoohi.com/home/creator/register-actor. Confirmation is required — a prompt in a tty, --yes to skip — and it refuses to run non-interactively without --yes. Nothing is ever deleted.

$ kaboum publish .

Honest boundary

For the underlying emitter/check loop that kaboum validate automates, see ](en/track-a/config-and-verify/).