transcribe-cpp 0.2.4__tar.gz → 0.3.1__tar.gz

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: transcribe-cpp
-Version: 0.2.4
+Version: 0.3.1
 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.4.*
+Requires-Dist: transcribe-cpp-native==0.3.1.*
 Provides-Extra: cu12
-Requires-Dist: transcribe-cpp-native-cu12==0.2.4.*; extra == 'cu12'
+Requires-Dist: transcribe-cpp-native-cu12==0.3.1.*; extra == 'cu12'
 Provides-Extra: test
 Requires-Dist: numpy; extra == 'test'
 Requires-Dist: pytest>=7; extra == 'test'
@@ -74,6 +74,17 @@ and the one-shot `transcribe()` helper.
 result = session.run(pcm, pnc="off", itn="on")
 ```
 
+### Prompting
+
+`vocabulary` (custom terms), `prompt` (context, or the instruction under
+`task="instruct"`) and `prefix` (text the model continues from) take effect
+where `model.supports()` reports `"vocabulary"`, `"context_prompt"`,
+`"instruct"` or `"transcript_prefix"`.
+
+```python
+result = session.run(pcm, vocabulary=["Kubernetes", "gRPC"])
+```
+
 Streaming models expose incremental transcription with committed/tentative
 text views — see `examples/stream_wav.py`:
 

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/README.md

@@ -43,6 +43,17 @@ and the one-shot `transcribe()` helper.
 result = session.run(pcm, pnc="off", itn="on")
 ```
 
+### Prompting
+
+`vocabulary` (custom terms), `prompt` (context, or the instruction under
+`task="instruct"`) and `prefix` (text the model continues from) take effect
+where `model.supports()` reports `"vocabulary"`, `"context_prompt"`,
+`"instruct"` or `"transcript_prefix"`.
+
+```python
+result = session.run(pcm, vocabulary=["Kubernetes", "gRPC"])
+```
+
 Streaming models expose incremental transcription with committed/tentative
 text views — see `examples/stream_wav.py`:
 

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcribe-cpp"
-version = "0.2.4"
+version = "0.3.1"
 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.4.*"]
