readio 0.3.2__tar.gz → 0.3.3__tar.gz

{readio-0.3.2 → readio-0.3.3}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -101,3 +101,9 @@
 {"data":{"updated_rows":2},"event":"audit.updated","event_id":"event-0101","record_revisions":{"commit_audit_sheet":4},"release_version":"v0.3.2","schema_version":2}
 {"data":{"entry_ids":["entry-0003"],"synced_audit_rows":2},"event":"entry.batch_added","event_id":"event-0102","record_revisions":{"commit_audit_sheet":5,"entry:v0.3.2/entry-0003":1,"release:v0.3.2":4},"release_version":"v0.3.2","schema_version":2}
 {"data":{"released_at":"2026-09-28"},"event":"release.finalized","event_id":"event-0103","record_revisions":{"release:v0.3.2":5},"release_version":"v0.3.2","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0104","record_revisions":{"release:v0.3.3":1},"release_version":"v0.3.3","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-0105","record_revisions":{"release:v0.3.3":2},"release_version":"v0.3.3","schema_version":2}
+{"data":{"row_count":2},"event":"audit.created","event_id":"event-0106","record_revisions":{"commit_audit_sheet":1},"release_version":"v0.3.3","schema_version":2}
+{"data":{"updated_rows":2},"event":"audit.updated","event_id":"event-0107","record_revisions":{"commit_audit_sheet":2},"release_version":"v0.3.3","schema_version":2}
+{"data":{"entry_ids":["entry-0001","entry-0002"],"synced_audit_rows":2},"event":"entry.batch_added","event_id":"event-0108","record_revisions":{"commit_audit_sheet":3,"entry:v0.3.3/entry-0001":1,"entry:v0.3.3/entry-0002":1,"release:v0.3.3":3},"release_version":"v0.3.3","schema_version":2}
+{"data":{"released_at":"2026-09-28"},"event":"release.finalized","event_id":"event-0109","record_revisions":{"release:v0.3.3":4},"release_version":"v0.3.3","schema_version":2}

readio-0.3.3/.ledger/releaseledger/data/ledgers/main/releases/v0.3.3/audit/commit-audit.yaml

@@ -0,0 +1,80 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 3
+release_version: v0.3.3
+git_base_ref: v0.3.2
+git_base_sha: fcf02b93783d26ec02252791a1642ea7bb3cc26a
+git_head_ref: HEAD
+git_head_sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+git_range: fcf02b93783d26ec02252791a1642ea7bb3cc26a..05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+commit_count: 2
+rows:
+  - sha: 3dbc57bc393a396c67606b36fbde0960b5347187
+    source_ref: git:3dbc57bc393a396c67606b36fbde0960b5347187
+    short_sha: 3dbc57b
+    changed_paths:
+      - README.md
+      - docs/cli.md
+      - pyproject.toml
+      - readio/cli.py
+      - readio/cli_help.py
+      - readio/spotify_cli.py
+      - tests/test_cli_help.py
+      - tests/test_voice_catalog.py
+    stats:
+      files_changed: 8
+      insertions: 515
+      deletions: 58
+    inspected: true
+    inspected_paths:
+      - README.md
+      - docs/cli.md
+      - pyproject.toml
+      - readio/cli.py
+      - readio/cli_help.py
+      - readio/spotify_cli.py
+      - tests/test_cli_help.py
+      - tests/test_voice_catalog.py
+    observed_behavior:
+      Added formatted root and command-group help, plus engine and
+      output-format discovery commands with JSON output; documented the CLI behavior
+      and covered it with tests.
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: better cli help"
+    target_entry_id: entry-0001
+    notes: ""
+  - sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    source_ref: git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    short_sha: 05f8940
+    changed_paths:
+      - docs/api.md
+      - readio/api/projects.py
+      - readio/api/types.py
+      - tests/test_public_api_projects.py
+      - tests/test_public_api_types.py
+    stats:
+      files_changed: 5
+      insertions: 125
+      deletions: 2
+    inspected: true
+    inspected_paths:
+      - docs/api.md
+      - readio/api/projects.py
+      - readio/api/types.py
+      - tests/test_public_api_projects.py
+      - tests/test_public_api_types.py
+    observed_behavior:
+      Exposed resolved pronunciation, lexicon, and language-detection
+      settings through the read-only synthesis preflight result, preserving automatic
+      versus explicitly empty lexicon selections; documented the behavior and added
+      tests.
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: add missing parameter to api"
+    target_entry_id: entry-0002
+    notes: ""

