utterplan 0.3.1__tar.gz → 0.3.2__tar.gz

{utterplan-0.3.1 → utterplan-0.3.2}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -48,3 +48,9 @@
 {"data":{"updated_rows":1},"event":"audit.updated","event_id":"event-0048","record_revisions":{"commit_audit_sheet":2},"release_version":"0.3.1","schema_version":2}
 {"data":{"entry_ids":["entry-0001"],"synced_audit_rows":1},"event":"entry.batch_added","event_id":"event-0049","record_revisions":{"commit_audit_sheet":3,"entry:0.3.1/entry-0001":1,"release:0.3.1":3},"release_version":"0.3.1","schema_version":2}
 {"data":{"released_at":"2026-09-27"},"event":"release.finalized","event_id":"event-0050","record_revisions":{"release:0.3.1":4},"release_version":"0.3.1","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0051","record_revisions":{"release:0.3.2":1},"release_version":"0.3.2","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-0052","record_revisions":{"release:0.3.2":2},"release_version":"0.3.2","schema_version":2}
+{"data":{"row_count":3},"event":"audit.created","event_id":"event-0053","record_revisions":{"commit_audit_sheet":1},"release_version":"0.3.2","schema_version":2}
+{"data":{"updated_rows":3},"event":"audit.updated","event_id":"event-0054","record_revisions":{"commit_audit_sheet":2},"release_version":"0.3.2","schema_version":2}
+{"data":{"entry_ids":["entry-0001","entry-0002"],"synced_audit_rows":2},"event":"entry.batch_added","event_id":"event-0055","record_revisions":{"commit_audit_sheet":3,"entry:0.3.2/entry-0001":1,"entry:0.3.2/entry-0002":1,"release:0.3.2":3},"release_version":"0.3.2","schema_version":2}
+{"data":{"released_at":"2026-10-03"},"event":"release.finalized","event_id":"event-0056","record_revisions":{"release:0.3.2":4},"release_version":"0.3.2","schema_version":2}

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

@@ -0,0 +1,105 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 3
+release_version: 0.3.2
+git_base_ref: v0.3.1
+git_base_sha: b0415758f6c1d1890d8015ce40c1e52d6120cf46
+git_head_ref: HEAD
+git_head_sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+git_range: b0415758f6c1d1890d8015ce40c1e52d6120cf46..ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+commit_count: 3
+rows:
+  - sha: 6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    source_ref: git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    short_sha: 6c2a1ac
+    changed_paths:
+      - tests/test_preparation.py
+      - utterplan/preparation.py
+    stats:
+      files_changed: 2
+      insertions: 40
+      deletions: 1
+    inspected: true
+    inspected_paths:
+      - tests/test_preparation.py
+      - utterplan/preparation.py
+    observed_behavior:
+      Spoken-text preparation protects annotation spans using sub,
+      as, say-as, ph, or phonemes from automated replacement while preserving source
+      offset mappings.
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: improve prepare ssmd"
+    target_entry_id: entry-0001
+    notes: ""
+  - sha: a2bc20d5d25f880688886f1867f0fd398a5b8c7e
+    source_ref: git:a2bc20d5d25f880688886f1867f0fd398a5b8c7e
+    short_sha: a2bc20d
+    changed_paths:
+      - 01_todo.md
+      - plan.md
+    stats:
+      files_changed: 2
+      insertions: 0
+      deletions: 1907
+    inspected: true
+    inspected_paths:
+      - 01_todo.md
+      - plan.md
+    observed_behavior:
+      Removed planning-only repository files; no runtime or public
+      package behavior changed.
+    public_impact: internal
+    decision: internal
+    stale: false
+    evidence_subject: "chore: remove plan files"
+    notes: Repository planning artifacts only, with no user-facing change.
+  - sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    source_ref: git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    short_sha: ba3b5af
+    changed_paths:
+      - tests/golden/ssmd_09_comprehensive.utterplan.json
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/test_consumer_readiness.py
+      - tests/test_preparation.py
+      - tests/test_ssmd_09_parser.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/preparation.py
+    stats:
+      files_changed: 13
+      insertions: 183
+      deletions: 7
+    inspected: true
+    inspected_paths:
+      - tests/golden/ssmd_09_comprehensive.utterplan.json
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/test_consumer_readiness.py
+      - tests/test_preparation.py
+      - tests/test_ssmd_09_parser.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/preparation.py
+    observed_behavior:
+      SSMD sequence_fallback_mode accepts spell or preserve, defaults
+      to spell, is forwarded to spoken-form preparation and serialized in plan metadata
+      and identity, and rejects invalid values.
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: parse fallback mode parameter from ssmdconvert settings"
+    target_entry_id: entry-0002
+    notes: ""

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

@@ -0,0 +1,32 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: 0.3.2
+kind: fixed
+summary:
+  Fixed text preparation so authored SSMD substitutions and say-as annotations
+  remain unchanged
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+paths:
+  - tests/test_preparation.py
+  - utterplan/preparation.py
+issues: []
+prs: []
+sources:
+  - git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 1
+---
+
+Spoken-text preparation excludes spans with `sub`, `as`, and `say-as` attributes from automatic spoken-form replacement, preserving author-provided text while retaining existing pronunciation protections.