+dependencies = ["transcribe-cpp-native==0.3.1.*"]
 
 [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.4.*"]
+cu12 = ["transcribe-cpp-native-cu12==0.3.1.*"]
 # 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.4 → transcribe_cpp-0.3.1}/src/transcribe_cpp/__init__.py

@@ -39,6 +39,7 @@ from .errors import (
     ModelLoadError,
     NotImplementedByModel,
     OutOfMemory,
+    OutputRepetition,
     OutputTruncated,
     TranscribeError,
     UnsupportedRequest,
@@ -46,12 +47,12 @@ from .errors import (
     raise_for_status,
 )
 
-__version__ = "0.2.4"
+__version__ = "0.3.1"
 
 # 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"]
+Task = Literal["transcribe", "translate", "instruct"]
 Timestamps = Literal["none", "auto", "segment", "word", "token"]
 Pnc = Literal["default", "off", "on"]
 Itn = Literal["default", "off", "on"]
@@ -61,6 +62,7 @@ CommitPolicy = Literal["auto", "on_finalize", "stable_prefix"]
 Feature = Literal[
     "initial_prompt", "temperature_fallback", "long_form",
     "cancellation", "pnc", "itn", "diarization",
+    "vocabulary", "context_prompt", "instruct", "transcript_prefix",
 ]
 
 __all__ = [
@@ -108,6 +110,7 @@ __all__ = [
     "Aborted",
     "InputTooLong",
     "OutputTruncated",
+    "OutputRepetition",
     "native_version",
     "native_commit",
     "library_path",
@@ -201,6 +204,7 @@ _KV_TYPES = {
 _TASKS = {
     "transcribe": _generated.TRANSCRIBE_TASK_TRANSCRIBE,
     "translate": _generated.TRANSCRIBE_TASK_TRANSLATE,
+    "instruct": _generated.TRANSCRIBE_TASK_INSTRUCT,
 }
 _TIMESTAMPS = {
     "none": _generated.TRANSCRIBE_TIMESTAMPS_NONE,
@@ -248,6 +252,10 @@ _FEATURES = {
     "pnc": _generated.TRANSCRIBE_FEATURE_PNC,
     "itn": _generated.TRANSCRIBE_FEATURE_ITN,
     "diarization": _generated.TRANSCRIBE_FEATURE_DIARIZATION,
+    "vocabulary": _generated.TRANSCRIBE_FEATURE_VOCABULARY,
+    "context_prompt": _generated.TRANSCRIBE_FEATURE_CONTEXT_PROMPT,
+    "instruct": _generated.TRANSCRIBE_FEATURE_INSTRUCT,
+    "transcript_prefix": _generated.TRANSCRIBE_FEATURE_TRANSCRIPT_PREFIX,
 }
 
 
@@ -651,9 +659,17 @@ def _stream_update_from(u) -> StreamUpdate:
     )
 
 
+def _cstr(value: str, name: str) -> bytes:
+    """UTF-8 bytes for a C string option; a NUL would silently cut it in C."""
+    if "\x00" in value:
+        raise InvalidArgument(f"{name} contains a NUL character")
+    return value.encode("utf-8")
+
+
 def _build_run_params(task, language, target_language, timestamps,
                       keep_special_tags, spec_k_drafts, diarize="default",
-                      pnc="default", itn="default"):
+                      pnc="default", itn="default", vocabulary=None,
+                      prompt=None, prefix=None):
     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 "
@@ -666,10 +682,27 @@ def _build_run_params(task, language, target_language, 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
+    params.language = _cstr(language, "language") if language else None
+    params.target_language = _cstr(target_language, "target_language") if target_language else None
     params.keep_special_tags = keep_special_tags
     params.spec_k_drafts = spec_k_drafts
+    if vocabulary is not None:
+        if isinstance(vocabulary, (str, bytes)):
+            raise InvalidArgument("vocabulary must be a sequence of terms, not a single string")
+        if isinstance(vocabulary, (set, frozenset, dict)):
+            raise InvalidArgument("vocabulary is in priority order; pass a list, not a set or dict")
+        vocabulary = list(vocabulary)  # an iterator would be used up by the check below
+        if not all(isinstance(t, str) for t in vocabulary):
+            raise InvalidArgument("vocabulary terms must be strings")
+        terms = [_cstr(t, "vocabulary") for t in vocabulary]
+        if terms:
+            arr = (ctypes.c_char_p * len(terms))(*terms)
+            params.vocabulary = ctypes.cast(arr, ctypes.POINTER(ctypes.c_char_p))
+            params.n_vocabulary = len(terms)
+            # The C struct holds raw pointers; keep the buffers alive with it.
+            params._prompting_keepalive = (arr, terms)
+    params.prompt = _cstr(prompt, "prompt") if prompt else None
+    params.prefix = _cstr(prefix, "prefix") if prefix else None
     return params
 
 
@@ -738,7 +771,7 @@ class WhisperRunOptions(FamilyExtension):
 
     def _apply(self, ext) -> None:
         if self.initial_prompt is not None:
-            ext.initial_prompt = self.initial_prompt.encode("utf-8")
+            ext.initial_prompt = _cstr(self.initial_prompt, "initial_prompt")
         if self.condition_on_prev_tokens is not None:
             ext.condition_on_prev_tokens = self.condition_on_prev_tokens
         if self.temperature is not None:
@@ -979,8 +1012,7 @@ class Model:
         )
 
     def supports(self, feature: Feature) -> bool:
-        """Whether the model exposes a behavioral feature (initial prompt,
-        temperature fallback, long-form, cancellation, pnc, itn)."""
+        """Whether the model exposes a behavioral feature (see ``Feature``)."""
         return bool(_lib.transcribe_model_supports(
             self._h, _enum(_FEATURES, feature, "feature")))
 
@@ -1101,7 +1133,10 @@ class Session:
             diarize: Diarize = "default",
             keep_special_tags: bool = False,
             spec_k_drafts: int = -1,
-            family: FamilyExtension | None = None) -> Result:
+            family: FamilyExtension | None = None,
+            vocabulary: Sequence[str] | None = None,
+            prompt: str | None = None,
+            prefix: str | None = None) -> Result:
         """Transcribe 16 kHz mono float32 PCM and return a materialized Result.
 
         ``pnc`` controls punctuation/capitalization and ``itn`` controls
@@ -1111,14 +1146,23 @@ class Session:
         ``spec_k_drafts`` tunes speculative decoding on models whose
         capabilities advertise ``supports_spec_decode`` (-1 = family default,
         0 = disabled, >0 = draft length; silently ignored elsewhere).
-
-        On ``Aborted`` (via :meth:`cancel`) and ``OutputTruncated`` the
-        partial transcript is preserved and attached to the exception as
-        ``partial_result``."""
+        ``vocabulary`` (terms, priority order), ``prompt`` and ``prefix`` are
+        the generic prompting inputs; probe ``model.supports()`` for
+        ``"vocabulary"``, ``"context_prompt"``, ``"instruct"`` and
+        ``"transcript_prefix"``. With ``task="instruct"`` the ``prompt`` is the
+        required instruction and the output is free text. Unsupported
+        vocabulary/context is ignored with a warning; an unsupported prefix
+        or instruct task raises. With ``prefix``, ``text`` holds only the
+        continuation and ``raw_text`` leads with the prefix.
+
+        On ``Aborted`` (via :meth:`cancel`) and ``OutputTruncated`` (including
+        its ``OutputRepetition`` subclass) the partial transcript is preserved
+        and attached to the exception as ``partial_result``."""
         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, pnc, itn)
+                                   keep_special_tags, spec_k_drafts, diarize, pnc, itn,
+                                   vocabulary, prompt, prefix)
         ext = self._resolve_family(family, "run") if family is not None else None
         if ext is not None:
             params.family = ctypes.cast(
@@ -1128,7 +1172,8 @@ class Session:
                    "transcribe_run")
         except (Aborted, OutputTruncated) as exc:
             # The C API preserves the partial transcript on the session for
-            # exactly these two statuses; surface it rather than discard it.
+            # these statuses (OutputRepetition included, as an OutputTruncated
+            # subclass); surface it rather than discard it.
             exc.partial_result = self._materialize()
             raise
         return self._materialize()
@@ -1143,7 +1188,9 @@ class Session:
                   keep_special_tags: bool = False,
                   spec_k_drafts: int = -1,
                   family: FamilyExtension | None = None,
-                  return_exceptions: bool = False) -> list[Result | TranscribeError]:
+                  return_exceptions: bool = False,
+                  vocabulary: Sequence[str] | None = None,
+                  prompt: str | None = None) -> list[Result | TranscribeError]:
         """Transcribe several utterances in one dispatch — one Result each.
 
         Families with a batched compute path process every utterance in a single
@@ -1160,7 +1207,10 @@ class Session:
         view (``Result`` or ``TranscribeError`` each) so completed work is
         never discarded. With ``return_exceptions=True`` no exception is
         raised for utterance failures and that mixed list is returned
-        directly (the ``asyncio.gather`` convention)."""
+        directly (the ``asyncio.gather`` convention).
+
+        ``vocabulary`` / ``prompt`` apply to every utterance (see :meth:`run`);
+        a transcript prefix is per-utterance and so is not accepted here."""
         self._cancel.clear()
         pcms = list(pcms)
         if not pcms:
@@ -1176,7 +1226,8 @@ class Session:
             counts[k] = n
 
         params = _build_run_params(task, language, target_language, timestamps,
-                                   keep_special_tags, spec_k_drafts, diarize, pnc, itn)
+                                   keep_special_tags, spec_k_drafts, diarize, pnc, itn,
+                                   vocabulary, prompt)
         ext = self._resolve_family(family, "run") if family is not None else None
         if ext is not None:
             params.family = ctypes.cast(
@@ -1231,19 +1282,24 @@ class Session:
                diarize: Diarize = "default",
                keep_special_tags: bool = False, commit_policy: CommitPolicy = "auto",
                stable_prefix_agreement_n: int = 0,
-               family: FamilyExtension | None = None) -> Stream:
+               family: FamilyExtension | None = None,
+               vocabulary: Sequence[str] | None = None,
+               prompt: str | None = None) -> Stream:
         """Begin streaming on this session and return a Stream to feed audio to.
 
         Requires a model whose capabilities advertise ``supports_streaming``;
         otherwise raises NotImplementedByModel. ``family`` is an optional
         family-specific stream extension (e.g. MoonshineStreamingOptions). The
         session is single-threaded and runs at most one stream at a time. Use
-        the Stream as a context manager so it is reset when you are done."""
+        the Stream as a context manager so it is reset when you are done.
+        ``vocabulary`` and ``prompt`` are as in :meth:`run`; ``task="instruct"``
+        raises."""
         self._cancel.clear()
         # 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, pnc, itn)
+                                       keep_special_tags, -1, diarize, pnc, itn,
+                                       vocabulary, prompt)
         sp = _StreamParams()
         _lib.transcribe_stream_params_init(_byref(sp))
         sp.commit_policy = _enum(_COMMIT_POLICIES, commit_policy, "commit_policy")
@@ -1496,6 +1552,9 @@ def transcribe(
     keep_special_tags: bool = False,
     spec_k_drafts: int = -1,
     family: FamilyExtension | None = None,
+    vocabulary: Sequence[str] | None = None,
+    prompt: str | None = None,
+    prefix: str | None = None,
 ) -> Result:
     """Transcribe *pcm* in one call and return a materialized Result.
 
