Examples

The Kitaru repo includes runnable examples that demonstrate each primitive. Each example is a standalone project — clone the repo, cd into the example you want, and run it directly.

Get the examples

git clone https://github.com/zenml-io/kitaru.git
cd kitaru/examples/basic_flow
kitaru init
python first_working_flow.py

Run kitaru init once before your first example to set up the local execution environment.

Every example uses imports relative to its own directory, so always cd into the example folder before running.

Connection context

Examples use whatever Kitaru connection context is already active.

If you are just trying Kitaru locally, run them as-is.
If you already have a deployed Kitaru server and want the examples to use it, connect first and verify the active context before running the example.

kitaru login https://my-server.example.com
kitaru status

Browse by goal

I want to...	Example	Run
Start with the smallest runnable flow	`basic_flow/`	`python first_working_flow.py`
See structured metadata logging	`basic_flow/`	`python flow_with_logging.py`
Persist and reload data across executions	`basic_flow/`	`python flow_with_artifacts.py`
Set runtime configuration defaults	`basic_flow/`	`python flow_with_configuration.py`
Inspect and manage past executions	`execution_management/`	`python client_execution_management.py`
Pause for human input and resume later	`execution_management/`	`python wait_and_resume.py`
Replay from a checkpoint with overrides	`replay/`	`python replay_with_overrides.py`
Track a model call inside a flow	`llm/`	`python flow_with_llm.py`
Wrap a PydanticAI agent	`pydantic_ai_agent/`	`python pydantic_ai_adapter.py`
Query executions from an MCP client	`mcp/`	`python mcp_query_tools.py`

For example:

cd examples/basic_flow
python first_working_flow.py

Core workflow basics

Example	Demonstrates	Related docs
`basic_flow/first_working_flow.py`	Smallest `@flow` + `@checkpoint` example	Quickstart
`basic_flow/flow_with_logging.py`	`kitaru.log()` metadata at flow and checkpoint scope	Logging
`basic_flow/flow_with_artifacts.py`	`kitaru.save()` and `kitaru.load()` across executions	Artifacts
`basic_flow/flow_with_configuration.py`	`kitaru.configure()` defaults, overrides, and frozen specs	Configuration

Execution lifecycle and recovery

Example	Demonstrates	Related docs
`execution_management/client_execution_management.py`	`KitaruClient` for listing runs, reading details, and loading data	Execution Management
`execution_management/wait_and_resume.py`	`kitaru.wait()` with inline prompt or CLI input/resume	Wait, Input, and Resume
`replay/replay_with_overrides.py`	Replay from a checkpoint with overridden inputs	Replay and Overrides

LLMs and agent integrations

Example	Demonstrates	Related docs
`llm/flow_with_llm.py`	`kitaru.llm()` prompt-response tracking with usage metadata	Tracked LLM Calls
`pydantic_ai_agent/pydantic_ai_adapter.py`	Wrap a PydanticAI agent with Kitaru replay boundaries	PydanticAI Adapter
`mcp/mcp_query_tools.py`	Query executions and data through the Kitaru MCP server	MCP Server

The LLM and PydanticAI examples require additional dependencies — check each example's README for setup instructions.

Recommended path

If you are learning Kitaru from scratch:

basic_flow/first_working_flow.py — Quickstart
basic_flow/flow_with_logging.py — Logging
basic_flow/flow_with_artifacts.py — Artifacts
execution_management/client_execution_management.py — Execution Management
execution_management/wait_and_resume.py — Wait, Input, and Resume
replay/replay_with_overrides.py — Replay and Overrides
llm/flow_with_llm.py — Tracked LLM Calls
pydantic_ai_agent/pydantic_ai_adapter.py — PydanticAI Adapter
mcp/mcp_query_tools.py — MCP Server