transcribe-cpp 0.0.3__tar.gz → 0.0.4__tar.gz

{transcribe_cpp-0.0.3 → transcribe_cpp-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transcribe-cpp
-Version: 0.0.3
+Version: 0.0.4
 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.0.3.*
+Requires-Dist: transcribe-cpp-native==0.0.4.*
 Provides-Extra: cu12
-Requires-Dist: transcribe-cpp-native-cu12==0.0.3.*; extra == 'cu12'
+Requires-Dist: transcribe-cpp-native-cu12==0.0.4.*; extra == 'cu12'
 Provides-Extra: test
 Requires-Dist: numpy; extra == 'test'
 Requires-Dist: pytest>=7; extra == 'test'

{transcribe_cpp-0.0.3 → transcribe_cpp-0.0.4}/pyproject.toml

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

@@ -25,7 +25,7 @@ import os
 import threading
 import weakref
 from dataclasses import dataclass
-from typing import Literal, Sequence, Union
+from typing import Literal, Optional, Sequence, Union
 
 from . import _abi, _generated
 from ._library import _base_version, artifact_dir, load_library, selected_provider
@@ -46,7 +46,7 @@ from .errors import (
     raise_for_status,
 )
 
-__version__ = "0.0.3"
+__version__ = "0.0.4"
 
 # String-enum types, exported so callers (and type checkers) can name them.
 Backend = Literal["auto", "cpu", "metal", "vulkan", "cpu_accel", "cuda"]
@@ -146,6 +146,10 @@ if _artifact is not None:
 
 _byref = ctypes.byref
 
+# transcribe_tokenize returns INT32_MIN to signal "this model has no tokenizer
+# encode path" (distinct from the negative grow-buffer signal).
+_INT32_MIN = -(2 ** 31)
+
 # Callback function types — must match the generated argtypes for
 # transcribe_log_set / transcribe_set_abort_callback. ctypes acquires the GIL
 # when C invokes these, and a CFUNCTYPE instance must be kept alive for as long
@@ -240,6 +244,14 @@ def native_provider() -> str | None:
     return selected_provider()
 
 
+_DEVICE_TYPE_NAMES = {
+    _generated.TRANSCRIBE_DEVICE_TYPE_CPU: "cpu",
+    _generated.TRANSCRIBE_DEVICE_TYPE_GPU: "gpu",
+    _generated.TRANSCRIBE_DEVICE_TYPE_IGPU: "igpu",
+    _generated.TRANSCRIBE_DEVICE_TYPE_ACCEL: "accel",
+}
+
+
 @dataclass(frozen=True)
 class BackendDevice:
     """One registered compute device (owned copies of the C strings)."""
@@ -247,23 +259,53 @@ class BackendDevice:
     name: str
     description: str
     kind: str  # "cpu" | "accel" | "metal" | "vulkan" | "cuda" | "sycl" | "gpu" | "unknown"
+    # Vendor-agnostic class: "cpu" | "gpu" | "igpu" | "accel", or "unknown" for a
+    # value reported by a runtime newer than this binding (tell such devices
+    # apart by device_id / name, not by this axis).
+    device_type: str
+    device_id: Optional[str]  # stable hw id (PCI bus id), or None (e.g. Metal)
+    memory_total: int  # reported capacity in bytes, or 0 if unreported
+    # Available bytes — a SNAPSHOT at query time, or 0 if unreported. Re-query
+    # (via backends() or Model.device) to refresh; backend-defined and not
+    # comparable across device kinds.
+    memory_free: int
+    # Registry index of this device — the value to pass as ``Model(...,
+    # gpu_device=index)`` to select it (0 selects the auto / first device).
+    # None when the device came from Model.device, since the underlying
+    # transcribe_model_get_device() does not expose an index; correlate such a
+    # device back to backends() by device_id / name instead. The index is
+    # order-dependent and not stable across driver updates or hosts.
+    index: Optional[int] = None
+
+
+def _backend_device_from_raw(dev, index: Optional[int] = None) -> BackendDevice:
+    """Build a BackendDevice from a library-filled transcribe_backend_device."""
+    return BackendDevice(
+        name=_decode(dev.name),
+        description=_decode(dev.description),
+        kind=_decode(dev.kind),
+        device_type=_DEVICE_TYPE_NAMES.get(dev.device_type, "unknown"),
+        device_id=_decode(dev.device_id) if dev.device_id else None,
+        memory_total=int(dev.memory_total),
+        memory_free=int(dev.memory_free),
+        index=index,
+    )
 
 
 def backends() -> list[BackendDevice]:
     """The compute devices registered with the native runtime — what the
     process can actually run on, after backend-module loading and graceful
-    degradation (e.g. a Vulkan module skipped on a machine without Vulkan)."""
+    degradation (e.g. a Vulkan module skipped on a machine without Vulkan).
+
+    Each device's ``memory_free`` is live as of the call; call again to poll
+    a device's available memory over time."""
     devices = []
     for i in range(_lib.transcribe_backend_device_count()):
         dev = _generated.transcribe_backend_device()
         _lib.transcribe_backend_device_init(_byref(dev))
         _check(_lib.transcribe_get_backend_device(i, _byref(dev)),
                f"reading backend device {i}")
-        devices.append(BackendDevice(
-            name=_decode(dev.name),
-            description=_decode(dev.description),
-            kind=_decode(dev.kind),
-        ))
+        devices.append(_backend_device_from_raw(dev, index=i))
     return devices
 
 
@@ -781,6 +823,18 @@ class Model:
     def backend(self) -> str:
         return _decode(_lib.transcribe_model_backend(self._h))
 
+    @property
+    def device(self) -> BackendDevice:
+        """The compute device this model is running on. ``memory_free`` is a
+        live snapshot, so read this again to poll how much device memory is
+        left after the model loaded. Raises if the model has no resolved
+        compute device."""
+        dev = _generated.transcribe_backend_device()
+        _lib.transcribe_backend_device_init(_byref(dev))
+        _check(_lib.transcribe_model_get_device(self._h, _byref(dev)),
+               "model_get_device")
+        return _backend_device_from_raw(dev)
+
     @property
     def capabilities(self) -> Capabilities:
         caps = _Capabilities()
@@ -815,6 +869,24 @@ class Model:
         return bool(_lib.transcribe_model_accepts_ext_kind(
             self._h, _EXT_SLOTS[options._slot], options._kind))
 
+    def tokenize(self, text: str) -> list[int]:
+        """Tokenize plain UTF-8 ``text`` into the model's vocabulary ids (no
+        BOS/EOS, no special tags). Raises :class:`NotImplementedByModel` for
+        families whose tokenizer has no encode path (e.g. SentencePiece today).
+        """
+        data = text.encode("utf-8")
+        cap = max(len(data), 16)
+        while True:
+            buf = (ctypes.c_int32 * cap)()
+            n = _lib.transcribe_tokenize(self._h, data, buf, cap)
+            if n == _INT32_MIN:
+                raise NotImplementedByModel(
+                    "model tokenizer has no encode path")
+            if n < 0:  # buffer too small: library asked for -n slots, retry
+                cap = -n
+                continue
+            return [buf[i] for i in range(n)]
+
     def session(self, *, n_threads: int = 0, kv_type: KVType = "auto",
                 n_ctx: int = 0) -> "Session":
         return Session(self, n_threads=n_threads, kv_type=kv_type, n_ctx=n_ctx)

{transcribe_cpp-0.0.3 → transcribe_cpp-0.0.4}/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 = "2273744299e5aa65"
+PUBLIC_HEADER_HASH = "ebe6a6816e34a24e"
 
 # === enum constants ===
 TRANSCRIBE_OK = 0
@@ -79,6 +79,10 @@ TRANSCRIBE_BACKEND_METAL = 2
 TRANSCRIBE_BACKEND_VULKAN = 3
 TRANSCRIBE_BACKEND_CPU_ACCEL = 4
 TRANSCRIBE_BACKEND_CUDA = 5
+TRANSCRIBE_DEVICE_TYPE_CPU = 0
+TRANSCRIBE_DEVICE_TYPE_GPU = 1
+TRANSCRIBE_DEVICE_TYPE_IGPU = 2
+TRANSCRIBE_DEVICE_TYPE_ACCEL = 3
 TRANSCRIBE_FEATURE_INITIAL_PROMPT = 0
 TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK = 1
 TRANSCRIBE_FEATURE_LONG_FORM = 2
@@ -145,7 +149,7 @@ class transcribe_whisper_chunk_trace(_c.Structure):
     pass
 
 transcribe_ext._fields_ = [("size", _c.c_uint64), ("kind", _c.c_uint32)]
-transcribe_backend_device._fields_ = [("struct_size", _c.c_uint64), ("name", _c.c_char_p), ("description", _c.c_char_p), ("kind", _c.c_char_p)]
+transcribe_backend_device._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), ("gpu_device", _c.c_int)]
 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), ("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)]
@@ -187,7 +191,7 @@ 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_device': {'size': 32, 'align': 8, 'offsets': {'struct_size': 0, 'name': 8, 'description': 16, 'kind': 24}},
+    'transcribe_backend_device': {'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': 16, 'align': 8, 'offsets': {'struct_size': 0, 'backend': 8, 'gpu_device': 12}},
     'transcribe_session_params': {'size': 24, 'align': 8, 'offsets': {'struct_size': 0, 'n_threads': 8, 'kv_type': 12, 'n_ctx': 16}},
     'transcribe_run_params': {'size': 64, 'align': 8, 'offsets': {'struct_size': 0, 'task': 8, 'timestamps': 12, 'pnc': 16, 'itn': 20, 'language': 24, 'target_language': 32, 'keep_special_tags': 40, 'family': 48, 'spec_k_drafts': 56}},
@@ -287,6 +291,8 @@ def configure(lib):
     lib.transcribe_model_free.argtypes = [_c.c_void_p]
     lib.transcribe_model_get_capabilities.restype = _c.c_int
     lib.transcribe_model_get_capabilities.argtypes = [_c.c_void_p, _c.POINTER(transcribe_capabilities)]
+    lib.transcribe_model_get_device.restype = _c.c_int
+    lib.transcribe_model_get_device.argtypes = [_c.c_void_p, _c.POINTER(transcribe_backend_device)]
     lib.transcribe_model_load_file.restype = _c.c_int
     lib.transcribe_model_load_file.argtypes = [_c.c_char_p, _c.POINTER(transcribe_model_load_params), _c.POINTER(_c.c_void_p)]
     lib.transcribe_model_load_params_init.restype = None

{transcribe_cpp-0.0.3 → transcribe_cpp-0.0.4}/tests/test_backends.py

@@ -25,6 +25,27 @@ def test_at_least_one_device_registered():
         }
 
 
