utterplan 0.6.1__tar.gz → 0.6.3__tar.gz

utterplan-0.6.3/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+<!-- Generated by memoryledger. Do not edit directly. -->
+<!-- Source: memoryledger records; regenerate with `memoryledger render` and `memoryledger export`. -->
+
+## Project memory policy
+
+This file contains reviewed long-term project memory.
+
+## Rules
+
+- UtterPlan is engine-independent. Core code must not import PyKokoro, PiperSynth, kokorog2p, piperg2p, ONNX Runtime, audio packages, or any consumer package.
+- UtterPlan ends before G2P. Engine/model selection, synthesis, and audio composition happen downstream.
+- `.utterplan.toml` schema v7 is the current inter-package contract; schema-v5/v6 TOML and historical JSON schemas v1–v4 remain sequential migration inputs only, and only the current schema version is natively supported.
+- Python objects may not contain semantic state that cannot survive file roundtrip.
+- Public FlowPlan objects contain no phonemes, model token IDs, models, sessions, or audio; completed plans must not retain spaCy or provider documents.
+- Every offset has a documented coordinate space.
+- Default planning is deterministic; the same source and configuration always produce the same executable plan and `plan_id`.
+- Schema changes require explicit compatibility review, frozen historical fixture coverage, deterministic migration tests, and package artifact checks.
+- Released schema files are immutable and retained under versioned paths; schemas v5, v6, and v7 have no JSON Schema resources.
+- Every supported older schema must retain a sequential migration path to current (v1 through v6 feed v7).
+- Migrations operate on serialized plain data and may not call parser, planner, G2P, renderer, or audio stages.
+- Package version and schema version remain independent. Migration preserves a compiled plan; replanning is a separate operation.
+- Optional compiler traces are sidecars; they must never alter executable plan content or identity.
+- UtterPlan parses SSMD 0.9 only; it does not parse SSMD 0.8 or migrate source documents (`ssmd migrate` owns that).
+- Book commands (`compile-book`, `render-book`) read the SSMDBook manifest only for chapter discovery, never modify the manifest or source chapters, write derived plans to separate directories, and never build book-level combined plans.
+- RenderPlan projection is optional: VoiceRender creates and validates engine-backed RenderProfiles, while UtterPlan projects stored schema-v7 FlowPlans into profile-specific RenderPlans (with `renderplan-set.toml` and reports) and performs deterministic replan refinement only.
+- UtterPlan depends directly on SSMD, PhraseSplit, TTSReady, and the renderplan contract package only; production code does not import Spokenform, and spaCy stays optional best-effort enrichment.
+- Repository tests must be self-contained and must not require sibling consumer checkouts; consumer-specific compatibility testing belongs in the consumer repository.