@@ -1504,13 +1563,15 @@ def transcribe(
     many clips keep a Model and call ``model.session().run(...)`` yourself; this
     helper is for the one-shot case. ``backend`` / ``device`` apply only when
     *model* is a path — they are ignored when an already-loaded Model is passed.
-    ``family`` / ``spec_k_drafts`` pass through to :meth:`Session.run`.
+    ``family`` / ``spec_k_drafts`` and the prompting inputs (``vocabulary``,
+    ``prompt``, ``prefix``) pass through to :meth:`Session.run`.
     """
     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, pnc=pnc, itn=itn, diarize=diarize,
                     keep_special_tags=keep_special_tags,
-                    spec_k_drafts=spec_k_drafts, family=family)
+                    spec_k_drafts=spec_k_drafts, family=family,
+                    vocabulary=vocabulary, prompt=prompt, prefix=prefix)
 
     if isinstance(model, Model):
         with model.session(**session_opts) as session:

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/src/transcribe_cpp/_generated.py

@@ -13,7 +13,7 @@ import ctypes as _c
 # Stable digest of the ABI surface below (structs, enums, macros, layout,
 # prototypes). A native provider package echoes this back so the API
 # package can reject an ABI-mismatched provider before dlopen.
-PUBLIC_HEADER_HASH = "7df72bf9e667b8c2"
+PUBLIC_HEADER_HASH = "57b1af43650f195d"
 
 # === enum constants ===
 TRANSCRIBE_OK = 0
@@ -35,6 +35,7 @@ TRANSCRIBE_ERR_UNSUPPORTED_PNC = 15
 TRANSCRIBE_ERR_UNSUPPORTED_ITN = 16
 TRANSCRIBE_ERR_INPUT_TOO_LONG = 17
 TRANSCRIBE_ERR_OUTPUT_TRUNCATED = 18
+TRANSCRIBE_ERR_OUTPUT_REPETITION = 19
 TRANSCRIBE_ABI_MODEL_LOAD_PARAMS = 0
 TRANSCRIBE_ABI_SESSION_PARAMS = 1
 TRANSCRIBE_ABI_RUN_PARAMS = 2
@@ -50,6 +51,7 @@ TRANSCRIBE_ABI_SESSION_LIMITS = 11
 TRANSCRIBE_ABI_EXT = 12
 TRANSCRIBE_ABI_DEVICE_INFO = 13
 TRANSCRIBE_ABI_SPEAKER_SEGMENT = 14
+TRANSCRIBE_ABI_BACKEND_INIT_PARAMS = 15
 TRANSCRIBE_LOG_LEVEL_NONE = 0
 TRANSCRIBE_LOG_LEVEL_INFO = 1
 TRANSCRIBE_LOG_LEVEL_WARN = 2
@@ -58,6 +60,7 @@ TRANSCRIBE_LOG_LEVEL_DEBUG = 4
 TRANSCRIBE_LOG_LEVEL_CONT = 5
 TRANSCRIBE_TASK_TRANSCRIBE = 0
 TRANSCRIBE_TASK_TRANSLATE = 1
+TRANSCRIBE_TASK_INSTRUCT = 2
 TRANSCRIBE_TIMESTAMPS_NONE = 0
 TRANSCRIBE_TIMESTAMPS_AUTO = 1
 TRANSCRIBE_TIMESTAMPS_SEGMENT = 2
@@ -95,6 +98,10 @@ TRANSCRIBE_FEATURE_CANCELLATION = 3
 TRANSCRIBE_FEATURE_PNC = 4
 TRANSCRIBE_FEATURE_ITN = 5
 TRANSCRIBE_FEATURE_DIARIZATION = 6
+TRANSCRIBE_FEATURE_VOCABULARY = 7
+TRANSCRIBE_FEATURE_CONTEXT_PROMPT = 8
+TRANSCRIBE_FEATURE_INSTRUCT = 9
+TRANSCRIBE_FEATURE_TRANSCRIPT_PREFIX = 10
 TRANSCRIBE_STREAM_IDLE = 0
 TRANSCRIBE_STREAM_ACTIVE = 1
 TRANSCRIBE_STREAM_FINISHED = 2
@@ -110,6 +117,13 @@ TRANSCRIBE_WHISPER_PROMPT_FIRST_SEGMENT = 0
 TRANSCRIBE_WHISPER_PROMPT_ALL_SEGMENTS = 1
 
 # === macro constants (integer object-like macros) ===
+TRANSCRIBE_BACKEND_MASK_ALL = 4294967295
+TRANSCRIBE_BACKEND_MASK_CPU = 1
+TRANSCRIBE_BACKEND_MASK_CUDA = 8
+TRANSCRIBE_BACKEND_MASK_METAL = 2
+TRANSCRIBE_BACKEND_MASK_OTHER = 2147483648
+TRANSCRIBE_BACKEND_MASK_ROCM = 16
+TRANSCRIBE_BACKEND_MASK_VULKAN = 4
 TRANSCRIBE_EXT_KIND_MOONSHINE_STREAMING_STREAM = 1414746957
 TRANSCRIBE_EXT_KIND_PARAKEET_BUFFERED_STREAM = 1396853584
 TRANSCRIBE_EXT_KIND_PARAKEET_STREAM = 1414744912
@@ -120,6 +134,8 @@ TRANSCRIBE_EXT_KIND_WHISPER_RUN = 1314015319
 # === structs ===
 class transcribe_ext(_c.Structure):
     pass
+class transcribe_backend_init_params(_c.Structure):
+    pass
 class transcribe_device_info(_c.Structure):
     pass
 class transcribe_model_load_params(_c.Structure):
@@ -164,10 +180,11 @@ class transcribe_whisper_chunk_trace(_c.Structure):
     pass
 
 transcribe_ext._fields_ = [("size", _c.c_uint64), ("kind", _c.c_uint32)]
+transcribe_backend_init_params._fields_ = [("struct_size", _c.c_uint64), ("artifact_dir", _c.c_char_p), ("allowed_backends", _c.c_uint32)]
 transcribe_device_info._fields_ = [("struct_size", _c.c_uint64), ("name", _c.c_char_p), ("description", _c.c_char_p), ("kind", _c.c_char_p), ("device_id", _c.c_char_p), ("memory_total", _c.c_uint64), ("memory_free", _c.c_uint64), ("device_type", _c.c_int)]
 transcribe_model_load_params._fields_ = [("struct_size", _c.c_uint64), ("backend", _c.c_int), ("device", _c.c_void_p)]
 transcribe_session_params._fields_ = [("struct_size", _c.c_uint64), ("n_threads", _c.c_int), ("kv_type", _c.c_int), ("n_ctx", _c.c_int32)]
-transcribe_run_params._fields_ = [("struct_size", _c.c_uint64), ("task", _c.c_int), ("timestamps", _c.c_int), ("pnc", _c.c_int), ("itn", _c.c_int), ("diarize", _c.c_int), ("language", _c.c_char_p), ("target_language", _c.c_char_p), ("keep_special_tags", _c.c_bool), ("family", _c.POINTER(transcribe_ext)), ("spec_k_drafts", _c.c_int32)]
+transcribe_run_params._fields_ = [("struct_size", _c.c_uint64), ("task", _c.c_int), ("timestamps", _c.c_int), ("pnc", _c.c_int), ("itn", _c.c_int), ("diarize", _c.c_int), ("language", _c.c_char_p), ("target_language", _c.c_char_p), ("keep_special_tags", _c.c_bool), ("family", _c.POINTER(transcribe_ext)), ("spec_k_drafts", _c.c_int32), ("vocabulary", _c.POINTER(_c.c_char_p)), ("n_vocabulary", _c.c_int32), ("prompt", _c.c_char_p), ("prefix", _c.c_char_p)]
 transcribe_capabilities._fields_ = [("struct_size", _c.c_uint64), ("native_sample_rate", _c.c_int32), ("n_languages", _c.c_int), ("languages", _c.POINTER(_c.c_char_p)), ("max_timestamp_kind", _c.c_int), ("supports_language_detect", _c.c_bool), ("supports_translate", _c.c_bool), ("supports_streaming", _c.c_bool), ("supports_spec_decode", _c.c_bool), ("max_audio_ms", _c.c_int64), ("n_translate_target_languages", _c.c_int), ("translate_target_languages", _c.POINTER(_c.c_char_p))]
 transcribe_session_limits._fields_ = [("struct_size", _c.c_uint64), ("effective_n_ctx", _c.c_int32), ("effective_max_audio_ms", _c.c_int64), ("max_kv_bytes", _c.c_int64)]
 transcribe_stream_params._fields_ = [("struct_size", _c.c_uint64), ("family", _c.POINTER(transcribe_ext)), ("commit_policy", _c.c_int), ("stable_prefix_agreement_n", _c.c_uint32)]
@@ -190,6 +207,7 @@ transcribe_whisper_chunk_trace._fields_ = [("struct_size", _c.c_uint64), ("t0_ms
 # transcribe_abi_struct id per struct (for the native size/align check).
 ABI_STRUCT_IDS = {
     'transcribe_ext': 12,
+    'transcribe_backend_init_params': 15,
     'transcribe_device_info': 13,
     'transcribe_model_load_params': 0,
     'transcribe_session_params': 1,
@@ -209,10 +227,11 @@ ABI_STRUCT_IDS = {
 # C-compiler layout captured at generation (for offset self-check).
 STRUCT_LAYOUT = {
     'transcribe_ext': {'size': 16, 'align': 8, 'offsets': {'size': 0, 'kind': 8}},
+    'transcribe_backend_init_params': {'size': 24, 'align': 8, 'offsets': {'struct_size': 0, 'artifact_dir': 8, 'allowed_backends': 16}},
     'transcribe_device_info': {'size': 64, 'align': 8, 'offsets': {'struct_size': 0, 'name': 8, 'description': 16, 'kind': 24, 'device_id': 32, 'memory_total': 40, 'memory_free': 48, 'device_type': 56}},
     'transcribe_model_load_params': {'size': 24, 'align': 8, 'offsets': {'struct_size': 0, 'backend': 8, 'device': 16}},
     'transcribe_session_params': {'size': 24, 'align': 8, 'offsets': {'struct_size': 0, 'n_threads': 8, 'kv_type': 12, 'n_ctx': 16}},
-    'transcribe_run_params': {'size': 72, 'align': 8, 'offsets': {'struct_size': 0, 'task': 8, 'timestamps': 12, 'pnc': 16, 'itn': 20, 'diarize': 24, 'language': 32, 'target_language': 40, 'keep_special_tags': 48, 'family': 56, 'spec_k_drafts': 64}},
+    'transcribe_run_params': {'size': 104, 'align': 8, 'offsets': {'struct_size': 0, 'task': 8, 'timestamps': 12, 'pnc': 16, 'itn': 20, 'diarize': 24, 'language': 32, 'target_language': 40, 'keep_special_tags': 48, 'family': 56, 'spec_k_drafts': 64, 'vocabulary': 72, 'n_vocabulary': 80, 'prompt': 88, 'prefix': 96}},
     'transcribe_capabilities': {'size': 56, 'align': 8, 'offsets': {'struct_size': 0, 'native_sample_rate': 8, 'n_languages': 12, 'languages': 16, 'max_timestamp_kind': 24, 'supports_language_detect': 28, 'supports_translate': 29, 'supports_streaming': 30, 'supports_spec_decode': 31, 'max_audio_ms': 32, 'n_translate_target_languages': 40, 'translate_target_languages': 48}},
     'transcribe_session_limits': {'size': 32, 'align': 8, 'offsets': {'struct_size': 0, 'effective_n_ctx': 8, 'effective_max_audio_ms': 16, 'max_kv_bytes': 24}},
     'transcribe_stream_params': {'size': 24, 'align': 8, 'offsets': {'struct_size': 0, 'family': 8, 'commit_policy': 16, 'stable_prefix_agreement_n': 20}},
@@ -239,8 +258,12 @@ def configure(lib):
     lib.transcribe_abi_struct_align.argtypes = [_c.c_int]
     lib.transcribe_abi_struct_size.restype = _c.c_size_t
     lib.transcribe_abi_struct_size.argtypes = [_c.c_int]
+    lib.transcribe_allowed_backends.restype = _c.c_uint32
+    lib.transcribe_allowed_backends.argtypes = []
     lib.transcribe_backend_available.restype = _c.c_bool
     lib.transcribe_backend_available.argtypes = [_c.c_int]
+    lib.transcribe_backend_init_params_init.restype = None
+    lib.transcribe_backend_init_params_init.argtypes = [_c.POINTER(transcribe_backend_init_params)]
     lib.transcribe_batch_detected_language.restype = _c.c_char_p
     lib.transcribe_batch_detected_language.argtypes = [_c.c_void_p, _c.c_int]
     lib.transcribe_batch_full_text.restype = _c.c_char_p
@@ -309,6 +332,8 @@ def configure(lib):
     lib.transcribe_init_backends.argtypes = [_c.c_char_p]
     lib.transcribe_init_backends_default.restype = _c.c_int
     lib.transcribe_init_backends_default.argtypes = []
+    lib.transcribe_init_backends_ex.restype = _c.c_int
+    lib.transcribe_init_backends_ex.argtypes = [_c.POINTER(transcribe_backend_init_params)]
     lib.transcribe_log_set.restype = None
     lib.transcribe_log_set.argtypes = [_c.CFUNCTYPE(None, _c.c_int, _c.c_char_p, _c.c_void_p), _c.c_void_p]
     lib.transcribe_model_accepts_ext_kind.restype = _c.c_bool

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/src/transcribe_cpp/errors.py

@@ -22,6 +22,7 @@ from ._generated import (
     TRANSCRIBE_ERR_INVALID_ARG as ERR_INVALID_ARG,
     TRANSCRIBE_ERR_NOT_IMPLEMENTED as ERR_NOT_IMPLEMENTED,
     TRANSCRIBE_ERR_OOM as ERR_OOM,
+    TRANSCRIBE_ERR_OUTPUT_REPETITION as ERR_OUTPUT_REPETITION,
     TRANSCRIBE_ERR_OUTPUT_TRUNCATED as ERR_OUTPUT_TRUNCATED,
     TRANSCRIBE_ERR_SAMPLE_RATE as ERR_SAMPLE_RATE,
     TRANSCRIBE_ERR_UNSUPPORTED_ARCH as ERR_UNSUPPORTED_ARCH,
@@ -113,6 +114,17 @@ class OutputTruncated(TranscribeError):
     partial_result: "Optional[Result]" = None
 
 
+class OutputRepetition(OutputTruncated):
+    """The decode was stopped because the output began repeating itself —
+    the transcript is incomplete by contract.
+
+    A subclass of :class:`OutputTruncated`, so a handler for incomplete
+    transcripts catches both. ``partial_result`` holds the partial transcript
+    with the repeats dropped (one copy kept), or None when the status surfaced
+    outside a result-bearing call.
+    """
+
+
 _STATUS_TO_EXC = {
     ERR_INVALID_ARG: InvalidArgument,
     ERR_NOT_IMPLEMENTED: NotImplementedByModel,
@@ -132,6 +144,7 @@ _STATUS_TO_EXC = {
     ERR_UNSUPPORTED_ITN: UnsupportedRequest,
     ERR_INPUT_TOO_LONG: InputTooLong,
     ERR_OUTPUT_TRUNCATED: OutputTruncated,
+    ERR_OUTPUT_REPETITION: OutputRepetition,
 }
 
 

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/tests/test_errors.py

@@ -41,6 +41,7 @@ def test_every_status_maps_to_documented_subclass():
         errors.ERR_UNSUPPORTED_ITN: t.UnsupportedRequest,
         errors.ERR_INPUT_TOO_LONG: t.InputTooLong,
         errors.ERR_OUTPUT_TRUNCATED: t.OutputTruncated,
+        errors.ERR_OUTPUT_REPETITION: t.OutputRepetition,
     }
     # The mapping table covers every non-OK status the header defines, and
     # nothing else (a new C status must be mapped deliberately, not by
@@ -64,6 +65,14 @@ def test_unknown_status_degrades_to_base_class():
     assert exc.status == 999
 
 
+def test_output_repetition_is_an_output_truncated():
+    # A handler that keeps the partial of an incomplete transcript catches both.
+    exc = errors.exception_for_status(errors.ERR_OUTPUT_REPETITION, "looped", "run")
+    assert isinstance(exc, t.OutputRepetition)
+    assert isinstance(exc, t.OutputTruncated)
+    assert exc.partial_result is None
+
+
 def test_exception_for_status_builds_without_raising():
     exc = errors.exception_for_status(errors.ERR_ABORTED, "aborted", "run")
     assert isinstance(exc, t.Aborted)

transcribe_cpp-0.3.1/tests/test_prompting.py

@@ -0,0 +1,116 @@
+"""Generic prompting inputs: run-params marshalling and model-gated behavior."""
+
+import ctypes
+
+import pytest
+
+import transcribe_cpp as t
+from transcribe_cpp import _generated
+
+
+def test_run_params_carry_prompting_fields():
+    params = t._build_run_params("instruct", None, None, "none", False, -1,
+                                 vocabulary=["GGUF", "ggml"], prompt="Summarize.",
+                                 prefix="And so")
+    assert params.task == _generated.TRANSCRIBE_TASK_INSTRUCT
+    assert params.n_vocabulary == 2
+    assert [params.vocabulary[i] for i in range(2)] == [b"GGUF", b"ggml"]
+    assert params.prompt == b"Summarize."
+    assert params.prefix == b"And so"
+
+
+def test_run_params_default_to_no_prompting():
+    params = t._build_run_params("transcribe", None, None, "auto", False, -1)
+    assert params.n_vocabulary == 0
+    assert not params.vocabulary
+    assert params.prompt is None and params.prefix is None
+
+
+def test_vocabulary_rejects_single_string():
+    with pytest.raises(t.InvalidArgument):
+        t._build_run_params("transcribe", None, None, "auto", False, -1, vocabulary="GGUF")
+
+
+def test_nul_in_string_option_is_rejected():
+    for kwargs in ({"prompt": "a\x00b"}, {"prefix": "a\x00b"}, {"vocabulary": ["a\x00b"]}):
+        with pytest.raises(t.InvalidArgument):
+            t._build_run_params("transcribe", None, None, "auto", False, -1, **kwargs)
+
+
+def test_vocabulary_accepts_iterators_rejects_sets():
+    params = t._build_run_params("transcribe", None, None, "auto", False, -1,
+                                 vocabulary=(w for w in ["GGUF", "ggml"]))
+    assert params.n_vocabulary == 2
+    with pytest.raises(t.InvalidArgument):
+        t._build_run_params("transcribe", None, None, "auto", False, -1, vocabulary={"GGUF"})
+
+
+def test_prompting_features_probe(model_path):
+    with t.Model(model_path, backend="cpu") as model:
+        for feature in ("vocabulary", "context_prompt", "instruct", "transcript_prefix"):
+            assert isinstance(model.supports(feature), bool)
+
+
+def test_unsupported_prefix_raises(streaming_model_path, audio_pcm):
+    with t.Model(streaming_model_path, backend="cpu") as model, model.session() as session:
+        if model.supports("transcript_prefix"):
+            pytest.skip("model supports a transcript prefix")
+        with pytest.raises(t.InvalidArgument):
+            session.run(audio_pcm, prefix="And so")
+
+
+def test_stream_prompting(streaming_model_path):
+    with t.Model(streaming_model_path, backend="cpu") as model, model.session() as session:
+        with pytest.raises(t.UnsupportedRequest):
+            session.stream(task="instruct", prompt="Summarize.")
+        with session.stream(vocabulary=["Kennedy", "Americans"], prompt="A speech."):
+            pass
+
+
+def _whisper(model):
+    return model.arch == "whisper"
+
+
+def test_whisper_prefix_contract(model_path, audio_pcm):
+    """The prefix is forced decoder text: text holds only the continuation,
+    raw_text leads with the prefix, and nothing is duplicated."""
+    prefix = "And so my fellow Americans,"
+    with t.Model(model_path, backend="cpu") as model, model.session() as session:
+        if not _whisper(model):
+            pytest.skip("whisper-specific rendering")
+        assert model.supports("transcript_prefix")
+        res = session.run(audio_pcm, prefix=prefix)
+    assert res.raw_text.strip().startswith(prefix)
+    assert not res.text.lower().startswith("and so")
+    assert "ask not" in res.text.lower()
+    # Whisper's timestamp rules do not compose with a prefix.
+    with t.Model(model_path, backend="cpu") as model, model.session() as session:
+        with pytest.raises(t.InvalidArgument):
+            session.run(audio_pcm, prefix=prefix, timestamps="segment")
+
+
+def test_whisper_vocabulary_and_context(model_path, audio_pcm):
+    with t.Model(model_path, backend="cpu") as model, model.session() as session:
+        if not _whisper(model):
+            pytest.skip("whisper-specific rendering")
+        assert model.supports("vocabulary") and model.supports("context_prompt")
+        res = session.run(audio_pcm, vocabulary=["Kennedy", "Americans"],
+                          prompt="An inaugural address.")
+        assert "country" in res.text.lower()
+        batch = session.run_batch([audio_pcm, audio_pcm], vocabulary=["Kennedy", "Americans"])
+        assert len(batch) == 2 and all("country" in r.text.lower() for r in batch)
+        # The whisper extension's prompt and the generic fields share one slot.
+        with pytest.raises(t.InvalidArgument):
+            session.run(audio_pcm, vocabulary=["Kennedy"],
+                        family=t.WhisperRunOptions(initial_prompt="x"))
+
+
+def test_control_token_literal_rejected(model_path, audio_pcm):
+    """A control-token literal is rejected and leaves the previous result."""
+    with t.Model(model_path, backend="cpu") as model, model.session() as session:
+        if not _whisper(model):
+            pytest.skip("whisper-specific rendering")
+        first = session.run(audio_pcm)
+        with pytest.raises(t.InvalidArgument):
+            session.run(audio_pcm, prompt="hello <|endoftext|>")
+        assert session._materialize().text == first.text

{transcribe_cpp-0.2.4 → transcribe_cpp-0.3.1}/uv.lock

@@ -387,7 +387,7 @@ wheels = [
 
 [[package]]
 name = "transcribe-cpp"
-version = "0.2.4"
+version = "0.3.1"
 source = { editable = "." }
 
 [package.optional-dependencies]
@@ -403,8 +403,8 @@ test = [
 requires-dist = [
     { name = "numpy", marker = "extra == 'test'" },
     { name = "pytest", marker = "extra == 'test'", specifier = ">=7" },
-    { name = "transcribe-cpp-native", specifier = "==0.2.4.*" },
-    { name = "transcribe-cpp-native-cu12", marker = "extra == 'cu12'", specifier = "==0.2.4.*" },
+    { name = "transcribe-cpp-native", specifier = "==0.3.1.*" },
+    { name = "transcribe-cpp-native-cu12", marker = "extra == 'cu12'", specifier = "==0.3.1.*" },
 ]
 provides-extras = ["cu12", "test"]