Metadata-Version: 2.4
Name: kikita-wake-word-runtime
Version: 0.1.0a3
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.26,<2.4
Requires-Dist: jsonschema==4.26.0 ; extra == 'dev'
Requires-Dist: maturin==1.14.1 ; extra == 'dev'
Requires-Dist: mypy==2.3.0 ; extra == 'dev'
Requires-Dist: ruff==0.16.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Cross-platform runtime and .kww specification for wake-word detection.
Keywords: wake-word,keyword-spotting,speech-recognition,onnx,audio,kww
Author: Kikita Labs
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/kikita-labs/wake-word-runtime/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/kikita-labs/wake-word-runtime#readme
Project-URL: Issues, https://github.com/kikita-labs/wake-word-runtime/issues
Project-URL: Repository, https://github.com/kikita-labs/wake-word-runtime

# Kikita Wake Word Runtime for Python

Typed Python binding for validating, inspecting, producing, and running `.kww` model
bundles through the shared Rust core.

```bash
pip install --pre kikita-wake-word-runtime
```

```python
from kikita_wake_word_runtime import open_bundle

with open_bundle("model.kww") as bundle:
    print(bundle.manifest.bundle_id)
```

Forge and other trusted producer applications create bundles through the same package:

```python
from kikita_wake_word_runtime import write_bundle

write_bundle(
    "model.kww",
    manifest,
    {
        "mel": mel_path,
        "embedding": embedding_path,
        "classifier": classifier_path,
    },
)
```

The writer validates sizes and SHA-256 values, writes a deterministic archive, reopens it
through the secure loader, and atomically publishes the completed `.kww`.

```python
from kikita_wake_word_runtime import WakeWordModel

model = WakeWordModel.from_bundle("model.kww")
stream = model.create_stream(source_sample_rate_hz=48_000)

for result in stream.process_pcm_s16le(discord_pcm):
    if result.detected:
        print(result.candidate_score, result.verifier_score, result.score)
```

`WakeWordModel` shares immutable ONNX sessions. Create one `WakeWordStream` per ordered
mono PCM source. Input buffers are copied. Call `finish()` at end of a finite source or
`reset()` before reusing stream state. A model may serve multiple streams concurrently;
calls on one mutable stream must remain ordered and must not run concurrently.

Candidate-only and embedded ONNX verifier bundles run offline. An external verifier
dependency is accepted by the manifest parser but model loading fails closed until that
exact dependency is supplied through a future resolver API.

The wheel contains the Rust core and statically linked ONNX Runtime. End users need
Python 3.11 or newer and a supported prebuilt platform, not Rust or a separate
`onnxruntime` package.

Supported by the first alpha: Windows x64, manylinux_2_28 x64, and Apple Silicon macOS.
See the [repository](https://github.com/kikita-labs/wake-word-runtime) for the `.kww`
specification, compatibility matrix, security policy, and release notes.