{utterplan-0.6.1 → utterplan-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.1
+Version: 0.6.3
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -353,6 +353,41 @@ creates or refreshes engine-backed profiles, then preflights and renders the
 resulting RenderPlans. The single-file `utterplan render-plan` command remains the
 low-level projection and deterministic replan primitive.
 
+When VoiceRender reports `preflight.replan`, use the new `replan-book` command to
+refine the exact active chapter plan. The operation reads the RenderProfile snapshot
+from the selected variant, writes a fingerprinted child RenderPlan, and updates only
+that chapter's active set entry. It does not replace the parent plan or rerun initial
+projection:
+
+```bash
+# VoiceRender measures the active plans; suppose chapter 5 returns preflight.replan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+utterplan replan-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5
+
+# Measure/render the newly active child. Repeat these last two commands if it
+# still reports preflight.replan; each cycle must use feedback for the active plan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+Use the exact variant directory name (including its profile fingerprint). `replan-book`
+searches `preflight-recheck.toml` before `preflight.toml` and refuses stale feedback,
+so a report for a parent can never be applied to its child. The single-file
+`render-plan --previous ... --preflight ...` operation remains available for
+low-level replanning.
+
+This orchestration does not add a splitter, renderer-specific capacity estimate, or
+engine dependency. VoiceRender supplies preflight measurements and remains responsible
+for synthesis and audio composition.
+
 Related packages: [RenderPlan](https://pypi.org/project/renderplan/) defines the
 shared profile and plan contracts; [VoiceRender](https://pypi.org/project/voicerender/)
 creates engine-backed profiles and performs preflight and synthesis.

{utterplan-0.6.1 → utterplan-0.6.3}/README.md

@@ -109,6 +109,41 @@ creates or refreshes engine-backed profiles, then preflights and renders the
 resulting RenderPlans. The single-file `utterplan render-plan` command remains the
 low-level projection and deterministic replan primitive.
 
+When VoiceRender reports `preflight.replan`, use the new `replan-book` command to
+refine the exact active chapter plan. The operation reads the RenderProfile snapshot
+from the selected variant, writes a fingerprinted child RenderPlan, and updates only
+that chapter's active set entry. It does not replace the parent plan or rerun initial
+projection:
+
+```bash
+# VoiceRender measures the active plans; suppose chapter 5 returns preflight.replan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+utterplan replan-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5
+
+# Measure/render the newly active child. Repeat these last two commands if it
+# still reports preflight.replan; each cycle must use feedback for the active plan.
+voicerender render-book . \
+  --variant narration4--28f616b6fe3b \
+  --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+Use the exact variant directory name (including its profile fingerprint). `replan-book`
+searches `preflight-recheck.toml` before `preflight.toml` and refuses stale feedback,
+so a report for a parent can never be applied to its child. The single-file
+`render-plan --previous ... --preflight ...` operation remains available for
+low-level replanning.
+
+This orchestration does not add a splitter, renderer-specific capacity estimate, or
+engine dependency. VoiceRender supplies preflight measurements and remains responsible
+for synthesis and audio composition.
+
 Related packages: [RenderPlan](https://pypi.org/project/renderplan/) defines the
 shared profile and plan contracts; [VoiceRender](https://pypi.org/project/voicerender/)
 creates engine-backed profiles and performs preflight and synthesis.

{utterplan-0.6.1 → utterplan-0.6.3}/docs/changelog.md

@@ -4,6 +4,30 @@
 
 ## [Unreleased]
 
+## [v0.6.3] - Unreleased
+
+### Added
+
+- Added replan-book to refine active book RenderPlans from matching VoiceRender preflight feedback
+
+<!-- generated by releaseledger -->
+
+## [v0.6.2] - 2026-10-14
+
+### Added
+
+- Added public book compilation and RenderPlan projection services with safe chapter selection and per-chapter reporting
+
+<!-- generated by releaseledger -->
+
+## [0.6.1] - 2026-10-13
+
+### Documentation
+
+- Documented the arc42 system architecture, structure, and boundaries
+
+<!-- generated by releaseledger -->
+
 ## [v0.6.0] - 2026-10-13
 
 ### Added

{utterplan-0.6.1 → utterplan-0.6.3}/docs/cli.md

@@ -205,6 +205,76 @@ are rejected before chapter processing. Exit status is 0 when all selected
 chapters succeed, 1 when any chapter fails, and 2 for usage or shared-configuration
 errors. See the [SSMDBook workflow guide](ssmdbook.md) for end-to-end and multi-voice examples.
 
+## Replan active RenderPlans for selected chapters
+
+`replan-book` is the book/variant orchestration for VoiceRender's capacity feedback.
+It loads the profile snapshot owned by the existing RenderPlanSet; callers must select
+the exact variant directory, not supply another profile:
+
+VoiceRender supplies capacity feedback: UtterPlan does not add renderer-specific
+metrics, a splitter, engine selection, synthesis, or audio composition.
+
+```text
+utterplan replan-book INPUT --variant VARIANT [--chapters SELECTOR]
+  [--renderplan-root PATH] [--voicerender-root PATH] [--report PATH]
+  [--dry-run] [--fail-fast] [--explain] [--json]
+```
+
+Example repeatable lifecycle:
+
+```bash
+# Initial projection and exact renderer preflight/render
+utterplan render-book . --profile narration4.renderprofile.toml --variant narration4 --chapters 5
+voicerender render-book . --variant narration4--28f616b6fe3b --chapters 5 \
+  --emphasis-policy defer-to-compose
+
+# If VoiceRender returns preflight.replan, refine only the active chapter plan
+utterplan replan-book . --variant narration4--28f616b6fe3b --chapters 5
+
+# Preflight/render the new active plan; repeat replan-book and this command if needed
+voicerender render-book . --variant narration4--28f616b6fe3b --chapters 5 \
+  --emphasis-policy defer-to-compose
+```
+
+`INPUT` is an SSMDBook root or its canonical `chapters/` directory. Chapter selectors
+use manifest source numbers and retain manifest order. The default RenderPlan root is
+`<book-root>/renderplan`; the default VoiceRender root is `<book-root>/voicerender`.
+The command reads `<variant>/renderprofile.toml` and the selected active plan paths
+from `renderplan-set.toml`. It discovers reports under
+`<voicerender-root>/<variant>/<chapter-id>/`, preferring `preflight-recheck.toml`
+over `preflight.toml` when both fully validate against the exact active RenderPlan.
+
+Only a matching `status="replan"` report is accepted. Missing reports, stale parent
+reports, mismatched profile/plan identities, and `ok`/`reject` statuses fail that
+chapter; the command never falls back to an initial RenderPlan projection. A successful
+replan writes a deterministic immutable child plan first, then atomically changes only
+the selected chapter's active set entry. Parent plans, source UtterPlans, profile
+identity, and unselected set entries remain unchanged. Run VoiceRender again after
+each replan; repeat the two feedback steps until preflight is `ok`.
+
+Defaults and behavior:
+
+- `--variant` is required and must name the existing full variant directory, including
+  its profile fingerprint. The profile snapshot is loaded from that collection.
+- `--chapters`: `all`, one source number, an inclusive range, or comma-separated
+  selections; default is `all`.
+- `--renderplan-root` and `--voicerender-root` override the collection/data roots,
+  not the selected variant or chapter paths recorded by the contracts.
+- `--report`: defaults to `<variant-dir>/replan-report.toml`; progress is persisted
+  after each chapter and the final report is marked complete.
+- `--dry-run`: validates and plans children without writing child RenderPlans or
+  changing the set index. It writes the operational report and reports successful
+  items as `planned`.
+- `--fail-fast`: later chapters are recorded as skipped after the first failure;
+  without it, later selected chapters continue.
+- `--explain` uses the existing per-request RenderPlan explanation; `--json` emits
+  structured outcome paths, identities, replacement counts, errors, and optional
+  explanations.
+
+Re-running with a stale report after activating a child fails with
+`renderplan.replan.book.preflight_stale`. VoiceRender must first measure the active
+child to produce its own matching feedback report.
+
 ## Explain a plan
 
 Explain an existing compiled plan as a human-readable speech narrative:

{utterplan-0.6.1 → utterplan-0.6.3}/docs/python-api.md

@@ -187,6 +187,28 @@ from utterplan.renderplan_batch import RenderRequest, new_renderplan_set, render
 
 `render_to_files()` projects schema-v7 `FlowPlan` inputs; grouping, source mapping, export, and replan logic remain UtterPlan-owned.
 
+## Public SSMDBook services
+
+`compile_book()` and `render_book()` are the public Python counterparts of the `compile-book` and `render-book` commands. They take paths and keyword options directly; callers do not construct `argparse.Namespace`, spawn a subprocess, or reproduce chapter selection, path safety, variant naming, snapshot/set initialization, or report logic. The CLI delegates to these same services.
+
+```python
+from utterplan import compile_book, render_book
+
+compiled = compile_book(".", chapters="5-17")
+projected = render_book(
+    ".",
+    profile="narration.renderprofile.toml",
+    chapters="5-17",
+)
+
+assert compiled.exit_code == projected.exit_code == 0
+print(projected.variant)  # resolved <label>--<profile fingerprint>
+```
+
+`BookCompileRequest` / `BookRenderRequest` are immutable option records. Their corresponding result records expose the workspace, selector, selected chapter IDs, artifact and report paths, per-chapter outcomes, `failed`, and `exit_code`; the render result also includes `profile_id`, `variant`, `variant_dir`, snapshot, and set paths. `variant` is authoritative: do not duplicate the label normalization or profile fingerprint algorithm downstream.
+
+Optional `on_progress` callbacks receive the existing `CompileOutcome` or `RenderOutcome` for each chapter. Optional `on_start` callbacks receive a resolved book-start record before batch processing. Services do not print. They preserve schema-v7 output and CLI filesystem/report behavior; workspace/path safety errors raise `BookServiceError`, and chapter-level failures are returned as outcomes. Pass `language=` to provide the fallback/required-language override, or supply a `PlannerConfig` with `planner_config=`. See the [SSMDBook guide](ssmdbook) for layouts, safety rules, and CLI/Python examples.
+
 ## Planner progress callbacks
 
 `UtterancePlanner.plan`, `UtterancePlanner.compile`, and `compile_document` accept an optional keyword-only `on_progress` callback. It receives typed `PlannerProgressEvent` objects synchronously in the planner thread. Progress is operational only: it is not added to `PlannerConfig` or the plan, and enabling a callback does not change plan identity or serialization.

{utterplan-0.6.1 → utterplan-0.6.3}/docs/ssmdbook.md

@@ -137,3 +137,33 @@ the collection's snapshot remains available for inspection and reproducible
 replanning. See the [CLI reference](cli.md#produce-renderplans-for-selected-ssmdbook-chapters),
 [RenderPlan](https://pypi.org/project/renderplan/), and
 [VoiceRender](https://pypi.org/project/voicerender/).
+
+## Python API for SSMDBook workspaces
+
+The Python API and CLI share the same book orchestration and artifact layout. The public services read the manifest for chapter discovery, select by original `source_number`, validate safe workspace paths, and write the same reports and per-chapter plans as the commands above. They do not print to the console or retain CLI argument objects.
+
+CLI:
+
+```bash
+utterplan compile-book . --chapters 5-17
+utterplan render-book . --profile narration.renderprofile.toml --chapters 5-17
+```
+
+Equivalent Python:
+
+```python
+from utterplan import compile_book, render_book
+
+compiled = compile_book(".", chapters="5-17")
+projected = render_book(
+    ".",
+    profile="narration.renderprofile.toml",
+    chapters="5-17",
+)
+
+print(projected.variant)  # exact profile-specific RenderPlan directory name
+```
+
+`BookCompileResult` and `BookRenderResult` expose the resolved workspace, selector, selected chapter IDs, artifact/report paths, per-chapter outcomes, `failed`, and `exit_code`. `BookRenderResult.variant` is the final sanitized label plus profile fingerprint; consumers should use it rather than reproduce the naming algorithm. Optional `on_progress` callbacks receive each compile or projection outcome, and `on_start` callbacks receive resolved selection and output metadata. A chapter must declare its language unless `language=` is explicitly supplied to `compile_book()`; compiler behavior can otherwise be configured with `planner_config=`. Invalid workspaces and unsafe paths raise `BookServiceError`, while ordinary per-chapter failures are represented in outcomes.
+
+The public request models `BookCompileRequest` and `BookRenderRequest` capture the corresponding service options. These APIs remain engine-independent: they neither inspect TTS engines nor synthesize or compose audio.