transcribe-cpp 0.2.1__tar.gz → 0.2.2__tar.gz

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: transcribe-cpp
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python bindings for transcribe.cpp
 Project-URL: Homepage, https://github.com/handy-computer/transcribe.cpp
 Project-URL: Repository, https://github.com/handy-computer/transcribe.cpp
@@ -21,9 +21,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9
-Requires-Dist: transcribe-cpp-native==0.2.1.*
+Requires-Dist: transcribe-cpp-native==0.2.2.*
 Provides-Extra: cu12
-Requires-Dist: transcribe-cpp-native-cu12==0.2.1.*; extra == 'cu12'
+Requires-Dist: transcribe-cpp-native-cu12==0.2.2.*; extra == 'cu12'
 Provides-Extra: test
 Requires-Dist: numpy; extra == 'test'
 Requires-Dist: pytest>=7; extra == 'test'
@@ -62,6 +62,18 @@ pcm = np.asarray(audio, dtype=np.float32)   # 1-D, 16 kHz mono
 result = session.run(pcm)
 ```
 
+### Punctuation, capitalization, and text normalization
+
+Generic run controls use `"default"` to preserve each model family's shipped
+behavior. Models advertising `model.supports("pnc")` accept `pnc="off"` or
+`pnc="on"`; models advertising `model.supports("itn")` accept the equivalent
+`itn` values. The options are available on `run()`, `run_batch()`, `stream()`,
+and the one-shot `transcribe()` helper.
+
+```python
+result = session.run(pcm, pnc="off", itn="on")
+```
+
 Streaming models expose incremental transcription with committed/tentative
 text views — see `examples/stream_wav.py`:
 
@@ -71,6 +83,7 @@ with model.session() as session, session.stream() as stream:
         stream.feed(chunk)
         text = stream.text()        # .committed (stable) + .tentative
     stream.finalize()
+    result = stream.snapshot()      # language, segments, words, tokens, timings
 ```
 
 Long transcriptions can be cancelled from another thread with

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/README.md

@@ -31,6 +31,18 @@ pcm = np.asarray(audio, dtype=np.float32)   # 1-D, 16 kHz mono
 result = session.run(pcm)
 ```
 
+### Punctuation, capitalization, and text normalization
+
+Generic run controls use `"default"` to preserve each model family's shipped
+behavior. Models advertising `model.supports("pnc")` accept `pnc="off"` or
+`pnc="on"`; models advertising `model.supports("itn")` accept the equivalent
+`itn` values. The options are available on `run()`, `run_batch()`, `stream()`,
+and the one-shot `transcribe()` helper.
+
+```python
+result = session.run(pcm, pnc="off", itn="on")
+```
+
 Streaming models expose incremental transcription with committed/tentative
 text views — see `examples/stream_wav.py`:
 
@@ -40,6 +52,7 @@ with model.session() as session, session.stream() as stream:
         stream.feed(chunk)
         text = stream.text()        # .committed (stable) + .tentative
     stream.finalize()
+    result = stream.snapshot()      # language, segments, words, tokens, timings
 ```
 
 Long transcriptions can be cancelled from another thread with

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcribe-cpp"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python bindings for transcribe.cpp"
 readme = "README.md"
 # 3.8 is EOL (2024-10); 3.9 is the floor. The binding is ctypes-only, so there