utterplan-0.3.2/.ledger/releaseledger/data/ledgers/main/releases/0.3.2/entries/entry-0002.md

@@ -0,0 +1,41 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0002
+release_version: 0.3.2
+kind: added
+summary: Added SSMD sequence fallback mode controls for spoken-form preparation
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+paths:
+  - tests/golden/ssmd_09_comprehensive.utterplan.json
+  - tests/migration/goldens/multilingual_preparation.json
+  - tests/migration/goldens/spokenform_numbers.json
+  - tests/migration/goldens/ssmd_break.json
+  - tests/migration/goldens/ssmd_language_detection.json
+  - tests/migration/goldens/ssmd_marker.json
+  - tests/migration/goldens/ssmd_pronunciation.json
+  - tests/test_consumer_readiness.py
+  - tests/test_preparation.py
+  - tests/test_ssmd_09_parser.py
+  - utterplan/parsers.py
+  - utterplan/planner.py
+  - utterplan/preparation.py
+issues: []
+prs: []
+sources:
+  - git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 2
+---
+
+SSMD headers can choose `spell` or `preserve` for sequence fallback behavior. The default remains `spell`; the selected mode is carried in plan metadata, and invalid values are rejected during planning.

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

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 4
+version: 0.3.2
+status: released
+history_state: curated
+title: null
+released_at: "2026-10-03"
+previous_version: 0.3.1
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 2
+artifact_count: 0
+git_base_ref: v0.3.1
+git_base_sha: b0415758f6c1d1890d8015ce40c1e52d6120cf46
+git_head_ref: HEAD
+git_head_sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+git_range: b0415758f6c1d1890d8015ce40c1e52d6120cf46..ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+git_commit_count: 3
+---

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

@@ -0,0 +1,48 @@
+rows:
+  - sha: 6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    inspected: true
+    inspected_paths:
+      - tests/test_preparation.py
+      - utterplan/preparation.py
+    observed_behavior: Spoken-text preparation protects annotation spans using sub, as, say-as, ph, or phonemes from automated replacement while preserving source offset mappings.
+    public_impact: public
+    decision: accepted
+    target_entry_key: null
+    target_entry_id: null
+    notes: ""
+    stale: false
+  - sha: a2bc20d5d25f880688886f1867f0fd398a5b8c7e
+    inspected: true
+    inspected_paths:
+      - 01_todo.md
+      - plan.md
+    observed_behavior: Removed planning-only repository files; no runtime or public package behavior changed.
+    public_impact: internal
+    decision: internal
+    target_entry_key: null
+    target_entry_id: null
+    notes: Repository planning artifacts only, with no user-facing change.
+    stale: false
+  - sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    inspected: true
+    inspected_paths:
+      - tests/golden/ssmd_09_comprehensive.utterplan.json
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/test_consumer_readiness.py
+      - tests/test_preparation.py
+      - tests/test_ssmd_09_parser.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/preparation.py
+    observed_behavior: SSMD sequence_fallback_mode accepts spell or preserve, defaults to spell, is forwarded to spoken-form preparation and serialized in plan metadata and identity, and rejects invalid values.
+    public_impact: public
+    decision: accepted
+    target_entry_key: null
+    target_entry_id: null
+    notes: ""
+    stale: false

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

@@ -0,0 +1,75 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 1
+release_version: 0.3.2
+git_base_ref: v0.3.1
+git_base_sha: b0415758f6c1d1890d8015ce40c1e52d6120cf46
+git_head_ref: HEAD
+git_head_sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+git_range: b0415758f6c1d1890d8015ce40c1e52d6120cf46..ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+commit_count: 3
+rows:
+  - sha: 6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    source_ref: git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    short_sha: 6c2a1ac
+    changed_paths:
+      - tests/test_preparation.py
+      - utterplan/preparation.py
+    stats:
+      files_changed: 2
+      insertions: 40
+      deletions: 1
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: improve prepare ssmd"
+  - sha: a2bc20d5d25f880688886f1867f0fd398a5b8c7e
+    source_ref: git:a2bc20d5d25f880688886f1867f0fd398a5b8c7e
+    short_sha: a2bc20d
+    changed_paths:
+      - 01_todo.md
+      - plan.md
+    stats:
+      files_changed: 2
+      insertions: 0
+      deletions: 1907
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "chore: remove plan files"
+  - sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    source_ref: git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    short_sha: ba3b5af
+    changed_paths:
+      - tests/golden/ssmd_09_comprehensive.utterplan.json
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/test_consumer_readiness.py
+      - tests/test_preparation.py
+      - tests/test_ssmd_09_parser.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/preparation.py
+    stats:
+      files_changed: 13
+      insertions: 183
+      deletions: 7
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: parse fallback mode parameter from ssmdconvert settings"

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

