rote-cli 0.14.0__tar.gz → 0.16.0__tar.gz

{rote_cli-0.14.0 → rote_cli-0.16.0}/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -137,8 +138,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
@@ -163,15 +164,15 @@
       has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may accept and charge a
-      fee for acceptance of support, warranty, indemnity, or other liability
-      obligations and/or rights consistent with this License. However, in
-      accepting such obligations, You may act only on Your own behalf and on
-      Your sole responsibility, not on behalf of any other Contributor, and
-      only if You agree to indemnify, defend, and hold each Contributor
-      harmless for any liability incurred by, or claims asserted against,
-      such Contributor by reason of your accepting any such warranty or
-      additional liability.
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 

rote_cli-0.14.0/README.md → rote_cli-0.16.0/PKG-INFO

@@ -1,3 +1,66 @@
+Metadata-Version: 2.5
+Name: rote-cli
+Version: 0.16.0
+Summary: Compile AI agent skills into cheap, fast, deterministic pipelines that run without an LLM in the loop
+Project-URL: Homepage, https://roteskills.com
+Project-URL: Repository, https://github.com/trevhud/rote
+Project-URL: Documentation, https://github.com/trevhud/rote#readme
+Project-URL: Changelog, https://github.com/trevhud/rote/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/trevhud/rote/issues
+Author-email: Trevor Hudson <trevhud@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agent-skills,agent-workflow,ai,anthropic,claude,claude-code,claude-skills,cloudflare,compilation,compiler,dbos,deterministic,dspy,durable-execution,inngest,llm,mcp,pipeline,skill,temporal,token-cost,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: graphql-core<4,>=3.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pytest<10,>=9.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: api
+Requires-Dist: anthropic>=1.15; extra == 'api'
+Provides-Extra: dbos
+Requires-Dist: dbos<4,>=3.3; extra == 'dbos'
+Provides-Extra: dev
+Requires-Dist: anthropic>=1.15; extra == 'dev'
+Requires-Dist: dbos<4,>=3.3; extra == 'dev'
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'dev'
+Requires-Dist: google-api-python-client>=2.201.0; extra == 'dev'
+Requires-Dist: google-auth-httplib2>=0.4.4; extra == 'dev'
+Requires-Dist: google-auth>=2.62.0; extra == 'dev'
+Requires-Dist: httplib2>=0.32.0; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: openai>=2.45; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: requests>=2.34.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: temporalio>=1.7; extra == 'dev'
+Requires-Dist: trustme>=1.2.1; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'mcp'
+Requires-Dist: httpx>=0.28; extra == 'mcp'
+Provides-Extra: openai-api
+Requires-Dist: openai>=2.45; extra == 'openai-api'
+Provides-Extra: serve
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'serve'
+Requires-Dist: httpx>=0.28; extra == 'serve'
+Provides-Extra: temporal
+Requires-Dist: temporalio>=1.7; extra == 'temporal'
+Description-Content-Type: text/markdown
+
 # rote
 
 **Compile AI agent skills into cheap, fast, deterministic pipelines that
@@ -19,6 +82,91 @@ genuinely need judgment. A 10 to 20 minute agent loop becomes a
 background workflow that costs a fraction of the tokens and can be
 regression tested.
 