@@ -34,13 +34,13 @@ classifiers = [
 # packaging fix still resolves); the import-time version/header-hash check in
 # _library.py is the runtime backstop. check_version_sync.py gates this pin
 # against include/transcribe.h.
-dependencies = ["transcribe-cpp-native==0.2.1.*"]
+dependencies = ["transcribe-cpp-native==0.2.2.*"]
 
 [project.optional-dependencies]
 # Opt-in accelerator providers — ADDITIVE: they install alongside the default
 # provider and the best one wins at runtime. Same base-version pin contract
 # as the hard dependency (gated by check_version_sync.py).
-cu12 = ["transcribe-cpp-native-cu12==0.2.1.*"]
+cu12 = ["transcribe-cpp-native-cu12==0.2.2.*"]
 # Test-only deps. Run with: uv run --extra test pytest (from bindings/python).
 # numpy is here so the numpy PCM-input tests run in every lane instead of
 # silently skipping wherever numpy happens to be absent.

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/src/transcribe_cpp/__init__.py

@@ -46,13 +46,15 @@ from .errors import (
     raise_for_status,
 )
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 # String-enum types, exported so callers (and type checkers) can name them.
 Backend = Literal["auto", "cpu", "metal", "vulkan", "cpu_accel", "cuda", "rocm"]
 KVType = Literal["auto", "f32", "f16"]
 Task = Literal["transcribe", "translate"]
 Timestamps = Literal["none", "auto", "segment", "word", "token"]
+Pnc = Literal["default", "off", "on"]
+Itn = Literal["default", "off", "on"]
 Diarize = Literal["default", "off", "on"]
 SortformerPreset = Literal["default", "very_high_latency", "high_latency", "low_latency"]
 CommitPolicy = Literal["auto", "on_finalize", "stable_prefix"]
@@ -89,6 +91,8 @@ __all__ = [
     "KVType",
     "Task",
     "Timestamps",
+    "Pnc",
+    "Itn",
     "Diarize",
     "CommitPolicy",
     "Feature",
@@ -206,6 +210,16 @@ _TIMESTAMPS = {
     "token": _generated.TRANSCRIBE_TIMESTAMPS_TOKEN,
 }
 _TIMESTAMP_NAMES = {v: k for k, v in _TIMESTAMPS.items()}
+_PNC = {
+    "default": _generated.TRANSCRIBE_PNC_MODE_DEFAULT,
+    "off": _generated.TRANSCRIBE_PNC_MODE_OFF,
+    "on": _generated.TRANSCRIBE_PNC_MODE_ON,
+}
+_ITN = {
+    "default": _generated.TRANSCRIBE_ITN_MODE_DEFAULT,
+    "off": _generated.TRANSCRIBE_ITN_MODE_OFF,
+    "on": _generated.TRANSCRIBE_ITN_MODE_ON,
+}
 _DIARIZE = {
     "default": _generated.TRANSCRIBE_DIARIZE_MODE_DEFAULT,
     "off": _generated.TRANSCRIBE_DIARIZE_MODE_OFF,
@@ -638,7 +652,8 @@ def _stream_update_from(u) -> StreamUpdate:
 
 
 def _build_run_params(task, language, target_language, timestamps,
-                      keep_special_tags, spec_k_drafts, diarize="default"):
+                      keep_special_tags, spec_k_drafts, diarize="default",
+                      pnc="default", itn="default"):
     if not isinstance(spec_k_drafts, int) or spec_k_drafts < -1:
         raise InvalidArgument(
             f"spec_k_drafts must be -1 (family default), 0 (disabled), or a "
@@ -648,6 +663,8 @@ def _build_run_params(task, language, target_language, timestamps,
     _lib.transcribe_run_params_init(_byref(params))
     params.task = _enum(_TASKS, task, "task")
     params.timestamps = _enum(_TIMESTAMPS, timestamps, "timestamps")
+    params.pnc = _enum(_PNC, pnc, "pnc")
+    params.itn = _enum(_ITN, itn, "itn")
     params.diarize = _enum(_DIARIZE, diarize, "diarize")
     params.language = language.encode("utf-8") if language else None
     params.target_language = target_language.encode("utf-8") if target_language else None
@@ -1079,12 +1096,16 @@ class Session:
             language: str | None = None,
             target_language: str | None = None,
             timestamps: Timestamps = "auto",
+            pnc: Pnc = "default",
+            itn: Itn = "default",
             diarize: Diarize = "default",
             keep_special_tags: bool = False,
             spec_k_drafts: int = -1,
             family: FamilyExtension | None = None) -> Result:
         """Transcribe 16 kHz mono float32 PCM and return a materialized Result.
 
+        ``pnc`` controls punctuation/capitalization and ``itn`` controls
+        inverse text normalization on models advertising those features.
         ``family`` is an optional family-specific extension (e.g.
         WhisperRunOptions) carrying per-run knobs for models that accept it.
         ``spec_k_drafts`` tunes speculative decoding on models whose
@@ -1097,7 +1118,7 @@ class Session:
         self._cancel.clear()
         array, n_samples = _pcm_to_carray(pcm)
         params = _build_run_params(task, language, target_language, timestamps,
-                                   keep_special_tags, spec_k_drafts, diarize)
+                                   keep_special_tags, spec_k_drafts, diarize, pnc, itn)
         ext = self._resolve_family(family, "run") if family is not None else None
         if ext is not None:
             params.family = ctypes.cast(
@@ -1116,6 +1137,8 @@ class Session:
                   language: str | None = None,
                   target_language: str | None = None,
                   timestamps: Timestamps = "auto",
+                  pnc: Pnc = "default",
+                  itn: Itn = "default",
                   diarize: Diarize = "default",
                   keep_special_tags: bool = False,
                   spec_k_drafts: int = -1,
@@ -1153,7 +1176,7 @@ class Session:
             counts[k] = n
 
         params = _build_run_params(task, language, target_language, timestamps,
-                                   keep_special_tags, spec_k_drafts, diarize)
+                                   keep_special_tags, spec_k_drafts, diarize, pnc, itn)
         ext = self._resolve_family(family, "run") if family is not None else None
         if ext is not None:
             params.family = ctypes.cast(
@@ -1204,6 +1227,7 @@ class Session:
 
     def stream(self, *, task: Task = "transcribe", language: str | None = None,
                target_language: str | None = None, timestamps: Timestamps = "none",
+               pnc: Pnc = "default", itn: Itn = "default",
                diarize: Diarize = "default",
                keep_special_tags: bool = False, commit_policy: CommitPolicy = "auto",
                stable_prefix_agreement_n: int = 0,
@@ -1219,7 +1243,7 @@ class Session:
         # spec_k_drafts is an offline-decode knob; streaming always uses the
         # family default (-1).
         run_params = _build_run_params(task, language, target_language, timestamps,
-                                       keep_special_tags, -1, diarize)
+                                       keep_special_tags, -1, diarize, pnc, itn)
         sp = _StreamParams()
         _lib.transcribe_stream_params_init(_byref(sp))
         sp.commit_policy = _enum(_COMMIT_POLICIES, commit_policy, "commit_policy")
@@ -1413,6 +1437,11 @@ class Stream:
             tentative=_decode(txt.tentative_text),
         )
 
+    def snapshot(self) -> Result:
+        """Full structured snapshot of the current hypothesis (owned copies)."""
+        _ = self._h  # validate that this stream has not been reset
+        return self._session._materialize()
+
     @property
     def state(self) -> str:
         """``"idle"`` / ``"active"`` / ``"finished"`` / ``"failed"``."""
@@ -1461,6 +1490,8 @@ def transcribe(
     language: str | None = None,
     target_language: str | None = None,
     timestamps: Timestamps = "auto",
+    pnc: Pnc = "default",
+    itn: Itn = "default",
     diarize: Diarize = "default",
     keep_special_tags: bool = False,
     spec_k_drafts: int = -1,
@@ -1477,7 +1508,7 @@ def transcribe(
     """
     session_opts = dict(n_threads=n_threads, kv_type=kv_type, n_ctx=n_ctx)
     run_opts = dict(task=task, language=language, target_language=target_language,
-                    timestamps=timestamps, diarize=diarize,
+                    timestamps=timestamps, pnc=pnc, itn=itn, diarize=diarize,
                     keep_special_tags=keep_special_tags,
                     spec_k_drafts=spec_k_drafts, family=family)
 

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/tests/conftest.py

@@ -59,6 +59,8 @@ VOXTRAL_MODEL = (
     REPO
     / "models/Voxtral-Mini-4B-Realtime-2602/Voxtral-Mini-4B-Realtime-2602-Q4_K_M.gguf"
 )
+PNC_MODEL = REPO / "models/canary-180m-flash/canary-180m-flash-Q8_0.gguf"
+ITN_MODEL = REPO / "models/SenseVoiceSmall/SenseVoiceSmall-Q8_0.gguf"
 
 
 def load_wav(path: Path) -> "array.array":
@@ -157,3 +159,15 @@ def parakeet_buffered_model_path() -> Path:
 def voxtral_model_path() -> Path:
     """Voxtral realtime streaming canary (accepts VOXTRAL_REALTIME_STREAM)."""
     return _family_model("TRANSCRIBE_SMOKE_VOXTRAL_MODEL", VOXTRAL_MODEL)
+
+
+@pytest.fixture(scope="session")
+def pnc_model_path() -> Path:
+    """Canary model whose generic PNC run parameter changes the prompt."""
+    return _family_model("TRANSCRIBE_SMOKE_PNC_MODEL", PNC_MODEL)
+
+
+@pytest.fixture(scope="session")
+def itn_model_path() -> Path:
+    """SenseVoice model whose generic ITN parameter changes text normalization."""
+    return _family_model("TRANSCRIBE_SMOKE_ITN_MODEL", ITN_MODEL)

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/tests/test_errors.py

@@ -13,6 +13,8 @@ Two layers, both model-free:
 
 from __future__ import annotations
 
+import inspect
+
 import pytest
 
 import transcribe_cpp as t
@@ -102,3 +104,53 @@ def test_invalid_spec_k_drafts_rejected_before_native_call():
         _build_run_params("transcribe", None, None, "none", False, -2)
     with pytest.raises(t.InvalidArgument, match="spec_k_drafts"):
         _build_run_params("transcribe", None, None, "none", False, "many")
+
+
+def test_pnc_and_itn_modes_map_to_native_run_params():
+    from transcribe_cpp import _build_run_params, _generated
+
+    modes = {
+        "default": (
+            _generated.TRANSCRIBE_PNC_MODE_DEFAULT,
+            _generated.TRANSCRIBE_ITN_MODE_DEFAULT,
+        ),
+        "off": (
+            _generated.TRANSCRIBE_PNC_MODE_OFF,
+            _generated.TRANSCRIBE_ITN_MODE_OFF,
+        ),
+        "on": (
+            _generated.TRANSCRIBE_PNC_MODE_ON,
+            _generated.TRANSCRIBE_ITN_MODE_ON,
+        ),
+    }
+    for mode, (pnc, itn) in modes.items():
+        params = _build_run_params(
+            "transcribe", None, None, "none", False, -1, pnc=mode, itn=mode
+        )
+        assert params.pnc == pnc
+        assert params.itn == itn
+
+    for name in ("pnc", "itn"):
+        with pytest.raises(t.InvalidArgument, match=name):
+            _build_run_params(
+                "transcribe", None, None, "none", False, -1, **{name: "maybe"}
+            )
+
+
+def test_public_run_surfaces_cover_every_generic_option():
+    common = {
+        "task", "language", "target_language", "timestamps", "pnc", "itn",
+        "diarize", "keep_special_tags", "family",
+    }
+    expected = {
+        t.Session.run: common | {"spec_k_drafts"},
+        t.Session.run_batch: common | {"spec_k_drafts"},
+        # Speculative decoding is explicitly offline-only.
+        t.Session.stream: common,
+        t.transcribe: common | {"spec_k_drafts"},
+    }
+    for callable_, required in expected.items():
+        parameters = inspect.signature(callable_).parameters
+        assert required <= parameters.keys()
+    assert "Pnc" in t.__all__
+    assert "Itn" in t.__all__

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/tests/test_streaming.py

@@ -29,6 +29,7 @@ def test_streaming_real(streaming_model_path, audio_pcm):
                 stream.feed(audio_pcm[i : i + 16000])
             update = stream.finalize()
             committed = stream.text().committed
+            snapshot = stream.snapshot()
             revision, state = stream.revision, stream.state
             last_status = stream.last_status
     assert update.is_final, update
@@ -36,6 +37,11 @@ def test_streaming_real(streaming_model_path, audio_pcm):
     assert revision >= 1
     assert last_status is None, last_status
     assert "country" in committed.lower(), committed
+    assert snapshot.text
+    assert isinstance(snapshot.language, str)
+    assert snapshot.segments
+    assert isinstance(snapshot.words, tuple)
+    assert isinstance(snapshot.tokens, tuple)
 
 
 def test_streaming_with_language_hint(prompted_streaming_model_path, audio_pcm):
@@ -122,6 +128,8 @@ def test_stream_use_after_reset_rejected(streaming_model_path, audio_pcm):
             stream.feed(audio_pcm[:16000])
         with pytest.raises(t.TranscribeError, match="reset"):
             stream.text()
+        with pytest.raises(t.TranscribeError, match="reset"):
+            stream.snapshot()
 
 
 def test_stream_reset_idempotent_and_session_reusable(

transcribe_cpp-0.2.2/tests/test_text_controls.py

@@ -0,0 +1,28 @@
+"""Model-gated generic punctuation/capitalization and ITN controls."""
+
+import transcribe_cpp as t
+
+
+def test_pnc_changes_canary_prompt(pnc_model_path, audio_pcm):
+    with t.Model(pnc_model_path, backend="cpu") as model, model.session() as session:
+        assert model.supports("pnc")
+        default = session.run(audio_pcm, language="en", pnc="default").text
+        enabled = session.run(audio_pcm, language="en", pnc="on").text
+        disabled = session.run(audio_pcm, language="en", pnc="off").text
+
+    assert default == enabled
+    assert disabled != enabled
+    assert disabled == disabled.lower()
+
+
+def test_itn_changes_sensevoice_text_normalization(itn_model_path, audio_pcm):
+    with t.Model(itn_model_path, backend="cpu") as model, model.session() as session:
+        assert model.supports("itn")
+        default = session.run(audio_pcm, language="en", itn="default")
+        disabled = session.run(audio_pcm, language="en", itn="off")
+        enabled = session.run(audio_pcm, language="en", itn="on")
+
+    assert (default.text, default.raw_text) == (disabled.text, disabled.raw_text)
+    assert enabled.text != disabled.text
+    assert "<|woitn|>" in disabled.raw_text
+    assert "<|withitn|>" in enabled.raw_text

{transcribe_cpp-0.2.1 → transcribe_cpp-0.2.2}/uv.lock

@@ -386,7 +386,7 @@ wheels = [
 
 [[package]]
 name = "transcribe-cpp"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 
 [package.optional-dependencies]
@@ -402,8 +402,8 @@ test = [
 requires-dist = [
     { name = "numpy", marker = "extra == 'test'" },
     { name = "pytest", marker = "extra == 'test'", specifier = ">=7" },
-    { name = "transcribe-cpp-native", specifier = "==0.2.1.*" },
-    { name = "transcribe-cpp-native-cu12", marker = "extra == 'cu12'", specifier = "==0.2.1.*" },
+    { name = "transcribe-cpp-native", specifier = "==0.2.2.*" },
+    { name = "transcribe-cpp-native-cu12", marker = "extra == 'cu12'", specifier = "==0.2.2.*" },
 ]
 
 [[package]]