@@ -0,0 +1,54 @@
+schema: releaseledger.entry-batch.v1
+operation: create
+schema_version: 1
+object_type: release_entry_batch
+release_version: 0.3.2
+git_base_ref: b0415758f6c1d1890d8015ce40c1e52d6120cf46
+git_base_sha: b0415758f6c1d1890d8015ce40c1e52d6120cf46
+git_head_ref: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+git_head_sha: ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+include_merges: nontrivial
+entries:
+  - kind: fixed
+    summary: Fixed text preparation so authored SSMD substitutions and say-as annotations remain unchanged
+    status: accepted
+    body: >-
+      Spoken-text preparation excludes spans with `sub`, `as`, and `say-as` attributes from automatic spoken-form replacement, preserving author-provided text while retaining existing pronunciation protections.
+    source_refs:
+      - git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    paths:
+      - tests/test_preparation.py
+      - utterplan/preparation.py
+    sources:
+      - git:6c2a1ac444c76ea183a791b59af2e92fb60dbb23
+    prs: []
+    issues: []
+    contributors:
+      - "@holgern"
+  - kind: added
+    summary: Added SSMD sequence fallback mode controls for spoken-form preparation
+    status: accepted
+    body: >-
+      SSMD headers can choose `spell` or `preserve` for sequence fallback behavior. The default remains `spell`; the selected mode is carried in plan metadata, and invalid values are rejected during planning.
+    source_refs:
+      - git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    paths:
+      - tests/golden/ssmd_09_comprehensive.utterplan.json
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/test_consumer_readiness.py
+      - tests/test_preparation.py
+      - tests/test_ssmd_09_parser.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/preparation.py
+    sources:
+      - git:ba3b5afb6c619cf91e482db16b19d53f199eb1e2
+    prs: []
+    issues: []
+    contributors:
+      - "@holgern"

utterplan-0.3.2/.ledger/releaseledger/work/0.3.2/evidence/6c2a1ac.patch

@@ -0,0 +1,64 @@
+ tests/test_preparation.py | 37 +++++++++++++++++++++++++++++++++++++
+ utterplan/preparation.py  |  4 +++-
+ 2 files changed, 40 insertions(+), 1 deletion(-)
+
+diff --git a/tests/test_preparation.py b/tests/test_preparation.py
+index dad7957..11f777b 100644
+--- a/tests/test_preparation.py
++++ b/tests/test_preparation.py
+@@ -65,3 +65,40 @@ def test_zero_width_audio_annotation_maps_to_spoken_point():
+     assert annotation.structural_start == annotation.structural_end
+     assert annotation.spoken_start == annotation.spoken_end
+     assert plan.texts.spoken[annotation.spoken_start : annotation.spoken_end] == ""
++
++
++def test_author_speech_annotations_are_protected_and_keep_source_offsets():
++    source = (
++        '[H2O]{sub="water"} '
++        '[31.12.2024]{as="date" format="dd.mm.yyyy"} '
++        '[04/05/2024]{say-as="date" format="MM/dd/yyyy"} '
++        '[tomato]{ph="təˈmeɪtoʊ"} '
++        '[AWS]{phonemes="eɪ dʌbəljuː ɛs"} ordinary 5 kg.'
++    )
++    plan = UtterancePlanner(PlannerConfig(language="en-us", document_format="ssmd")).plan(source)
++
++    assert plan.texts.spoken == ("H2O 31.12.2024 04/05/2024 tomato AWS ordinary five kilograms.")
++    protected = [
++        annotation
++        for annotation in plan.annotations
++        if any(key in annotation.attrs for key in ("sub", "as", "say-as", "ph", "phonemes"))
++    ]
++    assert len(protected) == 5
++    for annotation in protected:
++        structural = plan.texts.structural[annotation.structural_start : annotation.structural_end]
++        spoken = plan.texts.spoken[annotation.spoken_start : annotation.spoken_end]
++        assert spoken == structural
++
++    assert any(annotation.attrs.get("sub") == "water" for annotation in protected)
++    assert any(annotation.attrs.get("as") == "date" for annotation in protected)
++    assert any(annotation.attrs.get("say-as") == "date" for annotation in protected)
++    assert any("ph" in annotation.attrs for annotation in protected)
++    assert any("phonemes" in annotation.attrs for annotation in protected)
++
++    assert len(plan.preparation.replacements) == 1
++    replacement = plan.preparation.replacements[0]
++    assert plan.texts.structural[replacement["source_start"] : replacement["source_end"]] == "5 kg"
++    assert (
++        plan.texts.spoken[replacement["output_start"] : replacement["output_end"]]
++        == "five kilograms"
++    )
+diff --git a/utterplan/preparation.py b/utterplan/preparation.py
+index d11bfdb..2483738 100644
+--- a/utterplan/preparation.py
++++ b/utterplan/preparation.py
+@@ -50,7 +50,9 @@ class SpokenformTextPreparer:
+                     for annotation in annotations
+                     if annotation.structural_start >= run.spoken_start
+                     and annotation.structural_end <= run.spoken_end
+-                    and (annotation.attrs.get("ph") or annotation.attrs.get("phonemes"))
++                    and any(
++                        key in annotation.attrs for key in ("sub", "as", "say-as", "ph", "phonemes")
++                    )
+                 ]
+                 kwargs: dict[str, Any] = {
+                     "language": language_lookup_key(run.language),