Lifecycle API

These are the available lifecycle hooks for Burr. Implement these classes and add instances to the application builder to customize your state machines’s execution.

class burr.lifecycle.base.PreRunStepHook

Hook that runs before a step is executed

abstractmethod pre_run_step(
*,
app_id: str,
partition_key: str,
sequence_id: int,
state: State,
action: Action,
inputs: Dict[str, Any],
**future_kwargs: Any,
)

Run before a step is executed.

Parameters:

  • state – State prior to step execution

  • action – Action to be executed

  • inputs – Inputs to the action

  • sequence_id – Sequence ID of the action

  • future_kwargs – Future keyword arguments

class burr.lifecycle.base.PreRunStepHookAsync

Async hook that runs before a step is executed

abstractmethod async pre_run_step(
*,
app_id: str,
partition_key: str,
sequence_id: int,
state: State,
action: Action,
inputs: Dict[str, Any],
**future_kwargs: Any,
)

Async run before a step is executed.

Parameters:

  • state – State prior to step execution

  • action – Action to be executed

  • inputs – Inputs to the action

  • sequence_id – Sequence ID of the action

  • future_kwargs – Future keyword arguments

class burr.lifecycle.base.PostRunStepHook

Hook that runs after a step is executed

abstractmethod post_run_step(
*,
app_id: str,
partition_key: str,
sequence_id: int,
state: State,
action: Action,
result: Dict[str, Any] | None,
exception: Exception,
**future_kwargs: Any,
)

Run after a step is executed.

Parameters:

  • state – State after step execution

  • action – Action that was executed

  • result – Result of the action

  • sequence_id – Sequence ID of the action

  • exception – Exception that was raised

  • future_kwargs – Future keyword arguments

class burr.lifecycle.base.PostRunStepHookAsync

Async hook that runs after a step is executed

abstractmethod async post_run_step(
*,
app_id: str,
partition_key: str,
sequence_id: int,
state: State,
action: Action,
result: dict | None,
exception: Exception,
**future_kwargs: Any,
)

Async run after a step is executed

Parameters:

  • state – State after step execution

  • action – Action that was executed

  • result – Result of the action

  • sequence_id – Sequence ID of the action

  • exception – Exception that was raised

  • future_kwargs – Future keyword arguments

class burr.lifecycle.base.PostApplicationCreateHook

Synchronous hook that runs post instantiation of an Application object (after .build() is called on the ApplicationBuilder object.)

abstractmethod post_application_create(
*,
app_id: str,
partition_key: str | None,
state: State,
application_graph: ApplicationGraph,
parent_pointer: ParentPointer | None,
spawning_parent_pointer: ParentPointer | None,
**future_kwargs: Any,
)

Runs after an “application” object is instantiated. This is run by the Application, in its constructor, as the last step.

Parameters:

  • app_id – Application ID

  • partition_key – Partition key of application

  • state – Current state of the application

  • application_graph – Application graph of the application, representing the state machine

  • parent_pointer – Forking parent pointer of the application (application that it copied from)

  • spawning_parent_pointer – Spawning parent pointer of the application (application that it was launched from)

  • future_kwargs – Future keyword arguments for backwards compatibility

class burr.lifecycle.base.PreStartSpanHook

Hook that runs before a span is started in the tracing API. This can be either a context manager or a logger of sorts.

class burr.lifecycle.base.PreStartSpanHookAsync
class burr.lifecycle.base.PostEndSpanHook

Hook that runs after a span is ended in the tracing API. This can be either a context manager or a logger.

class burr.lifecycle.base.PostEndSpanHookAsync

Hook that runs at the end of an async span

class burr.lifecycle.base.ExecuteMethod(*values)

A set of the application methods the user can call. These correspond to interface methods in application.py, and allow us to say which method is being called for the following hooks.

class burr.lifecycle.base.PreApplicationExecuteCallHook

Hook that runs before an application method (step/iterate/run/stream…) is called.

class burr.lifecycle.base.PreApplicationExecuteCallHookAsync

Hook that runs before an async application method (step/iterate/run/stream…) is called.

class burr.lifecycle.base.PostApplicationExecuteCallHook

Hook that runs after an application method (step/iterate/run/stream…) is called.

class burr.lifecycle.base.PostApplicationExecuteCallHookAsync

Hook that runs after an async application method (step/iterate/run/stream…) is called.

class burr.lifecycle.base.PreStreamGenerateHook

Hook that runs before the generator produces its next item. Paired with PostStreamGenerateHook to bracket the actual generation time for each stream item, excluding consumer processing time.

class burr.lifecycle.base.PreStreamGenerateHookAsync

Hook that runs before the generator produces its next item (async variant). Paired with PostStreamGenerateHookAsync to bracket the actual generation time for each stream item, excluding consumer processing time.

class burr.lifecycle.base.PostStreamGenerateHook

Hook that runs after the generator has produced an item (or exhausted/errored). Paired with PreStreamGenerateHook to bracket the actual generation time for each stream item, excluding consumer processing time.

class burr.lifecycle.base.PostStreamGenerateHookAsync

Hook that runs after the generator has produced an item (or exhausted/errored). Async variant. Paired with PreStreamGenerateHookAsync to bracket the actual generation time for each stream item, excluding consumer processing time.

These hooks are available for you to use:

class burr.lifecycle.default.StateAndResultsFullLogger(jsonl_path: str, mode: ~typing.Literal['append', 'w'] = 'append', json_dump: ~typing.Callable[[dict], str] = <function safe_json>)

Logs the state and results of the action in a jsonl file.

__init__(jsonl_path: str, mode: ~typing.Literal['append', 'w'] = 'append', json_dump: ~typing.Callable[[dict], str] = <function safe_json>)

Initializes the logger.

Parameters:

  • jsonl_path – Path to the jsonl file

  • mode – Mode to open the file in. Either “append” or “w”

  • json_dump – Function to use to dump the json. Default is safe_json

class burr.lifecycle.default.SlowDownHook(pre_sleep_time: float = 0.5, post_sleep_time: float = 0.5)

Slows down execution. You’ll only want to use this for debugging/visualizing.

__init__(pre_sleep_time: float = 0.5, post_sleep_time: float = 0.5)

Initializes the hook.

Parameters:

  • pre_sleep_time – Time to sleep before the step

  • post_sleep_time – Time to sleep after the step