+def test_backends_non_empty():
+    # A CPU device always exists, so the list is never empty.
+    assert t.backends(), "backends() returned an empty list — a CPU device must exist"
+
+
+def test_device_index_and_fields():
+    # Each device carries its registry index (the value Model(..., gpu_device=)
+    # selects with) and well-formed metadata. Pin the device-selection surface.
+    devices = t.backends()
+    for i, dev in enumerate(devices):
+        assert dev.index == i, f"device {i} reported index {dev.index}"
+        assert dev.device_type in {"cpu", "gpu", "igpu", "accel", "unknown"}, (
+            f"device {i} device_type {dev.device_type!r}"
+        )
+        assert dev.memory_total >= 0
+        assert dev.memory_free >= 0
+        assert dev.device_id is None or isinstance(dev.device_id, str)
+        assert isinstance(dev.name, str) and dev.name
+        assert isinstance(dev.kind, str) and dev.kind
+
+
 def test_cpu_always_available():
     # Every shipped configuration includes a CPU backend (compiled in or as
     # the baseline module); a process without one is mispackaged.

transcribe_cpp-0.0.4/tests/test_device_select.py

@@ -0,0 +1,55 @@
+"""Model-gated device-selection tests.
+
+These take the ``model_path`` / ``transcribe_cpp`` fixtures, which ``skip``
+when the default whisper-tiny.en asset is absent (override with
+``TRANSCRIBE_SMOKE_MODEL``). They pin the device-selection surface added
+alongside the per-device ``index`` field: ``Model.device`` reports where the
+model landed (its ``.index`` is ``None`` because it did not come from
+enumeration), and an out-of-range / negative ``gpu_device`` is rejected with
+``InvalidArgument``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import transcribe_cpp as t
+
+
+def test_model_device_matches_enumeration(transcribe_cpp, model_path):
+    # The model lands on some registered device. Model.device does not come
+    # from enumeration, so its .index is None; correlate it back to backends()
+    # by name (and by device_id when that is reported).
+    with transcribe_cpp.Model(model_path) as model:
+        dev = model.device
+        assert isinstance(dev, transcribe_cpp.BackendDevice)
+        assert dev.index is None, "Model.device should not carry a registry index"
+
+        devices = transcribe_cpp.backends()
+        by_name = [d for d in devices if d.name == dev.name]
+        assert by_name, (
+            f"model device {dev.name!r} not found among backends() "
+            f"{[d.name for d in devices]}"
+        )
+        if dev.device_id is not None:
+            assert any(d.device_id == dev.device_id for d in by_name), (
+                f"model device_id {dev.device_id!r} matched no enumerated device"
+            )
+
+
+def test_negative_gpu_device_rejected(transcribe_cpp, model_path):
+    with pytest.raises(transcribe_cpp.InvalidArgument):
+        transcribe_cpp.Model(model_path, gpu_device=-1)
+
+
+def test_out_of_range_gpu_device_rejected(transcribe_cpp, model_path):
+    bad = len(transcribe_cpp.backends()) + 1000
+    with pytest.raises(transcribe_cpp.InvalidArgument):
+        transcribe_cpp.Model(model_path, gpu_device=bad)
+
+
+def test_cpu_backend_with_gpu_index_rejected(transcribe_cpp, model_path):
+    # Hardware-independent: a CPU backend has no GPU to select, so a non-zero
+    # gpu_device is invalid regardless of what hardware is present.
+    with pytest.raises(transcribe_cpp.InvalidArgument):
+        transcribe_cpp.Model(model_path, backend="cpu", gpu_device=1)