+### Try it free in 60 seconds
+
+No API key, no subscription, no tokens, no clone. The
+[`expense-audit`](examples/expense-audit/) example is a month-end expense
+audit skill whose compiled pipeline ships with working code, and it comes
+inside the package, so you can emit it and run it before you compile
+anything of your own:
+
+```sh
+uv tool install 'rote-cli[dbos]'   # or: python3 -m venv .venv && . .venv/bin/activate && pip install 'rote-cli[dbos]'
+rote example expense-audit         # copies the skill, IR, code and sample input to ./expense-audit
+                                   # (zero-install: uvx --from rote-cli rote example expense-audit)
+
+# IR -> a plain Python script, then run it on the sample batch
+rote emit expense-audit/expected/pipeline-draft.yaml --runtime python --out expense-audit/app-python
+rote run expense-audit/app-python --input expense-audit/input.json
+```
+
+`rote example` prints these commands (and the dbos and eval ones) for
+the copy it made. `rote example` alone lists what is bundled. Prefer the
+repo? `git clone https://github.com/trevhud/rote.git && cd rote`, then
+use `examples/expense-audit/` in place of `expense-audit/`.
+
+```
+rote run (python): succeeded
+  0.1s
+{
+  "file_report": {
+    "report_path": "/home/you/expense-audit/app-python/reports/2026-09-expense-audit.md",
+    "status": "draft",
+    "reviewer": null,
+    "reimbursable_usd": 2395.59,
+    "pending_usd": 844.39,
+    "returned_usd": 64.17,
+    "batch_total_usd": 3304.15,
+    "auto_approved": ["Dev Patel", "Emi Tanaka"],
+    "review_items": 4,
+    "blocked_items": 2
+  }
+}
+```
+
+Sixteen expense lines in five currencies went through a parallel wave of
+three mandatory checks, a per-employee audit fanned out five ways, and a
+report written to disk, with no model anywhere in the loop. The full
+skill also parks for the controller's approval, which needs a durable
+runtime:
+
+```sh
+rote emit expense-audit/expected/pipeline.yaml --runtime dbos --out expense-audit/app-dbos
+rote run expense-audit/app-dbos --input expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+# ... "status": "final", "reimbursable_usd": 2990.98, "returned_usd": 313.17
+```
+
+What compiling it bought, measured: we ran the same batch twice each way
+with `rote eval --run` (the skill as an agent via `claude -p` on Sonnet,
+against the dbos app above):
+
+| | Skill run as an agent | Compiled pipeline |
+| --- | --- | --- |
+| Wall clock per run | 42.9 s | 9.8 s, mostly DBOS startup |
+| Cost per run | $0.22 | $0 |
+| Identical output across runs | 1 of 2 | 2 of 2 |
+
+So it's roughly 4x faster in practice, it drops from $0.22 a run to
+nothing, and it gives the same answer every time. The agent's two runs
+disagreed on where they filed the report. Full results are in
+[`examples/expense-audit/scorecard.md`](examples/expense-audit/scorecard.md).
+
+To get a scorecard for any pipeline without running anything, use
+`rote eval`. It fetches the live price list once and runs no inference.
+Its numbers are an estimate from turn counts, not a measurement:
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+`pip` installs don't include `examples/`, hence the clone. The other
+examples' extracted modules are `NotImplementedError` stubs waiting for
+real vendor API clients, so `expense-audit` is the one that runs end to
+end. Details in [its README](examples/expense-audit/README.md).
+
+### Compile your own skill
+
 ```sh
 pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
@@ -96,13 +244,40 @@ and want to run a thousand more, unattended.
 
 ## How it works
 
-One `rote compile` run does the whole thing. An LLM agent (itself
-defined as a skill) reads the source skill, applies a structured
-compilation rubric, and emits a runtime-agnostic intermediate
-representation (`pipeline.yaml`), extracted Python modules for the
-deterministic parts, typed signature stubs for the LLM-judge parts, and
+One `rote compile` run does the whole thing. First rote decides the
+pipeline's structure: which nodes exist and of which kind, how they are
+wired, which run once per item, which are mandatory, where a person must
+approve, and which constants they carry (System-1, see
+[`docs/design/system1-compile.md`](docs/design/system1-compile.md)). One
+Claude Haiku call reads the whole skill and proposes that structure, and
+rote checks every node against the skill's text, its tools' schemas and
+the sample input before accepting it. `--structure rules` decides it with
+rules over the skill's text instead, with no model call.
+Then an LLM agent (itself defined as a skill) writes only the text those
+decisions need: the extracted Python modules for the deterministic
+parts, their tests, and the typed signatures and prompts for the
+LLM-judge parts. rote holds the agent to its decisions, and emits a
+runtime-agnostic intermediate representation (`pipeline.yaml`) plus
 runnable code for the durable execution engine of your choice.
 
+`--no-system1` runs the original path instead, where the agent applies
+the full compilation rubric and decides the structure too. `--update`
+always uses that path, because System-1 does not support incremental
+re-compilation yet.
+
+The agent implements the deterministic `pure_function` steps the skill
+spells out and writes tests for them. Before the compile reports
+success, rote checks what the agent wrote and runs those tests, and any
+failure goes back to the agent to fix. The tests are code an LLM wrote
+from a skill you may not have written, so rote runs them in an OS
+sandbox (`sandbox-exec` on macOS, bubblewrap on Linux): no network, no
+reads outside the compile's work dir and the Python install, no programs
+other than Python, no API keys in the environment, an empty `HOME`. If
+no sandbox works on your machine, the tests are skipped and the compile
+says the deliverable is unverified. `--trust-skill` runs them without a
+sandbox, and `--no-verify-tests` never runs them; either way, review
+`<out>/compiled/tests/` before running them yourself.
+
 `rote` is a three-layer system; each layer has one job and contracts on
 a small interface.
 
@@ -124,7 +299,7 @@ a small interface.
 ```
 
 1. **The compiler agent** (`skills/rote-compile/`): a regular
