From a dry run to a conformance report

One recommended first path, then the SDKs, the API, the bindings and the evals. Everything below runs today; what does not yet exist says so.

Quickstart Core 0.2 reference Core API (OpenAPI)

Quickstart: five minutes, no hardware

Get the tools.

git clone https://github.com/amado2k5/cookwala && cd cookwala
pip install -e sdk/python            # standard library only; add [full] for schema validation and signatures

Find, view and export a recipe. Search the catalog (2,051 recipes, names in 25 languages), read one in the terminal, and export it to Cooklang or schema.org. Offline, from your checkout.
```
cookwala search koshari --cuisine EG --level V1
cookwala get example-koshari --lang ar
cookwala export cooklang shakshuka -o shakshuka.cook
cookwala export schema-org shakshuka
```
example-koshari Koshari V1 EG 1 of 1 match
Cooklang has no place for hazards, critical control points or end conditions, so the export leaves them out and says so in the file. Do not use an exported file to drive a device. Facts-only V0 recipes export their ingredients only.
Hash a recipe. An executor cooks exactly this revision and refuses on mismatch.
```
cookwala hash examples/koshari.cookwala.json
```
sha256:f7fc3745af514…
Can this device cook it? Nothing is executed; the answer comes before heat.
```
cookwala dryrun examples/koshari.cookwala.json --device examples/capabilities/robot-arm.json
```
{"state": "refused", "refusal": {"reason": "missing_capability", "node": "n1", "detail": "device cannot perform cw.op.boil and no person is present to do it"}}
```
cookwala dryrun examples/koshari.cookwala.json --device examples/capabilities/robot-arm.json --human-present
```
{"state": "accepted", "plan": [{"node": "n1", "op": "cw.op.boil", "by": "human", "verifiedBy": "human"}, …]}
Check a temperature trace against a safe band. 99 °C is a boil, not a simmer.
```
python -c "import cookwala as cw; print(cw.check_envelope('cw.op.simmer', [{'t':0,'tempC':60},{'t':60,'tempC':94},{'t':90,'tempC':99}]))"
```
{'envelopeOk': False, 'targetOk': None, 'reason': 'left_envelope'}
Run the conformance vectors and write a report. The report is the artifact behind any claim.
```
cookwala conformance --report report.json
```
conformance: 137/137 passed (7 core suites, 5 profile suites) report -> report.json
Run the reference hub and cook against the Core API.
```
cookwala hub --port 7878
curl -s localhost:7878/v1/safety-limits | head
```
Then POST /v1/executions as in the hub README: refused without a person present, accepted with one, stop always works, the log carries no personal data.

SDKs and tools