readio-0.3.3/.ledger/releaseledger/data/ledgers/main/releases/v0.3.3/entries/entry-0001.md

@@ -0,0 +1,36 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: v0.3.3
+kind: added
+summary:
+  Added formatted command help and engine and output-format discovery to the
+  CLI
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:3dbc57bc393a396c67606b36fbde0960b5347187
+paths:
+  - README.md
+  - docs/cli.md
+  - pyproject.toml
+  - readio/cli.py
+  - readio/cli_help.py
+  - readio/spotify_cli.py
+  - tests/test_cli_help.py
+  - tests/test_voice_catalog.py
+issues: []
+prs: []
+sources:
+  - git:3dbc57bc393a396c67606b36fbde0960b5347187
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 1
+---

readio-0.3.3/.ledger/releaseledger/data/ledgers/main/releases/v0.3.3/entries/entry-0002.md

@@ -0,0 +1,33 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0002
+release_version: v0.3.3
+kind: added
+summary:
+  Added lexicon, pronunciation, and language-detection policies to the read-only
+  synthesis preflight API
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+paths:
+  - docs/api.md
+  - readio/api/projects.py
+  - readio/api/types.py
+  - tests/test_public_api_projects.py
+  - tests/test_public_api_types.py
+issues: []
+prs: []
+sources:
+  - git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 2
+---

readio-0.3.3/.ledger/releaseledger/data/ledgers/main/releases/v0.3.3/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 4
+version: v0.3.3
+status: released
+history_state: curated
+title: null
+released_at: "2026-09-28"
+previous_version: v0.3.2
+cancel_reason: null
+superseded_by: null
+changelog_file: docs/changelog.md
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 2
+artifact_count: 0
+git_base_ref: v0.3.2
+git_base_sha: fcf02b93783d26ec02252791a1642ea7bb3cc26a
+git_head_ref: HEAD
+git_head_sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+git_range: fcf02b93783d26ec02252791a1642ea7bb3cc26a..05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+git_commit_count: 2
+---

readio-0.3.3/.ledger/releaseledger/work/v0.3.3/audit-decisions.yaml

@@ -0,0 +1,34 @@
+rows:
+  - sha: 3dbc57bc393a396c67606b36fbde0960b5347187
+    inspected: true
+    inspected_paths:
+      - README.md
+      - docs/cli.md
+      - pyproject.toml
+      - readio/cli.py
+      - readio/cli_help.py
+      - readio/spotify_cli.py
+      - tests/test_cli_help.py
+      - tests/test_voice_catalog.py
+    observed_behavior: Added formatted root and command-group help, plus engine and output-format discovery commands with JSON output; documented the CLI behavior and covered it with tests.
+    public_impact: public
+    decision: accepted
+    target_entry_key: null
+    target_entry_id: null
+    notes: ""
+    stale: false
+  - sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    inspected: true
+    inspected_paths:
+      - docs/api.md
+      - readio/api/projects.py
+      - readio/api/types.py
+      - tests/test_public_api_projects.py
+      - tests/test_public_api_types.py
+    observed_behavior: Exposed resolved pronunciation, lexicon, and language-detection settings through the read-only synthesis preflight result, preserving automatic versus explicitly empty lexicon selections; documented the behavior and added tests.
+    public_impact: public
+    decision: accepted
+    target_entry_key: null
+    target_entry_id: null
+    notes: ""
+    stale: false

readio-0.3.3/.ledger/releaseledger/work/v0.3.3/audit.yaml

@@ -0,0 +1,56 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 1
+release_version: v0.3.3
+git_base_ref: v0.3.2
+git_base_sha: fcf02b93783d26ec02252791a1642ea7bb3cc26a
+git_head_ref: HEAD
+git_head_sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+git_range: fcf02b93783d26ec02252791a1642ea7bb3cc26a..05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+commit_count: 2
+rows:
+  - sha: 3dbc57bc393a396c67606b36fbde0960b5347187
+    source_ref: git:3dbc57bc393a396c67606b36fbde0960b5347187
+    short_sha: 3dbc57b
+    changed_paths:
+      - README.md
+      - docs/cli.md
+      - pyproject.toml
+      - readio/cli.py
+      - readio/cli_help.py
+      - readio/spotify_cli.py
+      - tests/test_cli_help.py
+      - tests/test_voice_catalog.py
+    stats:
+      files_changed: 8
+      insertions: 515
+      deletions: 58
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: better cli help"
+  - sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    source_ref: git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    short_sha: 05f8940
+    changed_paths:
+      - docs/api.md
+      - readio/api/projects.py
+      - readio/api/types.py
+      - tests/test_public_api_projects.py
+      - tests/test_public_api_types.py
+    stats:
+      files_changed: 5
+      insertions: 125
+      deletions: 2
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: add missing parameter to api"

