Skip to content

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.

model= is optional (v1.0.2 #1). Omitted, the runtime resolves it to the configured provider's default_model at registration time — "claude-sonnet-4-5" for AnthropicProvider, "gpt-4o-mini" for OpenAIProvider. Passing an explicit model string still works byte-identically; the runtime additionally validates the name against the configured provider's recognizes_model() and raises :class:InvalidRuntimeConfiguration at registration time if the name belongs to a different shipped provider's family (e.g. model="gpt-4o-mini" on a runtime configured with AnthropicProvider). Names no shipped provider recognizes (custom or fine-tuned models) pass through silently.

prompt_template= is the only escape hatch from the runtime-assembled prompt. It is a str.format-style template that receives four placeholders:

  • {system} — the system block: behavior name, frame goal and constraints, role description, and (when output_schema= is set) the schema with an example instance.
  • {view} — the scoped graph view: objects, relations, and recent events, rendered as Markdown (format locked per CONTRACT v0.6 #13).
  • {event} — the triggering event as id, type, actor, and pretty-printed JSON payload with volatile keys stripped.
  • {instruction} — the one-sentence task derived from creates= and output_schema=.

The four placeholders carry the same runtime-assembled content whether or not a template is set; the template only re-arranges them. Omitting prompt_template= (the default) uses the runtime's canonical layout.

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