Track A — Installation et génération

kaboum est un template Copier qui génère des acteurs Kaoohi — des microservices FastAPI + LangChain avec les conversations dans PostgreSQL, le cache d’auth dans Redis, le double support LLM et une configuration prête pour le marketplace. Vous répondez une fois à un questionnaire ; le template rend un dépôt complet et exécutable. Cette page couvre les prérequis, le rendu lui-même, et les réponses qui façonnent tout ce qui suit.

Prérequis

Outil	Minimum	Pourquoi vous en avez besoin
Copier	9.4.0	Moteur de template. Épinglé par le _min_copier_version du template — 9.0.0 était revendiqué dans les anciennes docs mais n’a jamais été exercé et ne s’installe pas sur Python 3.12.
Python	3.11 / 3.12 / 3.13	Runtime de l’acteur généré (3.12 est le défaut du template)
Docker	20.10+	Builds de conteneurs et PostgreSQL/Redis locaux
PostgreSQL	14+	Conversations, messages, stats — le seul service critique
Redis	6+	Cache d’auth et file de réponse optionnelle
git	2.30+	Copier clone le template depuis un ref git

Installez Copier isolé de tout environnement de projet :

pipx install copier
# or: pip install copier
# or: uv tool install copier

Générez votre acteur

Interactif (recommandé la première fois)

copier copy https://github.com/allcare/kaboum /path/to/my-actor

Copier demande chaque variable avec son texte d’aide et son défaut. Deux réponses seulement n’ont pas de défaut :

• project_name — minuscules, ^[a-z][a-z0-9_]{1,30}$. Nomme vos tables de base ({project_name}_conversations, …), votre image Docker et vos événements de log.
• domain_module — le paquet Python de votre code de domaine (p. ex. booking, email). Les noms réservés sont rejetés : mesh, agent, api, core, kaoohi, shared, integrations, middleware, models, storage — ils entrent en collision avec les modules possédés par le template.

Tout le reste a un défaut sensé ; appuyer sur Entrée jusqu’en bas produit un acteur valide.

Non interactif (scripts, CI)

copier copy https://github.com/allcare/kaboum /path/to/my-actor \
  --vcs-ref v1.2.0 \
  --data project_name=katask \
  --data domain_module=task \
  --data actor_description="AI Task Manager" \
  --defaults \
  --trust

• --data key=value définit une variable ; répétez pour chacune.
• --defaults accepte les défauts pour tout ce que vous n’avez pas passé.
• --trust saute la confirmation de sécurité de template de Copier.

Si le répertoire cible existe déjà, Copier refuse, sauf si vous ajoutez --overwrite — préférez régénérer dans un chemin neuf.

Rendez toujours depuis un ref git

Passez l’URL du dépôt (comme ci-dessus) ou un tag via --vcs-ref, jamais un checkout local mouvant. Copier enregistre le commit du template utilisé dans le .copier-answers.yml généré, sous _commit. Rendu depuis un simple chemin de système de fichiers, ce champ vaut null, votre acteur oublie quel kaboum l’a produit, et copier update n’a plus rien contre quoi faire son diff. Épinglez un tag publié (--vcs-ref v1.2.0) pour des rendus reproductibles ; n’utilisez HEAD que lorsque vous testez délibérément des changements de template non publiés.

Les réponses qui comptent

Référence complète des variables : ](fr/reference/copier-variables/). La visite ci-dessous les regroupe comme le fait copier.yml.

Identité et nommage

project_name et domain_module (ci-dessus), plus des noms dérivés que vous surchargez rarement : actor_display_name, domain_display_name, config_class_name (<DisplayName>Config), agent_class_name (<DisplayName>Agent>), actor_description, et python_version (3.11/3.12/3.13, défaut 3.12).

Framework d’agent et intelligence

agent_framework choisit la base d’agent :