One hub client with the same 25 operations in 13 languages (Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, C#, Swift, C++, Ruby, PHP, curl), and 101 scenarios with code in each: SDK and scenarios.

Python package and CLI

pip install -e sdk/python. search, get, export (Cooklang, schema.org), hash, verify, dryrun, envelope, convert, sms, constraints, validate, conformance, humanitarian, init, hub, mcp. Standard library only.

now · editable install; PyPI wheel next →

TypeScript types

Types for all 24 schemas, generated and type-checked; the browser dry run as a module. One namespace per schema.

now · source package; npm next →

MCP server

Fourteen read-only tools for any MCP client, started with npx -y @cookwala/mcp: search, get, dry_run, explain_step, check_envelope, check_mandate, parse_sms and more. No server to host. Never cooks.

now →

Reference hub

The Core API with a simulated device: dry run before heat, state machine on a clock, envelopes respected, stop always works. Dockerfile included.

now →

ROS 2 interfaces

cookwala_msgs: ExecuteRecipe and ExecuteNode actions; cancel is a safe stop; no goal field can raise a limit.

now · bridge node is a good first contribution →

LeRobot and OpenTelemetry exporters

Execution logs become LeRobotDataset v3 tasks and OTLP traces, only with the household's consent.

now →

New: sample code for every role

Clients, a planner agent under a mandate, an orchestrator, safety gates, recovery and reports, in Python, JavaScript, Java and C#. Run the demo with no install, then take the same code to pip, npm, Maven, Gradle, NuGet, Homebrew, Chocolatey, Scoop, apt, RPM, pacman, conda, snap, a container, Helm, Artifactory, or a function on Azure, AWS, Google Cloud or OpenShift.

Samples and packages Run the demo

Built and tested by CI; registries come with the first tagged release.

The Core API

What an operation envelope looks like in the vocabulary that every dry run reads:

"cw.op.deep_fry": {
  "envelope": {
    "medium": "oil",
    "tempC": { "min": 160, "max": 190 },
    "unattended": false,
    "sensorLadder": ["cw.sense.oil_temp"],
    "note": "No oil-temperature sensor, no deep frying."
  }
}

One API every executor implements: POST /v1/executions, status, stop, resume, log, safety limits, capabilities; catalogs add recalls and incidents. Idempotency keys on every POST, If-Match on changes, refusal as a normal answer, stop never refused for authorization.

core.openapi.yaml · registry.openapi.yaml · humanitarian.openapi.yaml · household.openapi.yaml (local) · all schemas in one bundle

Versioning

Semver per spec; minor versions additive; majors announced 12 months ahead; the index serves each major for 3 years. Core is 0.2.x; profiles version independently and declare the Core version they need. Governance

Conformance

137 public vectors: hashing (including the RFC 8785 example), signatures (including an RFC 8032 key), revocation, selective disclosure, event chains and witnessed checkpoints, units, envelopes and sensor ladders, state machines, disclosure policy, registry rules, SMS grammar, signal policy, relay verification.

A claim is a signed ConformanceReport: self-declared → verified by a registry operator → certified by an independent certifier (none engaged yet). Reports, never badges. The path · vectors

Evals for agents

Ten promptfoo cases check that an agent follows the Core rules: untrusted text, mandates and caps, allergen blocks, safety limits, unattended operations, recalls, over-refusal. Add providers to compare models; publish with the model id, date and config hash. Benchmark

What it sits beside, and what it is not

None of these is a machine-checked contract between a recipe and a device. Cookwala is only that, and uses the others where they fit.

Schema.org Recipe	Describes a recipe for search engines: ingredients, times, nutrition. No operations, no end conditions, nothing a device verifies. A Cookwala recipe can be published with Schema.org fields for discovery.
LeRobot (Hugging Face)	A dataset format for what a robot did: observations and actions. It does not say what a recipe is or when a step is unsafe. Cookwala exports consented execution logs to it.
HACCP	A management system for people: hazards, critical control points, records. Cookwala encodes control points so a machine can check them; it does not replace a kitchen's HACCP plan.
Matter (CSA)	Device control: set an oven to a temperature, read a probe. Cookwala says what the oven should be asked to do and when to refuse; a mapping table lives in bindings/matter.json.
ROS 2	Robot middleware: how a robot moves and talks to itself. Cookwala sits above motion and ships ROS 2 interfaces for the task layer.

Concepts, in one table

Term	What it is	What it is not
Operation envelope	The physical meaning of an operation: medium, temperature band, attention, unattended allowed, sensor ladder, hazards	A recipe setting; recipes narrow it, never widen it
Sensor ladder	Ways to verify a step, best first: a sensor, a logged estimate, time, a person. No rung reachable means refuse	A fallback to guessing
Safety limit	Enforced on the device; stricter always wins; no message can raise it	A field in a recipe or a request
Agent mandate	Scopes, caps, allowed providers, expiry, confirm-before list, signed by the principal	A prompt
Derived constraint	The only household object a provider receives ("deliver 17:00 to 18:00, label for peanuts")	A household fact
Conformance report	A signed record of which vectors ran, with what tool, when, on what	A badge

Common problems

Everything is refused with needs_human_present: cutting, sautéing and frying may not run unattended; pass --human-present.
Refused with missing_sensor_no_fallback on deep frying: deep frying has one rung, an oil thermometer; that is the standard working.
The hash doesn't match: hashes exclude only hash and signature; any other change is a new revision.
Validation says a temperature is outside the envelope: the recipe target must lie inside the operation's band; change the operation or the target.
Python can't import cookwala: install from a checkout or set COOKWALA_ROOT.

Contribute

Implement the Core API on a device or a hub and publish a report; write a ROS 2 bridge node; add attack cases to the agent benchmark; add vectors; propose an RFC. How · RFCs · GitHub

Docs are also at /llms.txt and as Markdown per page, for AI readers.