-   Anthropic Skill (`SKILL.md` + four reference files). This is the
+   Anthropic Skill (`SKILL.md` + six reference files). This is the
    *brain*; it runs inside any Skills-compatible surface, and you don't
    need `rote` to use it.
 2. **The IR** (`src/rote/ir.py`): Pydantic models for the five node
@@ -154,7 +329,9 @@ touching Python tooling:
 Then say "compile this skill" (or run `/rote:compile`). It confirms the
 source directory, asks which runtime you want, runs the CLI via
 [uv](https://docs.astral.sh/uv/) in the background, and reports the
-emitted pipeline. A second skill, `/rote:serve`, wires compiled
+emitted pipeline. `/rote:implement` then fills in the emitted stub
+modules against each node's IR contract and verifies the result with
+`rote run`. A third skill, `/rote:serve`, wires compiled
 pipelines up as MCP tools so Claude can trigger the deployed workflows
 (see [docs/mcp-trigger.md](docs/mcp-trigger.md)).
 
@@ -174,9 +351,10 @@ this README still works logged out.
 
 > **Naming note:** the `rote` package on PyPI is an unrelated
 > memoization library that also installs `import rote`, so the two can't
-> share an environment. This project's distribution is `rote-cli` while
-> the CLI command and import name stay `rote`, hence
-> `uvx --from rote-cli rote ...`. See [docs/releasing.md](docs/releasing.md).
+> share an environment. This project's distribution is `rote-cli` and the
+> import name stays `rote`. The package installs the same CLI under two
+> commands, `rote` and `rote-cli`, so both `uvx rote-cli ...` and
+> `uvx --from rote-cli rote ...` work. See [docs/releasing.md](docs/releasing.md).
 
 ### Run on the bundled example
 
@@ -190,7 +368,7 @@ rote compile examples/bdr-outreach/skill --out /tmp/bdr-compiled
 
 On that skill the compiler produces a 22-node IR that's **78.9%
 codifiable** (15 of 19 non-gate nodes), extracts 5 Python modules and 2
-typed judge signatures, and flags 4 mandatory nodes and 3 HITL gates,
+typed judge signatures, and flags 3 mandatory nodes and 3 HITL gates,
 all in ~13 minutes for ~$0.70 (Sonnet via Claude Code). Along the way it
 independently lifts the three MANDATORY exclusion checks out of prose,
 pulls four batch-size constants out of prompt text, and models a
@@ -285,7 +463,7 @@ through your API credentials.
 - **`rote config`**: print every configurable default with its
   effective value *and the layer that set it*. Resolution everywhere is
   `flag > ROTE_* env (ROTE_RUNTIME, ROTE_DEPLOY, ROTE_AGENT,
-  ROTE_MODEL) > project rote.yaml > user config > built-in`. Config
+  ROTE_MODEL, ROTE_EFFORT) > project rote.yaml > user config > built-in`. Config
   files are strict: a typo'd key or value is a loud error, never a
   silent fallback. `--json` for automation.
 - **`rote eval <compiled>`**: render the before/after scorecard (wall
@@ -326,6 +504,11 @@ way, prefer the more deterministic kind.
 Pick with `--runtime`; the same IR drives all of them. Under
 `--backend api`, none of the emitted code references MCP: the
 crystallization step replaces tool calls with direct vendor API calls.
+The compiler agent gets web search and fetch tools for that, writes each
+call from the vendor's current reference page, and cites the page as
+`# docs: <url>`; `compile-report.md` lists every cited page beside
+whether the agent fetched it during the compile. The api backend's calls
+are Python, so it needs a Python runtime (`dbos`, `python`, `temporal`).
 Under the default `--backend mcp`, tool-using nodes emit a working MCP
 client call (with durable park-on-auth on every MCP-capable runtime);
 see [`docs/mcp-client.md`](docs/mcp-client.md).
