rote-cli 0.6.0__tar.gz → 0.8.0__tar.gz

{rote_cli-0.6.0 → rote_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rote-cli
-Version: 0.6.0
+Version: 0.8.0
 Summary: Graduate fuzzy AI skills into deterministic, reliable workflows
 Project-URL: Homepage, https://github.com/trevhud/rote
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -326,17 +326,16 @@ subscription path.
 
 ## Status
 
-`rote` is **pre-1.0**. The end-to-end flow works on the BDR example, and
-all six adapters are validated by a `slow`-marked e2e suite that runs the
-emitted code against real runtimes (DBOS over SQLite, Temporal's
-time-skipping server, the TypeScript targets compiled with `tsc --noEmit`
-and driven through both HITL gates on live dev servers, the plain-Python
-script as a subprocess, and the MCP server over real stdio). The fast
-suite (`pytest tests/`) makes no real API calls; the integration suite is
-`pytest tests/ -m slow`.
-
-Known gaps: the `codex` driver is a stub (`is_available` works, `run`
-isn't implemented), the extracted modules are `NotImplementedError` stubs
+`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, a Restate adapter is planned, and
 `fan_out` nodes currently receive the whole upstream list in one
 invocation (per-element dispatch is a planned enhancement). Published on
@@ -357,7 +356,10 @@ rote/
 │   ├── graduator/         orchestrator + drivers/ (claude · codex · anthropic_api)
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
-├── examples/bdr-outreach/ source skill · hand-drafted IR baseline · run snapshots
+├── examples/
+│   ├── 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
 └── tests/                 fast + slow suites (pytest -m slow)
 ```
 
@@ -377,6 +379,12 @@ rote/
   heuristics, IR schema, LLM-judge extraction)
 - [`examples/bdr-outreach/`](examples/bdr-outreach/) — the canonical
   skill, its ground-truth IR, and snapshotted real graduator runs
+- [`examples/ops-report/`](examples/ops-report/) — the 100%-roteness
+  archetype: every step deterministic, one durable HITL gate, zero LLM
+  nodes after graduation
+- [`examples/deal-monitor/`](examples/deal-monitor/) — the data-heavy
+  archetype: parallel entry waves, fan-out judges, and a template render
+  replacing per-run LLM-generated HTML
 
 ---
 
@@ -384,19 +392,17 @@ rote/
 
 In rough priority order:
 
-1. **`CodexDriver` implementation** — same shape as `ClaudeDriver` but
-   spawning `codex exec`; unlocks ChatGPT subscribers.
-2. **Re-graduate BDR end-to-end with `signature_spec`** — the bundled IR
+1. **Re-graduate BDR end-to-end with `signature_spec`** — the bundled IR
    was hand-extended with structured schemas; the rubric now teaches the
    field, but no real run has produced one yet.
-3. **Pre-filter as a `pure_function` node** — today hard thresholds are
+2. **Pre-filter as a `pure_function` node** — today hard thresholds are
    lifted into a judge's `forward()`, which works for Temporal but not
    Cloudflare; a separate node makes the short-circuit uniform.
-4. **More example skills** — BDR is one shape; research-heavy,
+3. **More example skills** — BDR is one shape; research-heavy,
    retrieval-heavy, and code-review skills stress the IR differently.
-5. **`fan_out` per-element dispatch** — currently the whole upstream list
+4. **`fan_out` per-element dispatch** — currently the whole upstream list
    arrives in one invocation.
-6. **The graduator graduating itself** — `rote-graduate` is a SKILL.md;
+5. **The graduator graduating itself** — `rote-graduate` is a SKILL.md;
    pointing `rote graduate` at it should crystallize its rubric-grade
    pieces and leave only the genuinely fuzzy judgments in the loop.
 

{rote_cli-0.6.0 → rote_cli-0.8.0}/README.md

@@ -280,17 +280,16 @@ subscription path.
 
 ## Status
 
-`rote` is **pre-1.0**. The end-to-end flow works on the BDR example, and
-all six adapters are validated by a `slow`-marked e2e suite that runs the
-emitted code against real runtimes (DBOS over SQLite, Temporal's
-time-skipping server, the TypeScript targets compiled with `tsc --noEmit`
-and driven through both HITL gates on live dev servers, the plain-Python
-script as a subprocess, and the MCP server over real stdio). The fast
-suite (`pytest tests/`) makes no real API calls; the integration suite is
-`pytest tests/ -m slow`.
-
-Known gaps: the `codex` driver is a stub (`is_available` works, `run`
-isn't implemented), the extracted modules are `NotImplementedError` stubs
+`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, a Restate adapter is planned, and
 `fan_out` nodes currently receive the whole upstream list in one
 invocation (per-element dispatch is a planned enhancement). Published on
@@ -311,7 +310,10 @@ rote/
 │   ├── graduator/         orchestrator + drivers/ (claude · codex · anthropic_api)
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
-├── examples/bdr-outreach/ source skill · hand-drafted IR baseline · run snapshots
+├── examples/
+│   ├── 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
 └── tests/                 fast + slow suites (pytest -m slow)
 ```
 
@@ -331,6 +333,12 @@ rote/
   heuristics, IR schema, LLM-judge extraction)
 - [`examples/bdr-outreach/`](examples/bdr-outreach/) — the canonical
   skill, its ground-truth IR, and snapshotted real graduator runs
+- [`examples/ops-report/`](examples/ops-report/) — the 100%-roteness
+  archetype: every step deterministic, one durable HITL gate, zero LLM
+  nodes after graduation
+- [`examples/deal-monitor/`](examples/deal-monitor/) — the data-heavy
+  archetype: parallel entry waves, fan-out judges, and a template render
+  replacing per-run LLM-generated HTML
 
 ---
 
@@ -338,19 +346,17 @@ rote/
 
 In rough priority order:
 
-1. **`CodexDriver` implementation** — same shape as `ClaudeDriver` but
-   spawning `codex exec`; unlocks ChatGPT subscribers.
-2. **Re-graduate BDR end-to-end with `signature_spec`** — the bundled IR
+1. **Re-graduate BDR end-to-end with `signature_spec`** — the bundled IR
    was hand-extended with structured schemas; the rubric now teaches the
    field, but no real run has produced one yet.
-3. **Pre-filter as a `pure_function` node** — today hard thresholds are
+2. **Pre-filter as a `pure_function` node** — today hard thresholds are
    lifted into a judge's `forward()`, which works for Temporal but not
    Cloudflare; a separate node makes the short-circuit uniform.
-4. **More example skills** — BDR is one shape; research-heavy,
+3. **More example skills** — BDR is one shape; research-heavy,
    retrieval-heavy, and code-review skills stress the IR differently.
-5. **`fan_out` per-element dispatch** — currently the whole upstream list
+4. **`fan_out` per-element dispatch** — currently the whole upstream list
    arrives in one invocation.
-6. **The graduator graduating itself** — `rote-graduate` is a SKILL.md;
+5. **The graduator graduating itself** — `rote-graduate` is a SKILL.md;
    pointing `rote graduate` at it should crystallize its rubric-grade
    pieces and leave only the genuinely fuzzy judgments in the loop.
 

{rote_cli-0.6.0 → rote_cli-0.8.0}/skills/rote-graduate/references/eval-estimates.md

@@ -25,6 +25,13 @@ Ground rules:
   (agents batch parallel calls). If it says "repeat until you have 25
   qualified contacts", estimate the realistic iteration count from any
   hints (quota sizes, batch sizes, typical yields), not the worst case.
+- **Steps that repeat per item MUST declare `iterations`.** A "process
+  each row" step costs its per-row turns *times the row count* — this
+  is almost always the dominant term, and flattening it understates the
+  whole run by 5–20×. Put the per-iteration turns in `estimated_turns`
+  and the realistic item-count range in `iterations` (page sizes,
+  pagination labels, batch quotas, and filter windows in the skill text
+  are your evidence). The loader multiplies them; never pre-multiply.
 - **Include the overhead the prose hides.** Reading reference files,
   re-checking rubric sections, correcting malformed tool calls — a
   realistic agent spends turns on these. A step whose happy path is 2
@@ -54,9 +61,14 @@ steps:
     phase: "1"
     estimated_turns: {low: 1, high: 2}
     estimated_tool_calls: {low: 4, high: 4}
-totals:                             # optional — omit if the sum is right
-  low: 28
-  high: 45
+  - description: "Push each eligible invoice and capture its sent date"
+    node_id: process_invoices_loop
+    phase: "Processing"
+    estimated_turns: {low: 3, high: 6}      # PER ROW —
+    iterations: {low: 20, high: 90}         # — × realistic row count
+totals:                             # optional — omit if the sum is right;
+  low: 88                           # must be WHOLE-RUN (post-iteration)
+  high: 602                         # when any step declares iterations
 notes: >-
   Lead generation dominates: the loop re-queries ZoomInfo with adjusted
   filters until the quota is met; typical campaigns converge in 3-5
@@ -72,30 +84,39 @@ Field reference:
 | `steps[].description` | yes | The step, in the skill's own vocabulary |
 | `steps[].node_id` | no | IR node id, only when the mapping is clean 1:1 |
 | `steps[].phase` | no | Source skill phase, same convention as the IR |
-| `steps[].estimated_turns` | yes | `{low, high}` agent turns |
+| `steps[].estimated_turns` | yes | `{low, high}` agent turns (per iteration when `iterations` is set) |
 | `steps[].estimated_tool_calls` | no | `{low, high}` tool calls, when distinct from turns |
-| `totals` | no | Whole-run `{low, high}`; omit to mean "sum the steps" |
+| `steps[].iterations` | when the step repeats | `{low, high}` repeats per run (rows, pages, items); whole-run cost = turns × iterations |
+| `totals` | no | Whole-run `{low, high}`; omit to mean "sum the steps (× iterations)" |
 | `notes` | no | The one paragraph a reader needs to trust the numbers |
 
 Validated by `rote.eval.sidecar.EvalEstimates` — if you can run Python,
 `load_eval_estimates("eval.yaml")` is the dry check, same pattern as
 `load_pipeline`.
 
-## Calibration anchors (BDR reference points)
-
-From real runs of BDR-scale skills (7 phases, ~20 distinct steps,
-heavy tool use):
-
-- Whole-run turn counts landed in the **30–57 turn** range.
-- Wall clock was **~13 seconds per turn** including tool execution.
-- A single fixed API call step: 1–2 turns. A batch-and-review step:
-  2–4. A bounded search loop: 6–15. A genuinely open research step:
-  4–10.
-
-If your step estimates sum to something wildly outside the anchor range
-for a comparably sized skill, re-examine before writing — either the
-skill really is bigger/smaller (fine, say so in `notes`) or a step
-estimate is off.
+## Calibration anchors (measured production runs)
+
+Whole-run turn counts are regime-dependent — anchor to the skill's
+*shape*, not to a universal range:
+
+- **Sequential tool-heavy skills** (BDR-scale: 7 phases, ~20 distinct
+  steps, no per-item loop): **30–57 turns** measured. ~13 seconds per
+  turn including tool execution.
+- **Per-item loop skills** (browser automation over a table, per-record
+  processing): measured production runs landed at **184 and 730 turns**
+  — the loop multiplier dominates everything else in the file. If a
+  skill says "for each row…", expect hundreds of turns, not tens, and
+  express it via `iterations`, never by inflating per-step turns.
+- Per-step anchors: a single fixed API call step: 1–2 turns. A
+  batch-and-review step: 2–4. A bounded search loop: 6–15. A genuinely
+  open research step: 4–10. One iteration of a per-row browser cycle
+  (locate, act, confirm, refresh): 2–6.
+
+If your estimate lands wildly outside the anchor for the skill's shape,
+re-examine before writing — either the skill really is bigger/smaller
+(fine, say so in `notes`) or a step estimate is off. A per-item skill
+whose whole-run total sums to under ~100 turns almost certainly has a
+missing `iterations` block.
 
 ## What NOT to do
 

{rote_cli-0.6.0 → rote_cli-0.8.0}/src/rote/__init__.py

@@ -1,3 +1,3 @@
 """rote — graduate fuzzy AI skills into deterministic workflows."""
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"

{rote_cli-0.6.0 → rote_cli-0.8.0}/src/rote/adapters/_common.py

@@ -223,13 +223,17 @@ def _pipeline_hash(pipeline: Pipeline) -> str:
     # Hash the full validated contents: node wiring, inputs, retries, and
     # edges all participate, so any regeneration that changes behavior gets
     # a new workflow type — name/version/counts alone miss rewires.
-    # Provenance (``Node.source``) is excluded: it's tooling metadata, and
-    # annotating where a node came from must not re-version in-flight
-    # workflows whose behavior didn't change.
+    # Provenance is excluded — it's tooling metadata, and annotating where
+    # a pipeline came from must not re-version in-flight workflows whose
+    # behavior didn't change. That covers ``Node.source`` (which SKILL.md
+    # section produced a node) and ``source_skill`` (where the skill bundle
+    # lived): the latter is a filesystem path the graduator re-points per
+    # output location, so hashing it would mint a new workflow type on
+    # every re-graduation to a different directory.
     payload = pipeline.model_dump_json(
         by_alias=True,
         exclude_none=True,
-        exclude={"nodes": {"__all__": {"source"}}},
+        exclude={"source_skill": True, "nodes": {"__all__": {"source"}}},
     )
     return hashlib.sha256(payload.encode()).hexdigest()[:8]