renderplan 0.1.3__tar.gz → 0.1.4__tar.gz

{renderplan-0.1.3 → renderplan-0.1.4}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -22,3 +22,5 @@
 {"data":{"updated_rows":1},"event":"audit.updated","event_id":"event-0022","record_revisions":{"commit_audit_sheet":2},"release_version":"v0.1.3","schema_version":2}
 {"data":{"entry_ids":["entry-0001"],"synced_audit_rows":1},"event":"entry.batch_added","event_id":"event-0023","record_revisions":{"commit_audit_sheet":3,"entry:v0.1.3/entry-0001":1,"release:v0.1.3":3},"release_version":"v0.1.3","schema_version":2}
 {"data":{"released_at":"2026-10-25"},"event":"release.finalized","event_id":"event-0024","record_revisions":{"release:v0.1.3":4},"release_version":"v0.1.3","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0025","record_revisions":{"release:v0.1.4":1},"release_version":"v0.1.4","schema_version":2}
+{"data":{"kind":"added","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0026","record_revisions":{"entry:v0.1.4/entry-0001":1,"release:v0.1.4":2},"release_version":"v0.1.4","schema_version":2}

renderplan-0.1.4/.ledger/releaseledger/data/ledgers/main/releases/v0.1.4/entries/entry-0001.md

@@ -0,0 +1,29 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: v0.1.4
+kind: added
+summary: Added portable character interpretation semantics to speech controls
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - tl:task-0004
+paths:
+  - renderplan/model.py
+  - renderplan/contracts.py
+  - README.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---
+
+RenderPlan formalizes say_as parameter validation while preserving exact request text and leaving engine-specific realization to renderer preflight.

renderplan-0.1.4/.ledger/releaseledger/data/ledgers/main/releases/v0.1.4/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 2
+version: v0.1.4
+status: planned
+history_state: curated
+title: null
+released_at: null
+previous_version: v0.1.3
+cancel_reason: null
+superseded_by: null
+changelog_file: docs/changelog.md
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 1
+artifact_count: 0
+git_base_ref: null
+git_base_sha: null
+git_head_ref: null
+git_head_sha: null
+git_range: null
+git_commit_count: null
+---

{renderplan-0.1.3/renderplan.egg-info → renderplan-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: renderplan
-Version: 0.1.3
+Version: 0.1.4
 Summary: Engine-neutral render profile, plan, preflight, manifest, and collection contracts for speech pipelines.
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3
@@ -90,6 +90,26 @@ The destination start offset of source span `N` inside the request is the sum of
 
 `SpeechControl` is request-local and renderer-neutral: it carries `start`, `end`, `name`, and TOML-safe `params`. Initial semantic names include `pronunciation`, `prosody`, `emphasis`, `say_as`, and `extension:<name>`. Controls participate in `segment_id`; renderers decide support, and unsupported controls must fail preflight rather than be ignored. Control ranges may overlap only when the source semantics permit it. Engine-specific voice selection is resolved into the opaque logical role/binding; audio directives become `AudioItem`s.
 
+### Standard `say_as` semantics
+
+`SpeechControl(name="say_as")` requires a non-empty `interpret_as` string and accepts optional non-empty `format` and `detail` strings. The standard value `interpret_as = "characters"` means: speak the covered text as a sequence of separately pronounced characters, preserving the surrounding request as one continuous speech request when the engine can do so. It is portable intent; RenderPlan does not dictate an engine's realization or restrict future `interpret_as` values.
+
+For example, the following control covers exactly `A R T`:
+
+```toml
+[[flow.control]]
+start = 0
+end = 5
+name = "say_as"
+
+[flow.control.params]
+interpret_as = "characters"
+```
+
+The exact-range invariant is `speech.text[0:5] == "A R T"`. The control does not rewrite the canonical request text, prescribe spaces, hyphens, commas, SSML, phonemes, or pauses, and does not split a sentence or add a `PauseItem`. A renderer that does not support the requested semantics must reject the request during preflight rather than silently ignore the control.
+
+Do not store `A- R- T` in RenderPlan merely because one Kokoro frontend prefers that spelling; an engine may choose such a frontend-specific realization internally.
+
 Bindings copied into plans must be self-contained enough to execute without reopening the RenderProfile. This contract does not define renderer-specific path keys or local-asset resolution.
 This schema has no generic asset-reference type yet. A VoiceRender profile producer must refuse bindings that depend on profile-local or otherwise uncopied asset state; do not introduce renderer-specific asset-path keys into this shared contract.
 

{renderplan-0.1.3 → renderplan-0.1.4}/README.md

@@ -67,6 +67,26 @@ The destination start offset of source span `N` inside the request is the sum of
 
 `SpeechControl` is request-local and renderer-neutral: it carries `start`, `end`, `name`, and TOML-safe `params`. Initial semantic names include `pronunciation`, `prosody`, `emphasis`, `say_as`, and `extension:<name>`. Controls participate in `segment_id`; renderers decide support, and unsupported controls must fail preflight rather than be ignored. Control ranges may overlap only when the source semantics permit it. Engine-specific voice selection is resolved into the opaque logical role/binding; audio directives become `AudioItem`s.
 
+### Standard `say_as` semantics
+
+`SpeechControl(name="say_as")` requires a non-empty `interpret_as` string and accepts optional non-empty `format` and `detail` strings. The standard value `interpret_as = "characters"` means: speak the covered text as a sequence of separately pronounced characters, preserving the surrounding request as one continuous speech request when the engine can do so. It is portable intent; RenderPlan does not dictate an engine's realization or restrict future `interpret_as` values.
+
+For example, the following control covers exactly `A R T`:
+
+```toml
+[[flow.control]]
+start = 0
+end = 5
+name = "say_as"
+
+[flow.control.params]
+interpret_as = "characters"
+```
+
+The exact-range invariant is `speech.text[0:5] == "A R T"`. The control does not rewrite the canonical request text, prescribe spaces, hyphens, commas, SSML, phonemes, or pauses, and does not split a sentence or add a `PauseItem`. A renderer that does not support the requested semantics must reject the request during preflight rather than silently ignore the control.
+
+Do not store `A- R- T` in RenderPlan merely because one Kokoro frontend prefers that spelling; an engine may choose such a frontend-specific realization internally.
+
 Bindings copied into plans must be self-contained enough to execute without reopening the RenderProfile. This contract does not define renderer-specific path keys or local-asset resolution.
 This schema has no generic asset-reference type yet. A VoiceRender profile producer must refuse bindings that depend on profile-local or otherwise uncopied asset state; do not introduce renderer-specific asset-path keys into this shared contract.
 

{renderplan-0.1.3 → renderplan-0.1.4}/docs/changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [v0.1.4] - Unreleased
+
+### Added
+
+- Added portable character interpretation semantics to speech controls
+
+<!-- generated by releaseledger -->
+
 ## [v0.1.3] - 2026-10-25
 
 ### Added

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan/__init__.py

@@ -24,7 +24,15 @@ from .collection import (
     validate_renderplan_set,
     validate_renderplan_set_profile,
 )
-from .contracts import CONTRACTS, supported_contracts
+from .contracts import (
+    CONTRACTS,
+    CONTROL_EMPHASIS,
+    CONTROL_PRONUNCIATION,
+    CONTROL_PROSODY,
+    CONTROL_SAY_AS,
+    SAY_AS_CHARACTERS,
+    supported_contracts,
+)
 from .errors import CodecError, RenderPlanError, ValidationError
 from .model import (
     MANIFEST_FORMAT,
@@ -66,12 +74,17 @@ from .version import __version__
 
 __all__ = [
     "CONTRACTS",
+    "CONTROL_EMPHASIS",
+    "CONTROL_PRONUNCIATION",
+    "CONTROL_PROSODY",
+    "CONTROL_SAY_AS",
     "MANIFEST_FORMAT",
     "PLAN_FORMAT",
     "PREFLIGHT_FORMAT",
     "PROFILE_FORMAT",
     "RENDERPLAN_SET_FORMAT",
     "RENDERPLAN_SET_VERSION",
+    "SAY_AS_CHARACTERS",
     "AudioItem",
     "CapacityConstraint",
     "CodecError",

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.3'
-__version_tuple__ = version_tuple = (0, 1, 3)
+__version__ = version = '0.1.4'
+__version_tuple__ = version_tuple = (0, 1, 4)
 
-__commit_id__ = commit_id = 'g3d1e5588a'
+__commit_id__ = commit_id = 'ga434ece68'

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan/contracts.py

@@ -25,9 +25,25 @@ CONTRACTS: Mapping[str, int] = MappingProxyType(
 )
 
 
+CONTROL_PRONUNCIATION = "pronunciation"
+CONTROL_PROSODY = "prosody"
+CONTROL_EMPHASIS = "emphasis"
+CONTROL_SAY_AS = "say_as"
+
+SAY_AS_CHARACTERS = "characters"
+
+
 def supported_contracts() -> Mapping[str, int]:
     """Return the immutable mapping of supported document formats to versions."""
     return CONTRACTS
 
 
-__all__ = ["CONTRACTS", "supported_contracts"]
+__all__ = [
+    "CONTRACTS",
+    "CONTROL_EMPHASIS",
+    "CONTROL_PRONUNCIATION",
+    "CONTROL_PROSODY",
+    "CONTROL_SAY_AS",
+    "SAY_AS_CHARACTERS",
+    "supported_contracts",
+]

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan/model.py

@@ -247,6 +247,7 @@ class SpeechControl:
             raise ValidationError("control must satisfy 0 <= start < end")
         require_nonempty(self.name, "control.name")
         require_toml_value(self.params, "control.params")
+        validate_standard_control(self)
 
     def ordering_key(self) -> tuple[int, int, str, bytes]:
         return (self.start, self.end, self.name, canonical_json_bytes(self.params))
@@ -260,6 +261,28 @@ class SpeechControl:
         }
 
 
+def validate_standard_control(control: SpeechControl) -> None:
+    """Validate parameters for known standard speech controls."""
+    if control.name != "say_as":
+        return
+
+    allowed = {"interpret_as", "format", "detail"}
+    unknown = set(control.params).difference(allowed)
+    if unknown:
+        raise ValidationError(
+            "say_as control has unsupported parameter(s): " + ", ".join(sorted(unknown))
+        )
+
+    interpret_as = control.params.get("interpret_as")
+    if not isinstance(interpret_as, str) or not interpret_as.strip():
+        raise ValidationError("say_as.interpret_as must be a non-empty string")
+
+    for name in ("format", "detail"):
+        value = control.params.get(name)
+        if value is not None and (not isinstance(value, str) or not value.strip()):
+            raise ValidationError(f"say_as.{name} must be a non-empty string when present")
+
+
 @dataclass(frozen=True, slots=True)
 class TokenBundle:
     """Dense token spans/pos/tag and sparse, token-indexed lemma/morph values."""

{renderplan-0.1.3 → renderplan-0.1.4/renderplan.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: renderplan
-Version: 0.1.3
+Version: 0.1.4
 Summary: Engine-neutral render profile, plan, preflight, manifest, and collection contracts for speech pipelines.
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3
@@ -90,6 +90,26 @@ The destination start offset of source span `N` inside the request is the sum of
 
 `SpeechControl` is request-local and renderer-neutral: it carries `start`, `end`, `name`, and TOML-safe `params`. Initial semantic names include `pronunciation`, `prosody`, `emphasis`, `say_as`, and `extension:<name>`. Controls participate in `segment_id`; renderers decide support, and unsupported controls must fail preflight rather than be ignored. Control ranges may overlap only when the source semantics permit it. Engine-specific voice selection is resolved into the opaque logical role/binding; audio directives become `AudioItem`s.
 
+### Standard `say_as` semantics
+
+`SpeechControl(name="say_as")` requires a non-empty `interpret_as` string and accepts optional non-empty `format` and `detail` strings. The standard value `interpret_as = "characters"` means: speak the covered text as a sequence of separately pronounced characters, preserving the surrounding request as one continuous speech request when the engine can do so. It is portable intent; RenderPlan does not dictate an engine's realization or restrict future `interpret_as` values.
+
+For example, the following control covers exactly `A R T`:
+
+```toml
+[[flow.control]]
+start = 0
+end = 5
+name = "say_as"
+
+[flow.control.params]
+interpret_as = "characters"
+```
+
+The exact-range invariant is `speech.text[0:5] == "A R T"`. The control does not rewrite the canonical request text, prescribe spaces, hyphens, commas, SSML, phonemes, or pauses, and does not split a sentence or add a `PauseItem`. A renderer that does not support the requested semantics must reject the request during preflight rather than silently ignore the control.
+
+Do not store `A- R- T` in RenderPlan merely because one Kokoro frontend prefers that spelling; an engine may choose such a frontend-specific realization internally.
+
 Bindings copied into plans must be self-contained enough to execute without reopening the RenderProfile. This contract does not define renderer-specific path keys or local-asset resolution.
 This schema has no generic asset-reference type yet. A VoiceRender profile producer must refuse bindings that depend on profile-local or otherwise uncopied asset state; do not introduce renderer-specific asset-path keys into this shared contract.
 

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan.egg-info/SOURCES.txt

@@ -30,6 +30,8 @@ pyproject.toml
 .ledger/releaseledger/data/ledgers/main/releases/v0.1.3/release.md
 .ledger/releaseledger/data/ledgers/main/releases/v0.1.3/audit/commit-audit.yaml
 .ledger/releaseledger/data/ledgers/main/releases/v0.1.3/entries/entry-0001.md
+.ledger/releaseledger/data/ledgers/main/releases/v0.1.4/release.md
+.ledger/releaseledger/data/ledgers/main/releases/v0.1.4/entries/entry-0001.md
 .ledger/releaseledger/work/v0.1.1/audit-decisions.yaml
 .ledger/releaseledger/work/v0.1.1/audit.yaml
 .ledger/releaseledger/work/v0.1.1/entries.yaml

{renderplan-0.1.3 → renderplan-0.1.4}/renderplan.egg-info/scm_file_list.json

@@ -27,6 +27,8 @@
     ".ledger/releaseledger/data/ledgers/main/releases/v0.1.3/audit/commit-audit.yaml",
     ".ledger/releaseledger/data/ledgers/main/releases/v0.1.3/entries/entry-0001.md",
     ".ledger/releaseledger/data/ledgers/main/releases/v0.1.3/release.md",
+    ".ledger/releaseledger/data/ledgers/main/releases/v0.1.4/entries/entry-0001.md",
+    ".ledger/releaseledger/data/ledgers/main/releases/v0.1.4/release.md",
     ".ledger/releaseledger/work/v0.1.1/audit-decisions.yaml",
     ".ledger/releaseledger/work/v0.1.1/audit.yaml",
     ".ledger/releaseledger/work/v0.1.1/entries.yaml",

renderplan-0.1.4/renderplan.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.4",
+  "distance": 0,
+  "node": "ga434ece686229c4accf193c4fdc8dd4357039586",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-28"
+}

{renderplan-0.1.3 → renderplan-0.1.4}/tests/test_contracts.py

@@ -9,6 +9,11 @@ import pytest
 
 from renderplan import (
     CONTRACTS,
+    CONTROL_EMPHASIS,
+    CONTROL_PRONUNCIATION,
+    CONTROL_PROSODY,
+    CONTROL_SAY_AS,
+    SAY_AS_CHARACTERS,
     AudioItem,
     CapacityConstraint,
     CodecError,
@@ -218,6 +223,83 @@ def test_renderplan_roundtrip_with_controls_and_generic_binding(tmp_path: Path)
     assert loaded.speech[0].controls[0].params == {"level": "moderate"}
 
 
+@pytest.mark.parametrize(
+    "params",
+    [
+        {},
+        {"format": "letters"},
+        {"interpret_as": ""},
+        {"interpret_as": 1},
+        {"interpret_as": "characters", "format": ""},
+        {"interpret_as": "characters", "detail": False},
+        {"interpret_as": "characters", "detail": ""},
+        {"interpret_as": "characters", "unexpected": "value"},
+    ],
+)
+def test_say_as_control_rejects_invalid_standard_parameters(params: dict[str, Any]) -> None:
+    with pytest.raises(ValidationError, match="say_as"):
+        SpeechControl(0, 5, "say_as", params)
+
+
+def test_say_as_standard_constants_and_future_interpretations() -> None:
+    assert CONTROL_SAY_AS == "say_as"
+    assert CONTROL_EMPHASIS == "emphasis"
+    assert CONTROL_PRONUNCIATION == "pronunciation"
+    assert CONTROL_PROSODY == "prosody"
+    assert SAY_AS_CHARACTERS == "characters"
+    control = SpeechControl(
+        0,
+        5,
+        CONTROL_SAY_AS,
+        {"interpret_as": "date", "format": "dd.mm.yyyy", "detail": "1"},
+    )
+    assert control.params["interpret_as"] == "date"
+
+
+def test_say_as_characters_roundtrip_preserves_sentence_text_and_flow(tmp_path: Path) -> None:
+    text = "Because someone called A R T finally."
+    start = text.index("A R T")
+    control = SpeechControl(
+        start,
+        start + len("A R T"),
+        CONTROL_SAY_AS,
+        {"interpret_as": SAY_AS_CHARACTERS},
+    )
+    value = plan(speech(text=text, controls=(control,)))
+    path = tmp_path / "say-as.renderplan.toml"
+    save_plan(value, path)
+    loaded = load_plan(path)
+
+    assert len(loaded.flow) == 1
+    assert len(loaded.speech) == 1
+    restored = loaded.speech[0]
+    restored_control = restored.controls[0]
+    assert restored.text == text
+    assert restored.text[restored_control.start : restored_control.end] == "A R T"
+    assert restored_control.name == CONTROL_SAY_AS
+    assert restored_control.params["interpret_as"] == SAY_AS_CHARACTERS
+    assert restored.planning_level == "sentence"
+    assert not any(isinstance(item, PauseItem) for item in loaded.flow)
+    assert "A- R- T" not in path.read_text(encoding="utf-8")
+
+
+@pytest.mark.parametrize(
+    ("text", "possessive"),
+    [
+        ("A R T's house is nice.", "'s"),
+        ("A R T’s house is nice.", "’s"),
+    ],
+)
+def test_say_as_control_excludes_possessive_suffix(text: str, possessive: str) -> None:
+    start = text.index("A R T")
+    end = start + len("A R T")
+    control = SpeechControl(start, end, CONTROL_SAY_AS, {"interpret_as": SAY_AS_CHARACTERS})
+    item = speech(text=text, controls=(control,))
+
+    assert item.text[control.start : control.end] == "A R T"
+    assert item.text[control.end :].startswith(possessive)
+
+
 def test_leading_pause_is_legal() -> None:
     item = speech()
     value = plan(flow=(PauseItem(120, "authored"), item))

{renderplan-0.1.3 → renderplan-0.1.4}/tests/test_identity.py

@@ -7,6 +7,7 @@ from renderplan import (
     RenderProfile,
     RoleProfile,
     SourceSpan,
+    SpeechControl,
     SpeechItem,
 )
 
@@ -43,6 +44,23 @@ def test_speech_request_identity_excludes_number_and_provenance() -> None:
     assert first.segment_id == renumbered.segment_id == different_source.segment_id
 
 
+def test_say_as_control_changes_speech_request_identity() -> None:
+    plain = replace(
+        speech(),
+        text="A R T",
+        source=(SourceSpan("f000000.s000", 0, 5),),
+        segment_id=None,
+    ).with_identity()
+    controlled = replace(
+        plain,
+        controls=(SpeechControl(0, 5, "say_as", {"interpret_as": "characters"}),),
+        segment_id=None,
+    ).with_identity()
+
+    assert plain.text == controlled.text == "A R T"
+    assert plain.segment_id != controlled.segment_id
+
+
 def test_pause_is_part_of_plan_identity() -> None:
     item = speech()
     p1 = RenderPlan(SOURCE, PROFILE_ID, (item, PauseItem(100, "sentence"))).with_identity()

renderplan-0.1.3/renderplan.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.3",
-  "distance": 0,
-  "node": "g3d1e5588ab31de2474b94f84e17e9a44721ae3d2",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-25"
-}