utterplan 0.4.0__tar.gz → 0.4.1__tar.gz

{utterplan-0.4.0 → utterplan-0.4.1}/.github/workflows/tests.yml

@@ -53,6 +53,8 @@ jobs:
             "typing_extensions==4.0.0" \
             "tomlkit==0.13.0"
           python -m pip install --no-deps -e .
+      - name: Verify SSMD 0.9.3 front-matter scene-break handling
+        run: python -m pytest -q tests/test_ssmd_09_parser.py -k front_matter_scene_break
       - name: Run lower-bound tests
         run: python -m pytest -q
 

{utterplan-0.4.0 → utterplan-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.4.0
+Version: 0.4.1
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -293,9 +293,14 @@ utterplan validate chapter.utterplan.toml
 utterplan inspect chapter.utterplan.toml --segment 0
 utterplan inspect chapter.utterplan.toml --semantic-boundaries
 utterplan explain chapter.utterplan.toml
+utterplan inspect-attempt chapter.attempt.toml --issues
 ```
 
 `explain` presents the compiled plan as a human-readable speech plan, while `inspect` exposes lower-level diagnostic fields.
+
+`inspect-attempt` reads the separate `utterplan.planning-attempt.v1` TOML artifact,
+not a canonical plan. Use it to review renderability issues and safe repair
+assessments on blocked planning outcomes; such candidates remain inspect-only drafts.
 Canonical plan output is TOML (`.utterplan.toml`) and is written to stdout when no output file is supplied. Status messages use stderr, and existing output files require `--force`. Safe punctuation repair is the default; use `--renderability strict` to reject every repair opportunity.
 
 ## SSMD source contract

{utterplan-0.4.0 → utterplan-0.4.1}/README.md

@@ -50,9 +50,14 @@ utterplan validate chapter.utterplan.toml
 utterplan inspect chapter.utterplan.toml --segment 0
 utterplan inspect chapter.utterplan.toml --semantic-boundaries
 utterplan explain chapter.utterplan.toml
+utterplan inspect-attempt chapter.attempt.toml --issues
 ```
 
 `explain` presents the compiled plan as a human-readable speech plan, while `inspect` exposes lower-level diagnostic fields.
+
+`inspect-attempt` reads the separate `utterplan.planning-attempt.v1` TOML artifact,
+not a canonical plan. Use it to review renderability issues and safe repair
+assessments on blocked planning outcomes; such candidates remain inspect-only drafts.
 Canonical plan output is TOML (`.utterplan.toml`) and is written to stdout when no output file is supplied. Status messages use stderr, and existing output files require `--force`. Safe punctuation repair is the default; use `--renderability strict` to reject every repair opportunity.
 
 ## SSMD source contract

{utterplan-0.4.0 → utterplan-0.4.1}/docs/changelog.md

@@ -4,6 +4,26 @@
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-07
+
+### Added
+
+- Added persistable planning attempts with inspectable renderability outcomes and safe repair assessments
+
+### Changed
+
+- Changed planning APIs to expose blocked candidates without weakening canonical plan validation
+
+### Fixed
+
+- Fixed legacy SSMD scene breaks to preserve front-matter boundaries and clean-to-source offsets
+
+### Documentation
+
+- Documented planning-attempt artifacts, inspection workflows, and renderability guarantees
+
+<!-- generated by releaseledger -->
+
 ## [0.4.0] - 2026-10-06
 
 ### Added

{utterplan-0.4.0 → utterplan-0.4.1}/docs/cli.md

@@ -100,6 +100,24 @@ utterplan explain chapter.utterplan.toml --details
 
 The default output shows prepared wording, render units, ordered segments, languages, resolved pauses, headings, SSMD version/title/document language, effective typed directives, metadata, and warning/error codes with source locations. Add `--details` for IDs, offsets, provenance, hashes, plan identity, and token analysis beneath each segment. Use `inspect --tokens` for a compact token/provenance view.
 
+## Inspect a persisted planning attempt
+
+`inspect` reads canonical plans. Persistable planning outcomes use the separate
+`utterplan.planning-attempt.v1` artifact and are opened with `inspect-attempt`:
+
+```bash
+utterplan inspect-attempt chapter.attempt.toml
+utterplan inspect-attempt chapter.attempt.toml --issues
+utterplan inspect-attempt chapter.attempt.toml --segment seg-000001 --unit unit-000001
+utterplan inspect-attempt chapter.attempt.toml --json
+```
+
+The default view summarizes status, renderability, and candidate size. `--issues`
+shows source context and conservative repair assessments; segment and unit selectors
+accept an ID or zero-based index. `--json` emits the complete artifact as JSON for
+inspection, but the persisted attempt itself remains TOML. A blocked candidate is an
+inspect-only draft, not a canonical plan, and is rejected by `UtterancePlan.load()`.
+
 ## Planning controls
 
 - `--unit paragraph|sentence` chooses render-unit grouping.
@@ -126,6 +144,7 @@ utterplan inspect chapter.utterplan.toml --segment 0
 utterplan inspect chapter.utterplan.toml --unit 0 --boundaries --tokens
 utterplan inspect chapter.utterplan.toml --preparation
 utterplan inspect chapter.utterplan.toml --semantic-boundaries
+utterplan inspect-attempt chapter.attempt.toml --issues
 ```
 
 `inspect --preparation` reports the preparation backend and version, structural and spoken text lengths, replacement count, and each replacement's structural and spoken ranges and text. This is the supported human-facing preparation diagnostic; raw coordinate lookup tables are intentionally absent from the persisted TOML plan.

{utterplan-0.4.0 → utterplan-0.4.1}/docs/python-api.md

@@ -41,6 +41,47 @@ the plan, is not renderer input, and does not change `plan.plan_id`. Its source
 ranges index SSMD-clean structural text; transformation output ranges index prepared
 spoken text, using Python string character offsets.
 
+## Persistable planning attempts
+
+`compile_attempt` and `UtterancePlanner.compile_attempt` expose a finalized planning
+outcome without raising solely because a segment is not renderable. They still raise
+for input, configuration, and planning failures. The existing `compile_document`,
+`UtterancePlanner.compile`, and `plan` APIs remain strict and continue raising
+`PlanRenderabilityError` when renderability blocks completion.
+
+Attempts are separate from canonical plans. A blocked attempt retains an inspect-only
+candidate draft; it is not a valid `UtterancePlan` and cannot be loaded by
+`UtterancePlan.load()`. Persist it with `PlanningAttempt.save()` and restore it with
+`PlanningAttempt.load()`; the attempt TOML schema is
+`utterplan.planning-attempt.v1`, independent of canonical plan schema v4.
+
+```python
+from utterplan import PlannerConfig, compile_attempt
+
+attempt = compile_attempt(
+    "Hello.\n\n.\n\nWorld.",
+    input_format="plain",
+    config=PlannerConfig(
+        language="en-us",
+        renderability_mode="strict",
+    ),
+)
+assert attempt.status == "blocked"
+attempt.save("chapter.attempt.toml")
+
+for issue in attempt.renderability.issues:
+    assessment = issue.repair_assessment
+    if assessment is not None:
+        print(issue.segment_id, assessment.safe, assessment.action)
+        print(assessment.blockers)
+```
+
+Repair assessments report the existing conservative options; they do not rewrite
+text speculatively. In repair mode, only the planner's established safe repairs are
+applied. `utterplan inspect-attempt chapter.attempt.toml --issues` shows issues,
+source locations, and repair assessments; `--segment` and `--unit` select candidate
+topology, and `--json` emits the complete attempt as JSON for inspection.
+
 ## TOML persistence
 
 Schema v4 remains the semantic contract, while `.utterplan.toml` is the canonical persisted format. `to_toml()` and `from_toml()` round-trip the complete plan; `save()` writes atomically, and `load()` accepts TOML only. Normal loading does not auto-detect or fall back to JSON.

{utterplan-0.4.0 → utterplan-0.4.1}/tests/test_cli.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import pytest
 
-from utterplan import PlannerConfig, UtterancePlan, UtterancePlanner
+from utterplan import PlannerConfig, UtterancePlan, UtterancePlanner, compile_attempt
 from utterplan.cli import build_parser, main
 
 
@@ -466,3 +466,61 @@ def test_validate_source_documents_and_preserve_saved_plan_validation(
     assert "plain input requires --language" in capsys.readouterr().err
     assert main(["validate", str(plain), "--input-format", "plain", "--language", "en-us"]) == 0
     assert "valid" in capsys.readouterr().out
+
+
+def _save_blocked_attempt(tmp_path: Path):
+    config = PlannerConfig(
+        language="en-us",
+        document_format="plain",
+        text_preparation="identity",
+        renderability_mode="strict",
+    )
+    attempt = compile_attempt("Hello.\n\n.\n\nWorld.", input_format="plain", config=config)
+    path = tmp_path / "blocked.attempt.toml"
+    attempt.save(path)
+    return attempt, path
+
+
+def test_inspect_attempt_reports_issues_segment_and_unit(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    attempt, path = _save_blocked_attempt(tmp_path)
+    issue_segment = attempt.renderability.issues[0].segment_id
+    unit = attempt.candidate.units[0]
+
+    assert (
+        main(
+            [
+                "inspect-attempt",
+                str(path),
+                "--issues",
+                "--segment",
+                issue_segment,
+                "--unit",
+                unit.id,
+            ]
+        )
+        == 0
+    )
+    output = capsys.readouterr().out
+    assert "status:        blocked" in output
+    assert "renderability: blocked (strict)" in output
+    assert "renderability.punctuation_only" in output
+    assert "safe: true" in output
+    assert f"Segment {issue_segment}" in output
+    assert f"Unit {unit.id}" in output
+
+
+def test_inspect_attempt_json_exposes_separate_artifact_schema(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    attempt, path = _save_blocked_attempt(tmp_path)
+
+    assert main(["inspect-attempt", str(path), "--json"]) == 0
+    output = capsys.readouterr().out
+    payload = json.loads(output)
+    assert payload["schema"] == "utterplan.planning-attempt.v1"
+    assert payload["attempt"]["status"] == "blocked"
+    assert payload["candidate"]["segments"]
+    assert payload["renderability"]["issues"]
+    assert payload["attempt"]["attempt_id"] == attempt.attempt_id

{utterplan-0.4.0 → utterplan-0.4.1}/tests/test_renderability_repair.py

@@ -8,14 +8,17 @@ from utterplan import (
     AnnotationSpan,
     BoundaryEvent,
     EmphasisDirective,
+    PlanFormatError,
     PlannerConfig,
     PlanRenderabilityError,
     PlanSegment,
     SegmentDirectives,
     SemanticBoundary,
+    UtterancePlan,
     UtterancePlanner,
     assess_renderability_repair,
     classify_segment,
+    compile_attempt,
 )
 from utterplan.config import PauseConfig
 from utterplan.planner import _repair_renderer_segments
@@ -327,3 +330,107 @@ def test_symbol_only_content_fails_without_a_guessed_repair() -> None:
         assert issue.repair_assessment.safe is False
         assert "will not guess" in str(error.value)
         assert error.value.mode == mode
+
+
+def test_strict_attempt_retains_blocked_candidate_and_compile_still_raises() -> None:
+    source = "Hello.\n\n.\n\nWorld."
+    config = PlannerConfig(
+        language="en-US",
+        text_preparation="identity",
+        renderability_mode="strict",
+    )
+    planner = UtterancePlanner(config)
+
+    attempt = planner.compile_attempt(source)
+    functional = compile_attempt(source, input_format="plain", config=config)
+    assert functional.status == "blocked"
+
+    assert attempt.status == "blocked"
+    assert not attempt.ok
+    assert attempt.renderability.issues
+    issue = attempt.renderability.issues[0]
+    segment = next(item for item in attempt.candidate.segments if item.id == issue.segment_id)
+    assert segment.text == issue.text == "."
+    assert issue.source_start is not None
+    assert issue.source_end is not None
+    assert source[issue.source_start : issue.source_end] == issue.text
+    assert attempt.candidate.plan_id == ""
+    with pytest.raises(ValueError, match="blocked planning-attempt draft"):
+        attempt.candidate.to_plan()
+
+    with pytest.raises(PlanRenderabilityError) as error:
+        planner.compile(source)
+    assert error.value.mode == "strict"
+    assert error.value.issues == attempt.renderability.issues
+
+
+def test_safe_repair_attempt_returns_a_canonical_plan() -> None:
+    config = PlannerConfig(language="en-US", text_preparation="identity")
+    attempt = UtterancePlanner(config).compile_attempt("Hello.\n\n.\n\nWorld.")
+
+    assert attempt.status == "repaired"
+    assert attempt.ok
+    assert len(attempt.repairs) == 1
+    assert attempt.repairs[0].repair_assessment is not None
+    assert attempt.repairs[0].repair_assessment.safe
+    plan = attempt.candidate.to_plan()
+    plan.validate()
+    assert [segment.text for segment in plan.segments] == ["Hello.", "World."]
+
+
+def test_unsafe_repair_attempt_is_blocked_and_draft_structure_is_checked() -> None:
+    from utterplan.exceptions import PlanValidationError
+    from utterplan.model import validate_plan_structure
+
+    config = PlannerConfig(
+        language="en-US",
+        text_preparation="identity",
+        renderability_mode="repair",
+    )
+    attempt = UtterancePlanner(config).compile_attempt("€")
+
+    assert attempt.status == "blocked"
+    assert attempt.renderability.issues[0].repair_assessment is not None
+    assert not attempt.renderability.issues[0].repair_assessment.safe
+    with pytest.raises(ValueError, match="blocked planning-attempt draft"):
+        attempt.candidate.to_plan()
+
+    malformed = replace(
+        attempt.candidate._plan,
+        segments=(replace(attempt.candidate.segments[0], spoken_end=100),),
+    )
+    with pytest.raises(PlanValidationError, match="segment range"):
+        validate_plan_structure(malformed)
+
+
+@pytest.mark.parametrize(
+    ("source", "mode", "expected_status"),
+    [
+        ("Ready.", "strict", "renderable"),
+        ("Hello.\n\n.\n\nWorld.", "repair", "repaired"),
+        ("€", "strict", "blocked"),
+    ],
+)
+def test_planning_attempt_toml_roundtrips_all_outcomes_and_stays_noncanonical(
+    source: str, mode: str, expected_status: str
+) -> None:
+    config = PlannerConfig(
+        language="en-US",
+        text_preparation="identity",
+        renderability_mode=mode,
+    )
+    attempt = UtterancePlanner(config).compile_attempt(source)
+    repeated = UtterancePlanner(config).compile_attempt(source)
+    serialized = attempt.to_toml()
+    restored = type(attempt).from_toml(serialized)
+
+    assert attempt.status == expected_status
+    assert repeated.attempt_id == attempt.attempt_id
+    assert restored == attempt
+    assert restored.to_toml() == serialized
+    assert restored.to_dict() == attempt.to_dict()
+    assert 'schema = "utterplan.planning-attempt.v1"' in serialized
+    with pytest.raises(PlanFormatError):
+        UtterancePlan.from_toml(serialized)
+    with pytest.raises(PlanFormatError):
+        UtterancePlan.from_dict(attempt.to_dict())

{utterplan-0.4.0 → utterplan-0.4.1}/tests/test_ssmd_09_parser.py

@@ -39,6 +39,87 @@ def test_legacy_scene_break_is_structural_not_renderer_text() -> None:
     assert all(segment.text != "---" for segment in plan.segments)
 
 
+@pytest.mark.parametrize(
+    ("body", "scene_break_count"),
+    [
+        ("Before.\n\n---\n\nAfter.", 1),
+        ("Before.\n\n---\n\nMiddle.\n\n---\n\nAfter.", 2),
+        ("Before.\n\n...p\n\nAfter.", 1),
+        ("---\n\nAfter.\n\n---", 2),
+        ("Before --- after.", 0),
+        ("Before.\n\n\\---\n\nAfter.", 0),
+    ],
+)
+def test_front_matter_scene_breaks_are_boundaries_not_renderer_text(
+    body: str, scene_break_count: int
+) -> None:
+    source = f'---\nssmd_version: "0.9"\ntitle: Demo\n---\n{body}'
+    plan = _planner().plan(source)
+
+    scene_breaks = [
+        event
+        for event in plan.boundaries
+        if event.kind == "explicit"
+        and (
+            event.attrs.get("semantic") == "scene_break"
+            or event.attrs.get("legacy_horizontal_rule")
+            or (event.origin == "ssmd" and event.strength == "x-strong")
+        )
+    ]
+    assert len(scene_breaks) == scene_break_count
+    if scene_break_count:
+        assert "---" not in plan.texts.structural or body.startswith("---")
+        assert all(segment.text.strip() != "---" for segment in plan.segments)
+        assert plan.document_metadata["planning"]["renderability"]["guaranteed"] is True
+    elif "Before --- after." in body:
+        assert "Before --- after." in plan.texts.structural
+        assert any("---" in segment.text for segment in plan.segments)
+    elif "\\---" in body:
+        assert "---" in plan.texts.structural
+
+
+def test_legacy_parser_front_matter_scene_break_uses_clean_to_source_mapping(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import ssmd
+
+    from utterplan.parsers import SSMDDocumentParser, map_structural_span_to_source
+
+    header = '---\nssmd_version: "0.9"\ntitle: Demo\n---\n'
+    body = "Before.\n\n---\n\nAfter."
+    source = header + body
+    legacy_result = SimpleNamespace(
+        clean_text=body,
+        annotations=[],
+        events=[],
+        header={"ssmd_version": "0.9", "title": "Demo"},
+        warnings=[],
+        diagnostics=[],
+        text_spans=[
+            SimpleNamespace(
+                char_start=0,
+                char_end=len(body),
+                source_start=len(header),
+                source_end=len(source),
+            )
+        ],
+    )
+    monkeypatch.setattr(ssmd, "parse_structure", lambda *args, **kwargs: legacy_result)
+
+    parsed = SSMDDocumentParser().parse(source, _planner().config)
+    assert parsed.structural_text == "Before.\n\nAfter."
+    source_after = source.index("After.")
+    assert map_structural_span_to_source(
+        parsed, len("Before.\n\n"), len(parsed.structural_text)
+    ) == (source_after, source_after + len("After."))
+    scene = next(event for event in parsed.boundaries if event.attrs.get("legacy_horizontal_rule"))
+    assert scene.attrs["source_start"] == source.index("---", len(header))
+    assert scene.attrs["source_end"] == source_after
+
+    plan = _planner().plan(source)
+    assert [segment.text for segment in plan.segments] == ["Before.", "After."]
+
+
 def _planner() -> UtterancePlanner:
     return UtterancePlanner(
         PlannerConfig(

{utterplan-0.4.0 → utterplan-0.4.1}/utterplan/__init__.py

@@ -1,4 +1,5 @@
 from ._version import __version__
+from .attempts import PlanDraft, PlanningAttempt, PlanningAttemptStatus
 from .batch import BatchProgressCallback, CompileOutcome, CompileRequest, compile_to_files
 from .compiler import (
     CompileResult,
@@ -6,6 +7,7 @@ from .compiler import (
     PreparationChange,
     PreparationTrace,
     PreparationTraceUnit,
+    compile_attempt,
     compile_document,
 )
 from .config import (
@@ -89,6 +91,10 @@ __all__ = [
     "PreparationTrace",
     "PreparationTraceUnit",
     "compile_document",
+    "compile_attempt",
+    "PlanningAttempt",
+    "PlanningAttemptStatus",
+    "PlanDraft",
     "compile_to_files",
     "PlannerConfig",
     "PauseConfig",

{utterplan-0.4.0 → utterplan-0.4.1}/utterplan/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
-__commit_id__ = commit_id = 'gc73c43017'
+__commit_id__ = commit_id = 'g293fe7cd5'