Cookbook
Eight small, tested Sakura projects that run offline.
Generated by cargo run -p agent_docs from compiler/examples/. Edit the example files, then regenerate.
These eight projects teach supported Sakura APIs on the JavaScript backend. Each
project is exercised offline by cargo test -p sakura_cli --test examples;
HTTP and LLM exchanges are synthetic committed cassettes, with no network or API keys.
Use Node 26 for execution, including its built-in SQLite implementation.
The initial API baseline is compiler revision
5cae349516c21714d90d36e87f1cfd6debe980c6.
CI reruns these projects against the compiler in the same checkout. Build that
checkout's CLI and run sakura --version and sakura prompt before adapting a recipe;
pre-alpha APIs can change. An installed skill's frontmatter records its compiler
version and build revision. These teaching examples are separate from the agent
evaluation tasks.
The source of each page is its example's recipe.md, sakura.toml,
src/main.sakura and fixture files. Run cargo run -p agent_docs from compiler/
to regenerate the cookbook and skill reference. Edit those sources, not the rendered pages.
- Decode JSON into a refined record — Decode an order once and let its field refinements reject invalid external data.
- Read a file from a CLI — Decode command-line flags into a record and count a selected file's bytes.
- Retry HTTP with an offline cassette — Retry a safe GET after a rate limit, with a finite attempt count and virtual time in tests.
- Query SQLite with bound parameters — Keep SQL text literal and interpolate values as parameters, then decode typed rows.
- Test a router endpoint directly — Call the router as a function to test dispatch, request validation and response handling.
- Exercise an LLM tool with a script — Drive a tool call and final answer with scripted model output, then replay the same provider exchange.
- Bound an agent loop and its budget — Set both a turn limit and a spending limit, and test rejection before an unaffordable call.
- Update list indices with List.set — Reassign the new list returned by
List.setwhile preserving earlier versions.