Hooks: Tap Into Lifecycle Events

Hooks let you observe and react to graph events without modifying your core node logic. They are ideal for cross-cutting concerns like logging, analytics, sending notifications, or triggering external side effects at specific points in the conversation lifecycle.

Usage

To create a hook, extend GraphHook and override the events you care about. Then register it with graph.add_hook(). You can register multiple hooks - they all fire in the order they were added.

from videosdk.conversational_graph import GraphHook

class MyHook(GraphHook):
    async def on_node_enter(self, node, ctx):
        print(f">>> Entering: {node}")

    async def on_state_update(self, updates, ctx):
        print(f"State updated: {updates}")

    async def on_end(self, ctx):
        print(f"Graph ended. Final: {ctx.states}")

graph.add_hook(MyHook())

Available Events

The following lifecycle events are available. Each event receives the relevant context so you can inspect or act on the current graph state.

Event	When It Fires
on_node_enter(node, ctx)	Before node function called
on_node_exit(node, result, ctx)	After node function returns
on_state_update(updates, ctx)	Whenever state is written
on_state_machine_advance(from_node, to_node, ctx)	Node transition
on_interrupt(node, say, retry_count, ctx)	Interrupt action
on_human_in_loop(node, reason, ctx)	HumanInLoop action
on_resume(payload, ctx)	Graph resumed
on_end(ctx)	Graph terminates

All methods are async, default to no-ops. Override only what you need.