rote-cli 0.15.0__tar.gz → 0.17.0__tar.gz

{rote_cli-0.15.0 → rote_cli-0.17.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.15.0/README.md → rote_cli-0.17.0/PKG-INFO

@@ -1,3 +1,67 @@
+Metadata-Version: 2.5
+Name: rote-cli
+Version: 0.17.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: fastmcp-slim[client]<5,>=4.1.3
+Requires-Dist: graphql-core<4,>=3.3
+Requires-Dist: httpx>=0.28
+Requires-Dist: json5<1,>=0.17.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pytest<10,>=9.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary<3,>=2.1.1
+Requires-Dist: rich<16,>=15.0.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.3; 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: 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
+Provides-Extra: openai-api
+Requires-Dist: openai>=2.45; extra == 'openai-api'
+Provides-Extra: serve
+Requires-Dist: fastmcp<5,>=4.1.3; 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
@@ -28,7 +92,8 @@ 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]'
+uv tool install rote-cli          # or: python3 -m venv .venv && . .venv/bin/activate && pip install rote-cli
+                                   # (the first dbos run offers to add the dbos extra; you confirm it)
 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)
 
@@ -51,12 +116,12 @@ rote run (python): succeeded
     "status": "draft",
     "reviewer": null,
     "reimbursable_usd": 2395.59,
-    "pending_usd": 844.39,
-    "returned_usd": 64.17,
+    "pending_usd": 18.75,
+    "returned_usd": 889.81,
     "batch_total_usd": 3304.15,
     "auto_approved": ["Dev Patel", "Emi Tanaka"],
-    "review_items": 4,
-    "blocked_items": 2
+    "review_items": 1,
+    "blocked_items": 5
   }
 }
 ```
@@ -71,7 +136,7 @@ runtime:
 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
+# ... "status": "final", "reimbursable_usd": 2414.34, "returned_usd": 889.81
 ```
 
 What compiling it bought, measured: we ran the same batch twice each way
@@ -109,18 +174,49 @@ pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
 # `rote compile` runs an LLM agent, so it needs a driver: Claude Code
 # (`claude`) or Codex (`codex`) installed and authed, or ANTHROPIC_API_KEY
-# for the in-process `api` driver. The BDR run below takes ~13 min and
-# ~$0.70 with Sonnet. (`rote emit` needs no LLM; see below.)
+# for the in-process `api` driver. (`rote emit` needs no LLM; see below.)
+
+# Default target is a compiled skill: the same skill name and trigger,
+# with its fixed steps in code, run by the agent you already use:
+rote compile ./examples/docs-digest/skill --out ./compiled/
+# rote compile: ✓ docs-digest v...
+#   next: rote skill install .../compiled/runtime/skill/docs-digest
+#     then swap it in for the original docs-digest skill (Claude Code:
+#     ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest)
+#     or see it give the original's answer first: rote try ./examples/docs-digest/skill
+```
+
+rote checks `~/.claude/skills/<name>` before it prints the link. When your
+original skill is already there, `ln -s` would nest the link inside it
+(and exit 0), so rote prints the swap with the original moved aside
+instead, plus the undo. Nothing is deleted, and rote runs none of it:
 
-# Default target is DBOS: durable execution as a plain Python library,
-# no orchestrator to run, SQLite for dev / Postgres for prod:
-rote compile ./examples/bdr-outreach/skill --out ./compiled/
+```
+    then, for Claude Code: your original docs-digest skill is at ~/.claude/skills/docs-digest.
+    To use the compiled one instead, move the original out of the skills folder (nothing is
+    deleted): mv ~/.claude/skills/docs-digest ~/docs-digest.original && ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest
+      undo: rm ~/.claude/skills/docs-digest && mv ~/docs-digest.original ~/.claude/skills/docs-digest
+```
 
-# Or pick another runtime (see the table below):
-rote compile ./examples/bdr-outreach/skill --runtime temporal   --out ./compiled/
+```sh
+# Or emit a background workflow instead (see the table below):
+rote compile ./examples/bdr-outreach/skill --runtime dbos       --out ./compiled/
 rote compile ./examples/bdr-outreach/skill --runtime cloudflare --out ./compiled/
 ```
 
+Measured on claude-sonnet-4-6, original skill against its compiled skill,
+with every compared field matching within the original's own run-to-run
+noise:
+
+| Skill | Original | Compiled skill |
+| --- | --- | --- |
+| expense-audit | 154 s, $0.34 | 43 s, $0.13 |
+| ops-report | 55 s, $0.13 | 42 s, $0.12 |
+| docs-digest | 17.9 s, $0.093 | 16.3 s, $0.049 |
+
+`rote try <skill>` runs that comparison on a skill of yours: it compiles,
+installs, and runs both sides on the same input, after showing the cost.
+
 The name comes from *rote learning*: doing something so many times, so
 reliably, that it becomes mechanical. That's what compilation does to a
 skill.
@@ -181,13 +277,27 @@ 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
@@ -249,6 +359,12 @@ touching Python tooling:
 /plugin install rote@rote
 ```
 
+New here? Run `/rote:setup`, or `uvx --from rote-cli rote setup` in a
+terminal. It imports the MCP servers you already use, compiles one of your
+skills, and shows that the compiled skill gives the same answer, with time
+and cost on each side. It asks before every step and shows the cost before
+anything is spent.
+
 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
