Esta página foi traduzida por máquina e ainda não foi revisada por uma pessoa. O inglês é a referência; correções são bem-vindas no GitHub. GitHub

Cookwala / Desenvolvedores

Core 0.2 · normativo, sob revisão

De um dry run a um relatório de conformance

Um primeiro caminho recomendado, depois os SDKs, a API, os bindings e os evals. Tudo abaixo funciona hoje; o que ainda não existe será indicado.

Quickstart Core 0.2 reference Core API (OpenAPI)

Quickstart: cinco minutos, sem 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

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 e ferramentas

Um cliente hub com as mesmas 25 operações em 13 idiomas (Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, C#, Swift, C++, Ruby, PHP, curl), e 101 cenários com código em cada um: SDK e cenários.

Pacote Python e CLI

pip install -e sdk/python. hash, verify, dryrun, envelope, convert, sms, constraints, validate, conformance, humanitarian, export, init, hub, mcp. Apenas biblioteca padrão.

now · editable install; PyPI wheel next →

Tipos TypeScript

Tipos para todos os 24 esquemas, gerados e verificados por tipo; o dry run no navegador como um módulo. Um namespace por esquema.

now · source package; npm next →

Servidor MCP

Catorze ferramentas só de leitura para qualquer cliente MCP, iniciadas com npx -y @cookwala/mcp: search, get, dry_run, explain_step, check_envelope, check_mandate, parse_sms e mais. Sem servidor para hospedar. Nunca cozinha.

now →

Hub de referência

A Core API com um dispositivo simulado: dry run antes do calor, máquina de estados baseada em um relógio, envelopes respeitados, stop sempre funciona. Dockerfile incluído.

now →

Interfaces ROS 2

cookwala_msgs: Ações ExecuteRecipe e ExecuteNode; cancel é uma parada segura; nenhum campo goal pode elevar um limite.

now · bridge node is a good first contribution →

Exportadores LeRobot e OpenTelemetry

Os logs de execução tornam-se tarefas LeRobotDataset v3 e traces OTLP, apenas com o consentimento do household.

now →

Novo: código de exemplo para cada papel

Clientes, um agente planejador sob mandato, um orquestrador, portões de segurança, recuperação e relatórios, em Python, JavaScript, Java e C#. Rode a demo sem instalar nada e leve o mesmo código para pip, npm, Maven, Gradle, NuGet, Homebrew, Chocolatey, Scoop, apt, RPM, pacman, conda, snap, um contêiner, Helm, Artifactory ou uma função no Azure, AWS, Google Cloud ou OpenShift.

Exemplos e pacotes Rodar a demo

Construído e testado pela CI; os registros chegam com a primeira versão marcada.

A Core API

Uma API que cada executor implementa: POST /v1/executions, status, stop, resume, log, safety limits, capabilities; catalogs adicionam recalls e incidentes. Idempotency keys em cada POST, If-Match em mudanças, refusal como uma resposta normal, stop nunca recusado por autorização.

core.openapi.yaml · registry.openapi.yaml · humanitarian.openapi.yaml · household.openapi.yaml (local) · todos os schemas em um bundle

Versionamento

Semver conforme a especificação; versões minor são aditivas; majors são anunciadas com 12 meses de antecedência; o índice serve cada major por 3 anos. O Core é 0.2.x; os perfis versionam independentemente e declaram a versão do Core de que precisam. Governance

Conformance

137 vetores públicos: hashing (incluindo o exemplo RFC 8785), assinaturas (incluindo uma chave RFC 8032), revogação, divulgação seletiva, cadeias de eventos e checkpoints testemunhados, unidades, envelopes e sensor ladders, máquinas de estado, política de divulgação, regras de registry, gramática de SMS, política de sinal, verificação de relay.

Um claim é um ConformanceReport assinado: autodeclarado → verificado por um operador de registry → certificado por um certificador independente (nenhum engajado ainda). Relatórios, nunca badges. The path · vectors

Evals para agentes

Dez casos de promptfoo verificam se um agente segue as regras do Core: texto não confiável, mandates e caps, blocos de alérgenos, limites de segurança, unattended operations, recalls, over-refusal. Adicione providers para comparar modelos; publique com o model id, data e config hash. Benchmark

Ao lado do que fica, e o que não é

Nenhum destes é um contrato verificado por máquina entre uma receita e um aparelho. Cookwala é só isso, e usa os outros onde cabem.

Schema.org Recipe	Descreve uma receita para buscadores: ingredientes, tempos, nutrição. Sem operações, sem condições de fim, nada que um aparelho verifique. Uma receita Cookwala pode ser publicada com campos Schema.org para ser encontrada.
LeRobot (Hugging Face)	Um formato de dados do que um robô fez: observações e ações. Não diz o que é uma receita nem quando um passo é inseguro. Cookwala exporta para ele registros de execução consentidos.
HACCP	Um sistema de gestão para pessoas: perigos, pontos críticos, registros. Cookwala codifica os pontos de controle para que uma máquina os verifique; não substitui o plano HACCP de uma cozinha.
Matter (CSA)	Controle de aparelhos: pôr um forno numa temperatura, ler uma sonda. Cookwala diz o que pedir ao forno e quando recusar; a tabela de mapeamento está em bindings/matter.json.
ROS 2	Middleware de robôs: como um robô se move e fala consigo. Cookwala fica acima do movimento e oferece interfaces ROS 2 para a camada de tarefa.

Conceitos, em uma tabela

Termo	O que é	O que não é
Operation envelope	O significado físico de uma operação: meio, faixa de temperatura, atenção, sem supervisão permitido, sensor ladder, perigos	Uma configuração de receita; as receitas a restringem, nunca a ampliam
Sensor ladder	Formas de verificar um passo, por ordem de preferência: um sensor, uma estimativa registada, tempo, uma pessoa. Se nenhum degrau for alcançável, recusar	Um recurso de fallback para suposições
Limite de segurança	Aplicado no dispositivo; o mais estrito vence sempre; nenhuma mensagem pode aumentá-lo	Um campo em uma receita ou um pedido
Mandato do agente	Escopos, limites, provedores permitidos, expiração, lista de confirmação prévia, assinado pelo principal	Um prompt
Restrição derivada	O único objeto doméstico que um provedor recebe ("entregar das 17:00 às 18:00, rotular para amendoins")	Um fato do contexto doméstico
Relatório de conformidade	Um registro assinado de quais vetores foram executados, com qual ferramenta, quando, em quê	Um emblema

Problemas comuns

Tudo é recusado com needs_human_present: cortar, refogar e fritar podem não ser executados sem supervisão; passar --human-present.
Recusado com missing_sensor_no_fallback em fritura profunda: a fritura profunda tem um degrau, um termômetro de óleo; esse é o padrão de funcionamento.
O hash não coincide: os hashes excluem apenas hash e signature; qualquer outra alteração é uma nova revisão.
A validação diz que uma temperatura está fora do envelope: o alvo da receita deve estar dentro da faixa da operação; altere a operação ou o alvo.
O Python não consegue importar cookwala: instale a partir de um checkout ou defina COOKWALA_ROOT.

Contribuir

Implemente a Core API em um dispositivo ou um hub e publique um relatório; escreva um nó de ponte ROS 2; adicione casos de ataque ao benchmark do agente; adicione vetores; proponha um RFC. Como · RFCs · GitHub

Os documentos também estão em /llms.txt e como Markdown por página, para leitores de IA.