Behaviors¶
The behavior decorators and base classes. For the conceptual
model see concepts/behaviors;
for the activation rules and the determinism contract see
concepts/patterns and
concepts/failure-model.
Decorators¶
Decorate a function as an event-driven behavior.
v0.7 additions (both keyword-only):
- pattern=: a Cypher subset pattern string. When set, the
behavior fires only when the pattern matches the post-event
graph state. Combined with on= both conditions must hold
(CONTRACT v0.7 #11). Matches are exposed as ctx.matches.
- activate_after=: int event count or "N events". Delays
invocation by N events; re-checks where= at fire time
(CONTRACT v0.7 #13).
Decorate a function as an LLM-driven behavior.
The decorated function's signature is
(event, graph, ctx, llm_output) -> None. The runtime assembles
the prompt, calls the provider, parses the structured output, and
only then invokes the handler with the parsed result. Failures
flow as behavior.failed events with a reason from
CONTRACT v0.6 #11 (llm.parse_error, llm.schema_violation,
llm.network_error, llm.rate_limited, budget.cost_exhausted).
Keyword-only on purpose — @llm_behavior carries enough
parameters that positional binding would be a footgun.
Decorate a function as a relation behavior — fires once per matching edge.
v0.7: also accepts pattern= and activate_after= per CONTRACT
v0.7 #8 / #11 / #13.
Base classes¶
Bases: Behavior
A behavior whose body is an LLM call.
The runtime owns prompt assembly, cache lookup, the provider call,
event emission, and structured-output parsing. The developer's
handler is invoked only after the LLM has responded (or a cached
response was found) and the output was successfully parsed.
CONTRACT v0.7: tools= declares a list of Tool objects (or
strings naming globally-registered tools) the LLM can call during
the turn loop. The runtime orchestrates the loop; the handler
receives only the final structured output, never raw tool calls.
build_prompt(event, graph, *, frame=None)
¶
Assemble the prompt that would be sent for this event.
CONTRACT v0.6 #20 — public so a developer can inspect prompts without making an API call. Reproducible (pure over inputs); cheap (no I/O).