• deepagents (défaut) — create_deep_agent avec planification, sous-agents à portée et une passe de summarization. Le meilleur choix pour les acteurs vraiment multi-étapes.
• langchain — un create_react_agent simple. Plus léger ; tous les interrupteurs d’intelligence ci-dessous sont sans effet sur ce chemin.

Sur le chemin deepagents, trois interrupteurs façonnent la pile de middleware — tous actifs par défaut par parité, et chacun ajoute des tokens ou de la latence par tour :

Interrupteur	Middleware	Conseil
include_planning	TodoListMiddleware (write_todos)	À garder activé seulement pour les acteurs multi-étapes
include_subagents	fan-out de sous-agents (l’outil task)	Coût en tokens le plus élevé — n’activez que si la délégation est nécessaire
include_reflection	SummarizationMiddleware	Le moins cher des trois, ajoute quand même une passe sur les longs contextes

Deux extras deepagents : extra_middleware ajoute vos propres middleware module.path:ClassName à la pile, et include_lean_channel route un canal de métadonnées (défaut voice) vers un agent allégé à outils simples pour les surfaces sensibles à la latence.

Intégrations, mesh et interrupteurs

integration_type choisit le slot de plugin sous src/integrations/ :

• none (défaut) — outils de domaine + MCP seulement.
• n8n — client REST n8n, proxy /n8n, et découverte de workflow-comme-outil pour les workflows étiquetés n8n_workflow_tag (défaut kaoohi-tool). n8n_allow_workflow_authoring vaut false par défaut et est un contrôle de sécurité, pas une commodité — les workflows peuvent exécuter du code arbitraire sur l’instance de l’équipe qui déploie.
• custom — une intégration écrite à la main dans src/integrations/custom/.

Autres décisions de forme, toutes avec des défauts sûrs : fleet_mesh (client de mesh inter-acteurs pour les acteurs de suite), include_redis_reply_queue, include_scheduler, include_panel (panneau UI côté propriétaire), include_actor_config_mixin (voir ](fr/track-a/config-and-verify/)), docker_workers (1/2/4), et resource_profile (auto se déduit de vos réponses au moment du rendu).

Métadonnées marketplace

Les variables kaoohi_* alimentent l’émetteur de configuration et finissent dans la fiche marketplace de votre acteur : kaoohi_category (deep_agent / productivity / communication / business / data), kaoohi_icon, kaoohi_image_repo (défaut ghcr.io/allcare/<name>, soulignés remplacés par des tirets), kaoohi_required_connectors / kaoohi_optional_connectors, kaoohi_capabilities, et kaoohi_expose_external_api avec ses sous-options operations/protocols (activées par défaut ; chaque kompanion reçoit une URL publique + une clé d’API via l’edge de la plateforme).

Mise en route après génération

Trois commandes avant toute chose :

cd /path/to/my-actor

# 1. Apply ruff's import-modernization fixes to the fresh render
ruff check --fix --unsafe-fixes src/

# 2. Install the package with dev extras
pip install -e ".[dev]"

# 3. Create your env file
cp .env.example .env

Dans .env, définissez au minimum : KOMPANION_ID, TEAM_ID, COLLECTION_ID (des UUID quelconques pour le dev local), POSTGRES_URL / POSTGRES_PASSWORD, REDIS_URL, une clé LLM (OPENAI_API_KEY ou ANTHROPIC_API_KEY), et AUTH_API_URL / AUTH_API_KEY (n’importe quel placeholder — l’autorisation est désactivée en dev).

Puis vérifiez le rendu :

pytest

La suite générée — santé, configuration, réglages, modèles, et les tests de contrat de plateforme — doit être verte sans avoir écrit une ligne de code de domaine. Si elle ne l’est pas, la version du template et votre chaîne d’outils ne sont pas d’accord ; corrigez cela avant de construire la logique de domaine.

Ensuite : ](fr/track-a/extension-points/), là où le vrai travail se passe.

Pour le plongeon de kaboum lui-même sur ce flux, voir son guide utilisateur, partie 2.