Hooks — swarph_mesh.hooks

HookSet + CallContext + the attribution_post_call default hook.

Tier 2 stability. HookSet and CallContext shapes are consumer-facing.

Lifecycle hooks per PLAN.md §9.

v0.1.0 ships THREE hook points wired into HookSet:

• pre_call — before adapter dispatch

• post_call — after adapter returns successfully

• on_error — adapter raised

PLAN.md §9 names two additional points (pre_parse, post_parse) that wrap the JSON-mode harness. Those are NOT scaffolded in v0.1.0 — add to HookSet when a call site materializes that needs them. Documenting as-future per drop PR #1 review carry-forward #3 (don’t ship empty hook lists for hook points no caller has asked for).

The default post_call hook writes an AttributionEvent via the configured AttributionWriter. Override at SwarphCall construction with hooks=HookSet() to opt out, or with hooks=HookSet(post_call=[attribution_post_call(writer=...)]) to swap the writer per-call.

class swarph_mesh.hooks.CallContext(provider, model, caller, role, mesh_peer, messages, system_prompt=None, json_schema=None, temperature=0.7, max_tokens=None, extra=<factory>)

Bases: object

Per-call envelope passed through the hook pipeline. Mutable — pre_call hooks can rewrite messages (e.g., redaction layer). Adapters MUST treat messages and model as inputs only, not outputs.

Parameters:

• provider (str)

• model (str)

• caller (str)

• role (str)

• mesh_peer (str | None)

• messages (list[ChatMessage])

• system_prompt (str | None)

• json_schema (dict | None)

• temperature (float)

• max_tokens (int | None)

• extra (dict[str, Any])

provider: str

model: str

caller: str

role: str

mesh_peer: str | None

messages: list[ChatMessage]

system_prompt: str | None = None

json_schema: dict | None = None

temperature: float = 0.7

max_tokens: int | None = None

extra: dict[str, Any]

class swarph_mesh.hooks.HookSet(pre_call=<factory>, post_call=<factory>, on_error=<factory>)

Bases: object

Collection of hooks for one SwarphCall. Hooks fire in registration order. Empty by default — callers register what they need.

Parameters:

• pre_call (list[Callable[[CallContext], Awaitable[None]]])

• post_call (list[Callable[[CallContext, LLMResponse], Awaitable[None]]])

• on_error (list[Callable[[CallContext, BaseException], Awaitable[None]]])

pre_call: list[Callable[[CallContext], Awaitable[None]]]

post_call: list[Callable[[CallContext, LLMResponse], Awaitable[None]]]

on_error: list[Callable[[CallContext, BaseException], Awaitable[None]]]

swarph_mesh.hooks.attribution_post_call(writer=None)

Default post-call hook factory: writes one AttributionEvent per successful call.

Use the module-level default writer (FileAttributionWriter by default) if none is provided. Production consumers swap the default writer at startup; per-call override is also supported.

Parameters:

writer (AttributionWriter | None)

Return type:

Callable[[CallContext, LLMResponse], Awaitable[None]]

swarph_mesh.hooks.default_hooks(writer=None)

Return a HookSet with the default attribution post-call hook pre-installed. Other slots empty.

Parameters:

writer (AttributionWriter | None)

Return type:

HookSet