@@ -369,6 +552,8 @@ subscription path.
 
 ## How it differs from other tools
 
+For a side-by-side with calcifier, skill-to-workflow, Claude Code dynamic workflows, and hand-written workflows, see [docs/comparison.md](docs/comparison.md).
+
 - **vs. raw durable engines (Temporal / Cloudflare / Inngest / Restate):**
   they give you the workflow *runtime*; they don't help you decide *what
   should be a workflow*. `rote` is the missing step that turns a working
@@ -387,16 +572,17 @@ subscription path.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example. The
-fast suite (`pytest tests/`) makes no real API calls and is what CI runs
-on every push, alongside a Python e2e (DBOS over SQLite + the MCP server
-over real stdio). Each adapter also has a `slow`-marked e2e that runs its
-emitted code against the real runtime (Temporal's time-skipping server,
-the TypeScript targets via `tsc --noEmit` and live dev servers, the
-plain-Python subprocess); those need a Node toolchain / Docker, so they
-run locally with `pytest tests/ -m slow`, not in CI.
-
-Known gaps: the extracted modules are `NotImplementedError` stubs
-you fill in with real API-client code, and a Restate adapter is planned.
+fast suite (`pytest tests/`) makes no real API calls, spends no tokens,
+and runs on every push. CI also runs every `slow`-marked e2e suite on
+every push: DBOS over SQLite, the MCP server over real stdio, the
+TypeScript targets via `tsc --noEmit` and live dev servers (Cloudflare
+`wrangler dev`, the Inngest dev server), and DBOS TypeScript against a
+Docker Postgres. Locally, `pytest tests/ -m slow` runs them; they need a
+Node toolchain and Docker.
+
+Known gaps: extracted modules that need a vendor API client (HubSpot,
+ZoomInfo, and so on) come out as `NotImplementedError` stubs you fill in,
+and a Restate adapter is planned.
 Published on
 PyPI as [`rote-cli`](https://pypi.org/project/rote-cli/) via tag-driven
 Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
@@ -416,7 +602,7 @@ measure your own workflow instead of reading someone else's, use
 ```
 rote/
 ├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
-├── skills/rote-compile/  the compiler agent (SKILL.md + 4 reference files)
+├── skills/rote-compile/  the compiler agent (SKILL.md + 6 reference files)
 ├── src/rote/
 │   ├── cli.py             rote compile / emit / eval / serve
 │   ├── ir.py              Pydantic IR models + load_pipeline
@@ -424,6 +610,7 @@ rote/
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
 ├── examples/
+│   ├── expense-audit/     free first run: working extracted code · fan-out · HITL gate
 │   ├── bdr-outreach/      canonical: all 5 node kinds · IR baseline · run snapshots
 │   ├── ops-report/        100% roteness: zero LLM nodes + a HITL gate
 │   ├── deal-monitor/      data-heavy: parallel waves · fan-out judges · template render
@@ -445,12 +632,16 @@ rote/
   emitted code uses under `--backend mcp`: endpoint/credential
   resolution and durable park-on-auth across every MCP-capable runtime
 - [`docs/mcp-trigger.md`](docs/mcp-trigger.md): `rote register` +
-  `rote serve`: compiled pipelines as MCP tools (FastMCP 3.x)
+  `rote serve`: compiled pipelines as MCP tools (FastMCP 4.x)
 - [`docs/releasing.md`](docs/releasing.md): tag-driven PyPI Trusted
   Publishing
 - [`skills/rote-compile/`](skills/rote-compile/): the compiler's
-  `SKILL.md` and its four rubric files (node kinds, crystallization
-  heuristics, IR schema, LLM-judge extraction)
+  `SKILL.md` and its six rubric files (node kinds, crystallization
+  heuristics, IR schema, LLM-judge extraction, implementation, eval
+  estimates)
+- [`examples/expense-audit/`](examples/expense-audit/): the free first
+  run: a hand-compiled pipeline with working extracted code that
+  `rote run` completes on python, dbos, and temporal with no credentials
 - [`examples/bdr-outreach/`](examples/bdr-outreach/): the canonical
   skill, its ground-truth IR, and snapshotted real compiler runs
 - [`examples/ops-report/`](examples/ops-report/): the 100%-roteness