@@ -261,16 +377,17 @@ pipelines up as MCP tools so Claude can trigger the deployed workflows
 Prefer a terminal? The same thing is one `uvx` command:
 
 ```sh
-uvx --from rote-cli rote compile ./my-skill --runtime dbos --out ./compiled
+uvx --from rote-cli rote compile ./my-skill --out ./compiled
 ```
 
 **Hosted platform:** [roteskills.com](https://roteskills.com) is the
 project site (concepts, benchmarks methodology, worked examples).
 [app.roteskills.com](https://app.roteskills.com) is Rote Cloud, a
 managed path for teams that would rather not operate a runtime: run
-`rote login` and `rote compile` then runs server-side, streams progress
-back, auto-deploys, and downloads the artifacts locally. Everything in
-this README still works logged out.
+`rote login`, then `rote compile --cloud` (or set `deploy: rote-cloud`
+with `rote init`) runs server-side, streams progress back, auto-deploys,
+and downloads the artifacts locally. Everything in 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
@@ -363,30 +480,33 @@ through your API credentials.
   (over SSH, `--device` prints the code + URL instead), you click
   Approve, and the CLI stores a tenant API key at
   `~/.local/share/rote/cloud.json` (mode 0600). Once logged in,
-  `rote compile` runs **on rote cloud by default**: the skill bundle
+  `rote compile --cloud` runs **on rote cloud**, and so does a compile
+  whose runtime is `cloudflare` or whose `deploy` is `rote-cloud`
+  (flag, env or config). A flagless compile stays local and emits a
+  compiled skill, logged in or not. On rote cloud the skill bundle
   syncs up (sha-diffed, so unchanged files don't re-upload), the
   platform runs the compilation server-side, live progress streams back
   through the same renderer as a local run, the result auto-deploys,
   and the artifacts download into your `--out` directory in the exact
-  local layout. `--local` keeps the compilation on your machine (then
-  the cloudflare-emit + auto-deploy flow applies), `--no-deploy` or a
-  config opt-out (`runtime:` pinned to a local target, or
-  `deploy: none`) keeps everything local; `--cloud` forces the server
-  even where config says otherwise. Logged out, everything works
-  locally exactly as before. `rote whoami` shows the account (verified
+  local layout. `--local` keeps the compilation on your machine (a
+  cloudflare compile then emits locally and auto-deploys), `--no-deploy`
+  or `deploy: none` keeps everything local; `--cloud` forces the server
+  even where config says otherwise. `rote whoami` shows the account (verified
   live); `rote logout` revokes the key server-side and clears the store.
-- **`rote init`**: one-time interactive onboarding: pick where
-  compiled pipelines run (rote cloud, with login offered inline, or
-  a local runtime, with a one-line pitch for each), which compiler
-  driver does the work (availability probed live), and optionally a
-  model. Answers are saved to `~/.config/rote/config.yaml`
+- **`rote init`**: one-time onboarding: pick where compiled pipelines
+  run (locally, with `skill` first and recommended, or rote cloud, with
+  login offered), which
+  compiler driver and model do the work, and who decides a local
+  compile's structure. It shows what it will write and asks before
+  writing. Answers are saved to `~/.config/rote/config.yaml`
   (`--project` writes a `./rote.yaml` that overrides it per-repo) and
-  every later command reads them. It's the only interactive command
-  besides login; CI never hits a prompt.
+  every later command reads them. Every question has a flag, so CI and
+  agents run it with flags and `--yes`; it never prompts without a
+  person at a terminal.
 - **`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
@@ -394,7 +514,11 @@ through your API credentials.
   much of the run is still LLM-decided). `rote compile` writes this to
   `compiled/scorecard.md` automatically. Add `--run` to *measure*
   instead of estimate: it executes both sides for real and appends
-  measured cost, turns, and output agreement across trials.
+  measured cost, turns, and output agreement across trials. With
+  `--run --runtime skill` the after side is the compiled skill, run by
+  an agent through `rote skill run`, so both sides are agents and the
+  table compares context, tokens, time, cost and field fidelity
+  (`--budget` is required).
 - **Per-node inference**: emitted judges read `ROTE_MODEL_<ID>` and
   `ROTE_BASE_URL_<ID>` at runtime, so you can swap the model or point at
   any OpenAI-compatible endpoint (Ollama, vLLM, a gateway) without
@@ -427,13 +551,19 @@ 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).
 
 | Runtime | `--runtime` | Language | Shape | Notes |
 | --- | --- | --- | --- | --- |
-| **DBOS** (default) | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
+| **Compiled skill** (default) | `skill` | Python driver + SKILL.md | a skill dir: the original's name and description, `scripts/` runs the fixed steps, the agent answers only judges and gates | Install with `rote skill install`; runs in Claude Code, Codex and other skill clients through `rote skill run` |
+| DBOS | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
 | Temporal | `temporal` | Python | `workflow.py` + `activities.py` | Signal handlers for HITL gates |
 | Plain Python | `python` | Python | single `main.py` script | Max legibility, stdlib only; refuses HITL-gate pipelines |
 | Cloudflare Workflows | `cloudflare` | TypeScript | `WorkflowEntrypoint` + `wrangler.jsonc` | `wrangler deploy`-ready |