Cookwala Docs
Get started / Reference hub Edit on GitHubMarkdown

Cookwala reference hub

The Core 0.2 API (api/core.openapi.yaml) served by a simulated device, so the quickstart curl works on your laptop and device makers have something to test against before they have hardware. Standard library Python, no persistence, no accounts.

bash
python hub/cookwala_hub.py --port 7878
# or
docker build -t cookwala-hub -f hub/Dockerfile . && docker run -p 7878:7878 cookwala-hub

What it does, in the order Core requires:

  1. POST /v1/executions checks the Idempotency-Key, the Core version, the recipe hash, recalls, the agent mandate scope and allergen blocks, then dry-runs the recipe against the device's capabilities. If any step cannot be verified it answers refused with the reason and the step, before anything heats up.
  2. Accepted executions advance accepted → preparing → running → completed on a clock (default 20 simulated seconds per real second). Steps a person must do or confirm pause the execution in needs_human; POST …/resume with If-Match continues.
  3. Medium temperatures reported in GET /v1/executions/{id} stay inside the operation envelopes from vocab/ops.json.
  4. POST …/stop always works and ends in stopped with an aborted_safe log.
  5. GET …/log returns an ExecutionLog with no personal data and consent.dataset: none.
  6. GET /v1/safety-limits returns the limits pack the hub enforces. No request can change it.

Try the refusal first, then add a person:

bash
H=$(python tools/cookwala_ref.py hash examples/shakshuka.cookwala.json)
curl -s -X POST localhost:7878/v1/executions -H 'Content-Type: application/vnd.cookwala+json' -H 'Idempotency-Key: demo-00000001' \
  -d "{\"core\":\"0.2.0\",\"kind\":\"ExecuteRequest\",\"id\":\"ex-1\",\"recipe\":\"cw:cookwala.ai:example-shakshuka\",\"recipeHash\":\"$H\",\"requestedBy\":\"person-1\",\"idempotencyKey\":\"demo-00000001\"}"
# → "state": "refused", "reason": "needs_human_present" (cutting may not run unattended)
curl -s -X POST localhost:7878/v1/executions -H 'Content-Type: application/vnd.cookwala+json' -H 'Idempotency-Key: demo-00000002' \
  -d "{\"core\":\"0.2.0\",\"kind\":\"ExecuteRequest\",\"id\":\"ex-2\",\"recipe\":\"cw:cookwala.ai:example-shakshuka\",\"recipeHash\":\"$H\",\"requestedBy\":\"person-1\",\"idempotencyKey\":\"demo-00000002\",\"x-hub-human-present\":true}"
# → "state": "accepted" with a plan per step; then GET /v1/executions/ex-2 to watch it run

x-hub-human-present is a hub extension field (Core allows x- fields); a real hub learns presence from its own sensors.

Limits: one device, one process, in-memory state, no TLS, no pairing. It is a test bed, not a product; see docs/CERTIFICATION.md for what a real executor must also prove.

Authentication, CORS and the network #

  • --token TOKEN (or COOKWALA_HUB_TOKEN): every request must carry Authorization: Bearer TOKEN or gets 401 with a problem document. Without it the hub is an open test bed and prints auth=NONE at start-up. POST /v1/executions/{id}/stop never requires the token or an Idempotency-Key header (Core 6.2: a stop is never refused once the caller can reach the executor).
  • --cors ORIGIN: send CORS headers for that one browser origin. Default: no CORS headers at all.
  • --bind 0.0.0.0 to listen on the network; the default is 127.0.0.1.
  • Status documents validate against ExecutionStatus: request is the request id, the running step is under step, and the hub's own plan and simulated medium reading travel as x-hub-plan and x-hub-mediumTempC. ETag is a quoted entity-tag; If-Match accepts it quoted or bare.
  • POST /v1/incidents validates the body against IncidentReport and answers 400 otherwise.
  • Before accepting, the hub runs the same dry run as the CLI with its SafetyLimits: a target outside the operation envelope, a non-numeric temperature, a heat level that cannot hold the envelope, or a value above a stricter local limit is refused (envelope_out_of_range, safety_limit). Allergen blocks match the recipe's declared allergens in every scheme and on every ingredient.

Reference tools over HTTP (/v1/tools/*) #

Not part of the Core API. The hub exposes the reference library so a client in any language gets exactly the behaviour the conformance vectors test: POST /v1/tools/{hash|verify|dryrun|envelope|sms|constraints|convert|ladder|validate|humanitarian} and GET /v1/tools/{recipes|recipes/{id}|devices|vocab/ops|registry}. The arguments and answers are listed in scenarios/OPERATIONS.md; every SDK client (sdk/*) wraps them. validate resolves a document's kind inside container schemas, as tools/validate_specs.py does.