utterplan 0.3.3__tar.gz → 0.3.4__tar.gz

{utterplan-0.3.3 → utterplan-0.3.4}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -60,3 +60,7 @@
 {"data":{"updated_rows":2},"event":"audit.updated","event_id":"event-0060","record_revisions":{"commit_audit_sheet":2},"release_version":"0.3.3","schema_version":2}
 {"data":{"entry_ids":["entry-0001","entry-0002"],"synced_audit_rows":2},"event":"entry.batch_added","event_id":"event-0061","record_revisions":{"commit_audit_sheet":3,"entry:0.3.3/entry-0001":1,"entry:0.3.3/entry-0002":1,"release:0.3.3":3},"release_version":"0.3.3","schema_version":2}
 {"data":{"released_at":"2026-10-03"},"event":"release.finalized","event_id":"event-0062","record_revisions":{"release:0.3.3":4},"release_version":"0.3.3","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0063","record_revisions":{"release:0.3.4":1},"release_version":"0.3.4","schema_version":2}
+{"data":{"fields":["git_base_ref","git_base_sha","git_commit_count","git_head_ref","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0064","record_revisions":{"release:0.3.4":2},"release_version":"0.3.4","schema_version":2}
+{"data":{"row_count":0},"event":"audit.created","event_id":"event-0065","record_revisions":{"commit_audit_sheet":1},"release_version":"0.3.4","schema_version":2}
+{"data":{"kind":"added","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0066","record_revisions":{"entry:0.3.4/entry-0001":1,"release:0.3.4":3},"release_version":"0.3.4","schema_version":2}

utterplan-0.3.4/.ledger/releaseledger/data/ledgers/main/releases/0.3.4/audit/commit-audit.yaml

@@ -0,0 +1,13 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 1
+release_version: 0.3.4
+git_base_ref: v0.3.3
+git_base_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_ref: HEAD
+git_head_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_range: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158..0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+commit_count: 0
+rows: []

utterplan-0.3.4/.ledger/releaseledger/data/ledgers/main/releases/0.3.4/entries/entry-0001.md

@@ -0,0 +1,34 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: 0.3.4
+kind: added
+summary: Added typed planner progress events and reused unchanged linguistic analyses
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - tl:task-0021
+paths:
+  - utterplan/progress.py
+  - utterplan/planner.py
+  - utterplan/linguistics.py
+  - utterplan/compiler.py
+  - tests/test_progress.py
+  - tests/test_linguistics.py
+  - docs/python-api.md
+  - README.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---
+
+The optional synchronous callback reports planner phases, provider runs, and actual spaCy model loads without changing plan serialization; equivalent analyses are reused where safe.

utterplan-0.3.4/.ledger/releaseledger/data/ledgers/main/releases/0.3.4/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 3
+version: 0.3.4
+status: planned
+history_state: curated
+title: null
+released_at: null
+previous_version: 0.3.3
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 1
+artifact_count: 0
+git_base_ref: v0.3.3
+git_base_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_ref: HEAD
+git_head_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_range: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158..0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_commit_count: 0
+---

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/audit-decisions.yaml

@@ -0,0 +1 @@
+rows: []

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/audit.yaml

@@ -0,0 +1,13 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 1
+release_version: 0.3.4
+git_base_ref: v0.3.3
+git_base_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_ref: HEAD
+git_head_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_range: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158..0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+commit_count: 0
+rows: []

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/entries.preview.yaml

@@ -0,0 +1,11 @@
+schema: releaseledger.entry-batch.v1
+operation: create
+schema_version: 1
+object_type: release_entry_batch
+release_version: 0.3.4
+git_base_ref: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_base_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_ref: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+include_merges: nontrivial
+entries: []

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/entries.yaml

@@ -0,0 +1,11 @@
+schema: releaseledger.entry-batch.v1
+operation: create
+schema_version: 1
+object_type: release_entry_batch
+release_version: 0.3.4
+git_base_ref: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_base_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_ref: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+git_head_sha: 0e4e0751e2b8a5d5c0592a3efbda5a31f653c158
+include_merges: nontrivial
+entries: []

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/evidence/manifest.json

@@ -0,0 +1,12 @@
+{
+  "candidate_count": 0,
+  "candidates": [],
+  "git_base_ref": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "git_base_sha": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "git_head_ref": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "git_head_sha": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "include_merges": "nontrivial",
+  "object_type": "git_evidence_manifest",
+  "release_version": "0.3.4",
+  "schema_version": 1
+}

utterplan-0.3.4/.ledger/releaseledger/work/0.3.4/range.json

@@ -0,0 +1,13 @@
+{
+  "base_ref": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "base_sha": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "candidate_count": 0,
+  "commit_count": 0,
+  "head_ref": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "head_sha": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158",
+  "include_merges": "nontrivial",
+  "kind": "git_range_summary",
+  "merge_commit_count": 0,
+  "merge_commits_skipped": 0,
+  "range": "0e4e0751e2b8a5d5c0592a3efbda5a31f653c158..0e4e0751e2b8a5d5c0592a3efbda5a31f653c158"
+}

{utterplan-0.3.3 → utterplan-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.3.3
+Version: 0.3.4
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -343,6 +343,22 @@ identity. Plain text must be explicitly selected in Python and always requires a
 language fallback. Existing `UtterancePlanner.plan` remains supported and returns
 only the plan; JSON is the portable persistence and interchange format.
 
+For operational progress from a long-running Python plan, pass `on_progress` to
+`UtterancePlanner.plan`, `UtterancePlanner.compile`, or `compile_document`. The
+callback receives typed `PlannerProgressEvent` objects and does not change the plan:
+
+```python
+from utterplan import PlannerConfig, UtterancePlanner
+
+events = []
+plan = UtterancePlanner(PlannerConfig(language="en-us")).plan(
+    text,
+    on_progress=events.append,
+)
+```
+
+Callbacks run synchronously and exceptions propagate. See the [Python API guide](docs/python-api.md#planner-progress-callbacks) for event fields, model-load events, and reuse behavior.
+
 ## Renderer-consumer boundary
 
 Renderers consume `PlanSegment.text`, which is prepared/spoken text, and use

{utterplan-0.3.3 → utterplan-0.3.4}/README.md

@@ -101,6 +101,22 @@ identity. Plain text must be explicitly selected in Python and always requires a
 language fallback. Existing `UtterancePlanner.plan` remains supported and returns
 only the plan; JSON is the portable persistence and interchange format.
 
+For operational progress from a long-running Python plan, pass `on_progress` to
+`UtterancePlanner.plan`, `UtterancePlanner.compile`, or `compile_document`. The
+callback receives typed `PlannerProgressEvent` objects and does not change the plan:
+
+```python
+from utterplan import PlannerConfig, UtterancePlanner
+
+events = []
+plan = UtterancePlanner(PlannerConfig(language="en-us")).plan(
+    text,
+    on_progress=events.append,
+)
+```
+
+Callbacks run synchronously and exceptions propagate. See the [Python API guide](docs/python-api.md#planner-progress-callbacks) for event fields, model-load events, and reuse behavior.
+
 ## Renderer-consumer boundary
 
 Renderers consume `PlanSegment.text`, which is prepared/spoken text, and use

{utterplan-0.3.3 → utterplan-0.3.4}/docs/changelog.md

@@ -4,6 +4,14 @@
 
 ## [Unreleased]
 
+## [0.3.4] - Unreleased
+
+### Added
+
+- Added typed planner progress events and reused unchanged linguistic analyses
+
+<!-- generated by releaseledger -->
+
 ## [0.3.3] - 2026-10-03
 
 ### Added

{utterplan-0.3.3 → utterplan-0.3.4}/docs/python-api.md

@@ -41,6 +41,33 @@ 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.
 
+## 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.
+
+```python
+from utterplan import PlannerConfig, PlannerProgressEvent, UtterancePlanner
+
+
+def report(event: PlannerProgressEvent) -> None:
+    if event.kind == "run.started":
+        print(
+            event.phase,
+            event.pass_index,
+            event.language,
+            event.provider,
+            event.model,
+        )
+
+
+planner = UtterancePlanner(PlannerConfig(language="en-us"))
+plan = planner.plan(text, on_progress=report)
+```
+
+The phase events cover parsing, source analysis, preparation, spoken analysis, segmentation, and finalization. Each provider run reports `run.started` and `run.completed`; `completed` counts fully completed runs and `total` is the number of runs in that phase. When a local spaCy model is actually loaded, `model.started` and `model.completed` identify its language, provider, and resolved model. Cached models produce no load events. Events contain primitive metadata only, never spaCy pipelines or documents.
+
+Callbacks should be lightweight. An exception raised by a callback propagates to the caller and can be used to stop planning. A provider invocation such as `pipeline(text)` is one opaque work unit: events report its start and completion but do not claim smooth percentages or internal progress. If spoken-text preparation leaves the linguistic input unchanged, the planner can reuse source analysis; the `spoken_analysis` phase events expose `details["reused"] = True` and no provider-run events are emitted for that reuse. Identity preparation also reports `source_analysis` as skipped (`details["skipped"] = True`) because it does not use source analyses; the single actual provider pass runs as logical pass 2.
+
 ## SSMD input and semantic plan
 
 The SSMD parser accepts dialect 0.9 only. Select SSMD explicitly for unversioned canonical fragments with `PlannerConfig(document_format="ssmd")`. Older SSMD source must be migrated with `ssmd migrate FILE --to 0.9`; `migrate_plan_data` and `utterplan migrate` apply to serialized UtterPlan JSON, not source documents.

{utterplan-0.3.3 → utterplan-0.3.4}/tests/test_linguistics.py

@@ -197,7 +197,7 @@ def test_clausal_boundaries_reuse_provider_document(monkeypatch):
 
     plan = UtterancePlanner(config).plan(source)
 
-    assert len(docs) == 2
+    assert len(docs) == 1
     assert detected == [(source, docs[-1])]
     boundary = next(item for item in plan.boundaries if item.kind == "clausal_comma")
     assert boundary.position == source.index(",")
@@ -311,3 +311,71 @@ def test_token_semantics_change_unit_hash_but_provenance_does_not(monkeypatch):
 
     metadata_only = replace(left, linguistic_runs=(changed_provenance,))
     assert metadata_only.units[0].content_hash == left.units[0].content_hash
+
+
+def _count_analysis_calls(monkeypatch: pytest.MonkeyPatch) -> list[str]:
+    calls: list[str] = []
+    original = LinguisticResourcePool.analyze
+
+    def counted(self, text, run, config, *, phase="source_analysis", on_progress=None):
+        calls.append(text)
+        return original(self, text, run, config, phase=phase, on_progress=on_progress)
+
+    monkeypatch.setattr(LinguisticResourcePool, "analyze", counted)
+    return calls
+
+
+def test_identity_preparation_analyzes_once_and_preserves_plan(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls = _count_analysis_calls(monkeypatch)
+    config = PlannerConfig(language="en-us", document_format="plain", text_preparation="identity")
+    baseline = UtterancePlanner(config).plan("Hello world.")
+    assert len(calls) == 1
+    calls.clear()
+
+    events = []
+    observed = UtterancePlanner(config).plan("Hello world.", on_progress=events.append)
+
+    assert len(calls) == 1
+    assert observed.plan_id == baseline.plan_id
+    assert observed.to_json() == baseline.to_json()
+    assert observed.document_metadata["planning"]["linguistic_passes"] == 2
+    skipped = next(
+        event
+        for event in events
+        if event.kind == "phase.started" and event.phase == "source_analysis"
+    )
+    assert skipped.details["skipped"] is True
+    assert [event.pass_index for event in events if event.kind == "run.started"] == [2]
+
+
+def test_unchanged_spokenform_reuses_source_analysis(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _count_analysis_calls(monkeypatch)
+    events = []
+    plan = UtterancePlanner(
+        PlannerConfig(language="en-us", document_format="plain", text_preparation="spokenform")
+    ).plan("Hello world.", on_progress=events.append)
+
+    assert plan.texts.spoken == "Hello world."
+    assert calls == ["Hello world."]
+    reused = [
+        event
+        for event in events
+        if event.phase == "spoken_analysis" and event.details.get("reused") is True
+    ]
+    assert [event.kind for event in reused] == ["phase.started", "phase.completed"]
+    assert not any(
+        event.kind == "run.started" and event.phase == "spoken_analysis" for event in events
+    )
+
+
+def test_changed_spokenform_still_analyzes_prepared_text(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _count_analysis_calls(monkeypatch)
+    source = "Dr. Smith lives here."
+    plan = UtterancePlanner(
+        PlannerConfig(language="en-us", document_format="plain", text_preparation="spokenform")
+    ).plan(source)
+
+    assert plan.texts.spoken == "Doctor Smith lives here."
+    assert calls == [source, plan.texts.spoken]

utterplan-0.3.4/tests/test_progress.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+from dataclasses import fields
+from types import SimpleNamespace
+
+import pytest
+
+from utterplan import (
+    LinguisticsConfig,
+    PlannerConfig,
+    PlannerProgressEvent,
+    ProgressCallback,
+    UtterancePlanner,
+    compile_document,
+)
+
+TEXT = "Hello world."
+
+
+def _identity_config(**kwargs: object) -> PlannerConfig:
+    return PlannerConfig(
+        language="en-us",
+        document_format="plain",
+        text_preparation="identity",
+        **kwargs,
+    )
+
+
+def test_public_progress_callback_reports_major_phases_and_runs() -> None:
+    events: list[PlannerProgressEvent] = []
+    planner = UtterancePlanner(_identity_config())
+
+    plan = planner.plan(TEXT, on_progress=events.append)
+
+    phases = [event.phase for event in events if event.kind == "phase.started"]
+    assert phases == [
+        "parse",
+        "source_analysis",
+        "preparation",
+        "spoken_analysis",
+        "segmentation",
+        "finalization",
+    ]
+    for phase in phases:
+        assert (
+            sum(event.kind == "phase.completed" and event.phase == phase for event in events) == 1
+        )
+
+    run_events = [event for event in events if event.kind.startswith("run.")]
+    assert [(event.kind, event.phase, event.completed, event.total) for event in run_events] == [
+        ("run.started", "spoken_analysis", 0, 1),
+        ("run.completed", "spoken_analysis", 1, 1),
+    ]
+    skipped_source = next(
+        event
+        for event in events
+        if event.kind == "phase.started" and event.phase == "source_analysis"
+    )
+    assert skipped_source.details["skipped"] is True
+    assert all(event.pass_total == 2 for event in run_events)
+    assert all(event.language == "en-us" for event in run_events)
+    assert all(event.char_count == len(TEXT) for event in run_events)
+    assert all(event.provider == "fallback" and event.model is None for event in run_events)
+    assert plan.texts.spoken == TEXT
+
+
+def test_compile_document_forwards_progress_callback() -> None:
+    events: list[PlannerProgressEvent] = []
+    result = compile_document(
+        TEXT,
+        input_format="plain",
+        config=_identity_config(),
+        on_progress=events.append,
+    )
+
+    assert result.plan.texts.spoken == TEXT
+    assert events
+    assert events[0].kind == "phase.started"
+    assert events[0].phase == "parse"
+
+
+def test_planner_compile_forwards_progress_callback() -> None:
+    events: list[PlannerProgressEvent] = []
+    result = UtterancePlanner(_identity_config()).compile(TEXT, on_progress=events.append)
+
+    assert result.plan.texts.spoken == TEXT
+    assert any(event.phase == "finalization" for event in events)
+
+
+def test_progress_callback_exceptions_propagate() -> None:
+    class MarkerError(RuntimeError):
+        pass
+
+    def callback(_event: PlannerProgressEvent) -> None:
+        raise MarkerError
+
+    with pytest.raises(MarkerError):
+        UtterancePlanner(_identity_config()).plan(TEXT, on_progress=callback)
+
+
+def test_model_load_events_bracket_real_load_and_cached_calls(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    timeline: list[str] = []
+
+    class Pipeline:
+        meta = {"version": "1.0"}
+
+        def __call__(self, text: str) -> list[SimpleNamespace]:
+            timeline.append("provider")
+            return [
+                SimpleNamespace(
+                    idx=match.start(),
+                    text=match.group(0),
+                    pos_="NOUN",
+                    tag_="NN",
+                    lemma_=match.group(0).lower(),
+                    morph="",
+                )
+                for match in re.finditer(r"\S+", text)
+            ]
+
+    pipeline = Pipeline()
+    loaded: list[str] = []
+
+    def load(model: str) -> Pipeline:
+        timeline.append("load")
+        loaded.append(model)
+        return pipeline
+
+    monkeypatch.setitem(
+        sys.modules,
+        "spacy",
+        SimpleNamespace(__version__="3.7.0", load=load),
+    )
+    config = _identity_config(
+        linguistics=LinguisticsConfig(use_spacy=True, spacy_model="fake_model", require_spacy=True)
+    )
+    events: list[PlannerProgressEvent] = []
+
+    def report(event: PlannerProgressEvent) -> None:
+        events.append(event)
+        timeline.append(event.kind)
+
+    planner = UtterancePlanner(config)
+    planner.plan(TEXT, on_progress=report)
+    planner.plan(TEXT, on_progress=report)
+
+    assert loaded == ["fake_model"]
+    assert [event.kind for event in events if event.kind.startswith("model.")] == [
+        "model.started",
+        "model.completed",
+    ]
+    model_events = [event for event in events if event.kind.startswith("model.")]
+    assert all(event.phase == "spoken_analysis" for event in model_events)
+    assert all(event.language == "en-us" for event in model_events)
+    assert all(event.provider == "spacy" and event.model == "fake_model" for event in model_events)
+    assert timeline.index("run.started") < timeline.index("model.started")
+    assert (
+        timeline.index("model.started") < timeline.index("load") < timeline.index("model.completed")
+    )
+    assert timeline.index("model.completed") < timeline.index("provider")
+    assert timeline.index("provider") < timeline.index("run.completed")
+
+
+def test_progress_callback_type_is_public() -> None:
+    def callback(_event: PlannerProgressEvent) -> None:
+        return None
+
+    public_callback: ProgressCallback = callback
+    assert callable(public_callback)
+
+
+def test_callback_output_matches_baseline_and_events_are_public_primitives() -> None:
+    source = "Dr. Smith lives here."
+    config = PlannerConfig(language="en-us", document_format="plain", text_preparation="spokenform")
+    baseline = UtterancePlanner(config).plan(source)
+    events: list[PlannerProgressEvent] = []
+    observed = UtterancePlanner(config).plan(source, on_progress=events.append)
+
+    assert observed.plan_id == baseline.plan_id
+    assert observed.to_json() == baseline.to_json()
+
+    def is_public_value(value: object) -> bool:
+        if value is None or isinstance(value, (str, int, float, bool)):
+            return True
+        if isinstance(value, Mapping):
+            return all(
+                isinstance(key, str) and is_public_value(item) for key, item in value.items()
+            )
+        if isinstance(value, (list, tuple)):
+            return all(is_public_value(item) for item in value)
+        return False
+
+    assert events
+    assert all(
+        is_public_value(getattr(event, field.name)) for event in events for field in fields(event)
+    )
+
+
+def test_multilingual_run_progress_is_monotonic_and_matches_plan_runs() -> None:
+    source = (
+        '---\nssmd_version: "0.9"\nlanguage: en-us\n---\n'
+        'Hello [bonjour]{lang="fr"} [hola]{lang="es"}.'
+    )
+    events: list[PlannerProgressEvent] = []
+    plan = UtterancePlanner(
+        PlannerConfig(language="en-us", document_format="ssmd", text_preparation="identity")
+    ).plan(source, on_progress=events.append)
+
+    started = [
+        event
+        for event in events
+        if event.kind == "run.started" and event.phase == "spoken_analysis"
+    ]
+    completed = [
+        event
+        for event in events
+        if event.kind == "run.completed" and event.phase == "spoken_analysis"
+    ]
+    expected_languages = [run.language for run in plan.languages]
+
+    assert [event.language for event in started] == expected_languages
+    assert [event.language for event in completed] == expected_languages
+    assert [event.completed for event in started] == list(range(len(expected_languages)))
+    assert [event.completed for event in completed] == list(range(1, len(expected_languages) + 1))
+    assert all(event.total == len(expected_languages) for event in started + completed)
+    assert all(event.pass_index == 2 and event.pass_total == 2 for event in started + completed)

{utterplan-0.3.3 → utterplan-0.3.4}/utterplan/__init__.py

@@ -54,6 +54,7 @@ from .model import (
     VoiceDirective,
 )
 from .planner import UtterancePlanner
+from .progress import PlannerProgressEvent, ProgressCallback, ProgressKind, ProgressPhase
 from .versioning import (
     CURRENT_SCHEMA_VERSION,
     FORMAT,
@@ -75,6 +76,10 @@ __all__ = [
     "SSMDConfig",
     "parse_duration",
     "UtterancePlanner",
+    "PlannerProgressEvent",
+    "ProgressCallback",
+    "ProgressKind",
+    "ProgressPhase",
     "UtterancePlan",
     "PlanSource",
     "PlanTexts",

{utterplan-0.3.3 → utterplan-0.3.4}/utterplan/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.3'
-__version_tuple__ = version_tuple = (0, 3, 3)
+__version__ = version = '0.3.4'
+__version_tuple__ = version_tuple = (0, 3, 4)
 
-__commit_id__ = commit_id = 'g0e4e0751e'
+__commit_id__ = commit_id = 'g938cb2c4a'

{utterplan-0.3.3 → utterplan-0.3.4}/utterplan/compiler.py

@@ -6,6 +6,7 @@ from typing import Literal
 from .config import PlannerConfig
 from .exceptions import ConfigurationError
 from .model import Diagnostic, UtterancePlan
+from .progress import ProgressCallback
 
 InputFormat = Literal["ssmd", "plain"]
 
@@ -72,13 +73,14 @@ def compile_document(
     config: PlannerConfig,
     fallback_language: str | None = None,
     trace: bool = False,
+    on_progress: ProgressCallback | None = None,
 ) -> CompileResult:
     """Compile one SSMD document or explicitly selected plain-text document.
 
     The document's declared SSMD language is authoritative. ``fallback_language``
     replaces the configured fallback for this request; it never forces a language
     over document semantics. ``PlannerConfig.language`` remains the compatibility
-    fallback when ``fallback_language`` is omitted.
+    fallback when ``fallback_language`` is omitted. The optional progress callback is synchronous and operational only; exceptions raised by it propagate to the caller.
     """
     if input_format not in {"ssmd", "plain"}:
         raise ConfigurationError("input_format must be 'ssmd' or 'plain'")
@@ -94,7 +96,7 @@ def compile_document(
 
     planner = UtterancePlanner(effective_config)
     try:
-        return planner.compile(text, config=effective_config, trace=trace)
+        return planner.compile(text, config=effective_config, trace=trace, on_progress=on_progress)
     finally:
         planner.close()