readio-0.3.3/.ledger/releaseledger/work/v0.3.3/entries.yaml

@@ -0,0 +1,48 @@
+schema: releaseledger.entry-batch.v1
+operation: create
+schema_version: 1
+object_type: release_entry_batch
+release_version: v0.3.3
+git_base_ref: fcf02b93783d26ec02252791a1642ea7bb3cc26a
+git_base_sha: fcf02b93783d26ec02252791a1642ea7bb3cc26a
+git_head_ref: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+git_head_sha: 05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+include_merges: nontrivial
+entries:
+  - kind: added
+    summary: Added formatted command help and engine and output-format discovery to the CLI
+    status: accepted
+    source_refs:
+      - git:3dbc57bc393a396c67606b36fbde0960b5347187
+    paths:
+      - README.md
+      - docs/cli.md
+      - pyproject.toml
+      - readio/cli.py
+      - readio/cli_help.py
+      - readio/spotify_cli.py
+      - tests/test_cli_help.py
+      - tests/test_voice_catalog.py
+    sources:
+      - git:3dbc57bc393a396c67606b36fbde0960b5347187
+    prs: []
+    issues: []
+    contributors:
+      - "@holgern"
+  - kind: added
+    summary: Added lexicon, pronunciation, and language-detection policies to the read-only synthesis preflight API
+    status: accepted
+    source_refs:
+      - git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    paths:
+      - docs/api.md
+      - readio/api/projects.py
+      - readio/api/types.py
+      - tests/test_public_api_projects.py
+      - tests/test_public_api_types.py
+    sources:
+      - git:05f8940cb8d3e1aa3eab6c26eacc3912ba89e36d
+    prs: []
+    issues: []
+    contributors:
+      - "@holgern"

readio-0.3.3/.ledger/releaseledger/work/v0.3.3/evidence/05f8940.patch

