Installation
Dans le dépôt Haki, le SDK est une dépendance éditable locale (pyproject.toml, [tool.uv.sources]) : uv sync à la racine
l’installe automatiquement, avec l’API elle-même.
Utilisé hors du dépôt (votre propre projet) :
HakiClient — synchrone (httpx)
Sync par défaut : les principaux consommateurs sont des scripts et des
hooks d’agent. transport est injectable pour les tests
(httpx.ASGITransport(app=app)).
dict
GET /health.dict
POST /v1/capture. events : liste de dicts au format EventIn.dict
POST /v1/context → {packet, token_count, trace_id}.dict
GET /v1/inspect/{trace_id} (scope obligatoire).dict
GET /v1/timeline.dict
POST /v1/consolidate → {processed}.dict
POST /v1/forget.dict
POST /v1/feedback.dict
POST /v1/conflicts/{id}/resolve.dict
POST /v1/keys — la clé en clair n’apparaît qu’ici.dict
GET /v1/keys (masqué).dict
DELETE /v1/keys/{key_id}.AsyncHakiClient expose exactement les mêmes méthodes, await-ables
(httpx.AsyncClient sous le capot).
Erreurs typées
HakiError
L’API est injoignable (réseau, timeout, DNS…).
HakiError
L’API a répondu avec
{"error": {...}}. Porte status_code,
error_type, field, payload — voir la
liste des types d’erreur.Les deux hooks agent (haki.runtime)
Ce que build_prompt_context() produit exactement
Ce que build_prompt_context() produit exactement
Un bloc délimité
<haki_memory>...</haki_memory> avec une instruction
fixe (« appliquez ces faits, notamment la langue de réponse, citez la
source »), un point par fait (predicate: value (valid from ...; sources: ...)),
puis les épisodes datés, puis les warnings préfixés !. Packet vide
(aucun fait, aucun épisode) → chaîne vide. Texte identique entre le
SDK Python et le SDK TypeScript.capture_turn(client, subject_id, project_id, user_msg, assistant_msg, *, org_id="org_default", agent_id=None, thread_id=None, kind="conversation.turn")
écrit un événement payload.messages = [{role: user, content}, {role: assistant, content}]
avec un idempotency_key unique par appel (f"turn-{uuid4()}").
Gateway (haki.gateway)
httpx.Client/httpx.AsyncClient préconfiguré avec
Authorization et les en-têtes X-Haki-* — voir la
référence Gateway pour le contrat complet.
CLI haki
command
Teste
/health, écrit ~/.haki/config.json.command
Scénario minuté complet : capture → consolidate → nouveau thread →
context rappelle le fait. Sortie 0/1. Tente un bootstrap de clé si
aucune n’est configurée.
command
Santé de l’API + latence.
command
command
command
command
Internes : invoqués par Cursor lui-même (
.cursor/hooks.json),
jamais à la main.