Jidoka Examples

Each folder under examples/ is one complete deterministic reference agent. It owns the agent code, scenario code, metadata, ExUnit tests, command runner, README, and Livebook. Example modules compile only in the test environment and are not part of the production Jidoka application.

Start Here

If you have not used Jidoka, start with guides/getting-started.md. Then use these examples in order:

1. Getting Started - learn one agent, prompt, and chat/3 result.
2. Support Agent - add one complete tool call and approval flow.
3. Governed Tools - add skills, catalog discovery, bounded browser tools, and deterministic evals.
4. Warranty Claim - add typed context, model policy, media, and results.
5. Durable Refund - add asynchronous, observable, and durable runtime behavior.
6. Workflow Composition - add a complete graph, agent nodes, loops, background runs, and schedules.

The agent, action, control, instruction, and YAML files are application patterns. The scenario, optional scripted model, command runner, test, and manifest files make the examples deterministic and are not required in production.

ScriptedLLM is a model test double. It returns known decisions without a provider or network request. Production code normally uses the model declared by the agent or supplies a runtime model policy; it does not pass ScriptedLLM as :llm.

The small loader.exs file only starts examples outside the test environment. It keeps the Spark compile order out of each command runner and Livebook. Mix compiles the same source files normally when it runs the example tests.

Run Examples

mix run examples/getting_started/example.exs
mix run examples/support_agent/example.exs
mix run examples/warranty_claim/example.exs
mix run examples/durable_refund/example.exs
mix run examples/workflow_composition/example.exs

Test Examples

The root mix test command runs the example tests with the rest of the suite. Use standard ExUnit tags for focused runs:

mix test --only example:support_agent
mix test --only tool_calling
mix test examples/durable_refund/test/execution_and_continuation_test.exs --trace

The YAML manifest lists the aggregate features for an example. Tags on each ExUnit test show the exact features that the scenario verifies.

The first three feature-inventory sections are a closed milestone. Run their focused provider-free parity proofs with:

mix test --include parity test/parity

First Three Sections

All 25 features have product code, deterministic tests, public guides, and an executable example path.

A02 is complete inside the versioned Jidoka document format. E07 is complete for the documented single-node durable contract and application-owned store extension. E08 means data-only replay and lineage-aware forks from safe snapshots; it does not mean arbitrary state editing or effect re-execution.

Existing Capability Proof Coverage

The same example suite now provides executable evidence for all 23 features that had product code but no grouped example proof. Complete features prove their shipped contract. Partial and bounded features prove only the named boundary.

Run all Livebooks without their standalone Mix.install calls:

mix run scripts/check_livebooks.exs -- --project examples/*/*.livemd guides/livebooks/*.livemd

Example Layout

examples/<name>/
├── README.md
├── manifest.yaml
├── example.exs
├── <name>.livemd
├── lib/
│   ├── agent.ex
│   ├── scenario.ex
│   ├── scripted_llm.ex  # optional for multi-step model behavior
│   ├── actions/
│   ├── controls/
│   └── scenarios/       # optional for examples with several workflows
└── test/
    └── <scenario>_test.exs

Choose An Example

Use Getting Started for the smallest complete agent. Use the Support Agent for a controlled tool flow. Use Governed Tools for bounded capability composition and local quality evidence. Use the Warranty Claim for agent authoring, model policy, structured results, and multimodal content. Use the Durable Refund Agent for asynchronous execution, cancellation, traces, usage, process hosting, durable recovery, and safe session forks. Use Workflow Composition for deterministic business graphs, bounded agent nodes, runtime-created work, reconnectable jobs, and cron triggers.