@@ -0,0 +1,211 @@
+ docs/api.md                       |  6 ++--
+ readio/api/projects.py            | 14 ++++++++++
+ readio/api/types.py               |  6 ++++
+ tests/test_public_api_projects.py | 43 +++++++++++++++++++++++++++++
+ tests/test_public_api_types.py    | 58 +++++++++++++++++++++++++++++++++++++++
+ 5 files changed, 125 insertions(+), 2 deletions(-)
+
+diff --git a/docs/api.md b/docs/api.md
+index 36229ca..31a4453 100644
+--- a/docs/api.md
++++ b/docs/api.md
+@@ -132,9 +132,11 @@ build = app.projects.build(project, ProjectBuildRequest(target="export"))
+ `app.audiobooks.inspect(epub_path)` returns typed EPUB metadata and chapters. `create_project()` creates an ordinary Readio project; `create_project_result()` additionally returns the selected chapter numbers and scope IDs. `app.audiobooks.export(project, AudiobookExportOptions(...))` writes M4B with chapters using the audiobook-specific API. `SUPPORTED_AUDIOBOOK_FORMATS` contains `m4b`; it is intentionally not in generic `SUPPORTED_AUDIO_FORMATS`.
+ `describe_project(project)` describes an existing audiobook after reopening it. The immutable `AudiobookProjectDescription` contains its `ProjectRef`, persisted source path, and persisted `AudiobookProjectChapter` values (chapter number, scope ID, title, and level). Readio loads the project and validates its kind; consumers do not need to inspect project files.
+
+-`app.projects.resolve_synthesis(project, request=None, *, voice_bindings=None)` returns a typed `SynthesisResolution` with effective engine, language, voice, model, model source, quality, speed, unit, pause mode, voice level, and supported planning/provider settings. It uses the same project synthesis resolver as `synthesize()`: fatal choices raise public API errors, and non-fatal resolver diagnostics are returned on the result.
++`app.projects.resolve_synthesis(project, request=None, *, voice_bindings=None)` returns a typed `SynthesisResolution` with effective engine, language, voice, model, model source, quality, speed, unit, pause mode, voice level, planning/provider settings, and pronunciation/resource policies: lexicons, G2P fallback, lexicon data policy, language-detection mode and languages, and experimental-option permission. It uses the same project synthesis resolver as `synthesize()`: fatal choices raise public API errors, and non-fatal resolver diagnostics are returned on the result.
+
+-Resolution is for preflight, validation, and UI display. It does not render audio, open an engine session, activate a profile, or mutate persistent synthesis/build state. It reports the same effective selection semantics used by actual project synthesis.
++`lexicons` preserves three states: `None` means automatic or inherited behavior, an empty tuple means static lexicon layers were explicitly disabled, and a non-empty tuple lists selected layers. These fields expose resolved request/profile values; preflight does not materialize backend runtime defaults that were not resolved.
++
++Resolution is read-only and intended for preflight, validation, and UI display. It does not render audio, open an engine session, activate a profile, or mutate project configuration, profile files, manifests, caches, audio, role bindings, or persistent synthesis/build state. It reports the same effective selection semantics used by actual project synthesis.
+
+ ```python
+ from pathlib import Path
+diff --git a/readio/api/projects.py b/readio/api/projects.py
+index e72cb82..4cab874 100644
+--- a/readio/api/projects.py
++++ b/readio/api/projects.py
+@@ -91,6 +91,14 @@ _OPERATION_DETAIL_KEYS = frozenset(
+ )
+
+
++def _optional_string_tuple(value: object) -> tuple[str, ...] | None:
++    if value is None:
++        return None
++    if isinstance(value, (tuple, list)):
++        return tuple(str(item) for item in value)
++    raise TypeError(f"expected a list or tuple, got {type(value).__name__}")
++
++
+ class ProjectService:
+     """Create, inspect, plan, and incrementally build persistent projects."""
+
+@@ -215,6 +223,12 @@ class ProjectService:
+             spacy=resolved.plan.planning.spacy,
+             short_sentence=cast(str | None, options.get("short_sentence")),
+             provider=adapter.capabilities().voice_binding_namespace,
++            lexicons=_optional_string_tuple(options.get("lexicons")),
++            g2p_fallback=cast(str | None, options.get("g2p_fallback")),
++            lexicon_data_policy=cast(str | None, options.get("lexicon_data_policy")),
++            language_detection=cast(str | None, options.get("language_detection")),
++            detect_languages=_optional_string_tuple(options.get("detect_languages")),
++            allow_experimental=bool(options.get("allow_experimental", False)),
+             diagnostics=diagnostics,
+         )
+
+diff --git a/readio/api/types.py b/readio/api/types.py
+index bbf859e..37b0dcd 100644
+--- a/readio/api/types.py
++++ b/readio/api/types.py
+@@ -379,6 +379,12 @@ class SynthesisResolution:
+     short_sentence: str | None = None
+     provider: str | None = None
+     diagnostics: tuple[Diagnostic, ...] = ()
++    lexicons: tuple[str, ...] | None = None
++    g2p_fallback: str | None = None
++    lexicon_data_policy: str | None = None
++    language_detection: str | None = None
++    detect_languages: tuple[str, ...] | None = None
++    allow_experimental: bool = False
+
+     def to_dict(self) -> dict[str, JsonValue]:
+         return cast(dict[str, JsonValue], json_value(self))
+diff --git a/tests/test_public_api_projects.py b/tests/test_public_api_projects.py
+index ad24290..178f187 100644
+--- a/tests/test_public_api_projects.py
++++ b/tests/test_public_api_projects.py
+@@ -248,11 +248,54 @@ def test_resolve_synthesis_uses_profile_and_reader_settings_without_mutation(
+     assert resolution.pause_mode == "manual"
+     assert resolution.voice_level == "calibrated"
+     assert resolution.provider == "fake"
++    assert resolution.lexicons is None
+     assert adapter.open_calls == 0
+     assert _project_snapshot(project.root) == before
+     assert json.loads(json.dumps(resolution.to_dict()))["model"] == "profile-model"
+
+
++def test_resolve_synthesis_exposes_pronunciation_options_and_empty_lexicons(
++    tmp_path: Path, monkeypatch
++) -> None:
++    adapter = Adapter()
++    monkeypatch.setitem(_registry._adapters, "fake", adapter)
++    app = Readio(ReadioConfig(reader=ReaderSettings(engine="fake", voice="fake-voice")))
++    source = tmp_path / "pronunciation.txt"
++    source.write_text("Preflight pronunciation settings.", encoding="utf-8")
++    project = app.projects.create(source, output=tmp_path / "pronunciation.readio")
++    before = _project_snapshot(project.root)
++
++    request = SynthesisRequest(
++        engine="fake",
++        voice="fake-voice",
++        lexicons=("lex-a", "lex-b"),
++        g2p_fallback="espeak",
++        lexicon_data_policy="installed-only",
++        allow_experimental=True,
++        language_detection="auto",
++        detect_languages=("en-us", "de"),
++    )
++    resolution = app.projects.resolve_synthesis(project, request)
++
++    assert resolution.lexicons == ("lex-a", "lex-b")
++    assert resolution.g2p_fallback == "espeak"
++    assert resolution.lexicon_data_policy == "installed-only"
++    assert resolution.allow_experimental is True
++    assert resolution.language_detection == "auto"
++    assert resolution.detect_languages == ("en-us", "de")
++    assert isinstance(resolution.lexicons, tuple)
++    assert isinstance(resolution.detect_languages, tuple)
++    assert adapter.open_calls == 0
++    assert _project_snapshot(project.root) == before
++
++    no_lexicons = app.projects.resolve_synthesis(
++        project, SynthesisRequest(engine="fake", voice="fake-voice", lexicons=())
++    )
++    assert no_lexicons.lexicons == ()
++    assert adapter.open_calls == 0
++    assert _project_snapshot(project.root) == before
++
++
+ def test_resolve_synthesis_respects_request_overrides_and_voice_bindings(
+     tmp_path: Path, monkeypatch
+ ) -> None:
+diff --git a/tests/test_public_api_types.py b/tests/test_public_api_types.py
+index 8d4cae2..d2f6c46 100644
+--- a/tests/test_public_api_types.py
++++ b/tests/test_public_api_types.py
+@@ -87,15 +87,73 @@ def test_audiobook_and_synthesis_preflight_types_are_immutable_and_json_serializ
+         pause_mode="auto",
+         voice_level="off",
+         provider="kokoro",
++        lexicons=("lex-a", "lex-b"),
++        g2p_fallback="espeak",
++        lexicon_data_policy="installed-only",
++        language_detection="auto",
++        detect_languages=("en-us", "de"),
++        allow_experimental=True,
+     )
+
+     description_payload = json.loads(json.dumps(description.to_dict()))
+     resolution_payload = json.loads(json.dumps(resolution.to_dict()))
+     assert description_payload["chapters"][0]["scope_id"] == "chapter-0003"
+     assert resolution_payload["model_source"] == "github"
++    assert resolution_payload["lexicons"] == ["lex-a", "lex-b"]
++    assert resolution_payload["g2p_fallback"] == "espeak"
++    assert resolution_payload["lexicon_data_policy"] == "installed-only"
++    assert resolution_payload["language_detection"] == "auto"
++    assert resolution_payload["detect_languages"] == ["en-us", "de"]
++    assert resolution_payload["allow_experimental"] is True
+     with pytest.raises(FrozenInstanceError):
+         resolution.engine = "piper"  # type: ignore[misc]
+
++    legacy_resolution = SynthesisResolution(
++        engine="pykokoro",
++        language="en-us",
++        voice="af_heart",
++        model="kokoro-v1",
++        model_source="github",
++        quality="fp32",
++        speed=1.0,
++        unit="paragraph",
++        pause_mode="auto",
++        voice_level="off",
++    )
++    assert legacy_resolution.lexicons is None
++    assert legacy_resolution.g2p_fallback is None
++    assert legacy_resolution.lexicon_data_policy is None
++    assert legacy_resolution.language_detection is None
++    assert legacy_resolution.detect_languages is None
++    assert legacy_resolution.allow_experimental is False
++    assert set(legacy_resolution.to_dict()) >= {
++        "lexicons",
++        "g2p_fallback",
++        "lexicon_data_policy",
++        "language_detection",
++        "detect_languages",
++        "allow_experimental",
++    }
++
++    legacy_positional = SynthesisResolution(
++        "pykokoro",
++        "en-us",
++        "af_heart",
++        "kokoro-v1",
++        "github",
++        "fp32",
++        1.0,
++        "paragraph",
++        "auto",
++        "off",
++        None,
++        None,
++        None,
++        (),
++    )
++    assert legacy_positional.diagnostics == ()
++    assert legacy_positional.lexicons is None
++
+
+ def test_synthesis_engine_options_are_json_compatible_and_frozen() -> None:
+     request = SynthesisRequest(