rift-local 0.1.0.dev1__tar.gz

rift_local-0.1.0.dev1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

rift_local-0.1.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leftium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rift_local-0.1.0.dev1/MANIFEST.in

@@ -0,0 +1,15 @@
+# Include essential files
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Exclude build artifacts and local files
+exclude log.txt
+exclude uv.lock
+exclude .gitignore
+prune tests
+prune scripts
+prune specs
+prune .pytest_cache
+prune .ruff_cache
+prune .venv

rift_local-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: rift-local
+Version: 0.1.0.dev1
+Summary: Local inference server for RIFT Transcription — streaming and batch speech recognition, LLM transforms, and CLI transcription backed by local models.
+Project-URL: Homepage, https://github.com/Leftium/rift-local
+Project-URL: Repository, https://github.com/Leftium/rift-local
+Project-URL: Issues, https://github.com/Leftium/rift-local/issues
+Author: Leftium
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asr,local-inference,speech-recognition,transcription,whisper
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: uvicorn[standard]>=0.34
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mlx
+Provides-Extra: moonshine
+Requires-Dist: moonshine-voice>=0.0.48; extra == 'moonshine'
+Provides-Extra: sherpa
+Requires-Dist: onnx>=1.16; extra == 'sherpa'
+Requires-Dist: sherpa-onnx>=1.11; extra == 'sherpa'
+Description-Content-Type: text/markdown
+
+# rift-local
+
+Local inference server for [RIFT Transcription](https://github.com/Leftium/rift-transcription). Serves streaming speech recognition over WebSocket, backed by local models with automatic download.
+
+## Install
+
+```
+pip install rift-local
+```
+
+### Backend extras
+
+rift-local supports multiple ASR backends, each installed as an optional extra:
+
+```bash
+pip install rift-local[sherpa]      # sherpa-onnx (Nemotron, Kroko)
+pip install rift-local[moonshine]   # Moonshine Gen 2 (via moonshine-voice)
+pip install rift-local[sherpa,moonshine]  # both
+```
+
+On Apple Silicon, add MLX support for future GPU-accelerated batch transcription:
+
+```bash
+pip install rift-local[mlx]
+```
+
+For development (includes pytest):
+
+```bash
+pip install rift-local[dev]
+```
+
+## Models
+
+List all available models and see which are installed:
+
+```
+rift-local list
+rift-local list --installed
+```
+
+### sherpa-onnx models
+
+| Model | Params | Languages | Download | Notes |
+|-------|--------|-----------|----------|-------|
+| `nemotron-en` | 0.6B | EN | 447 MB | Best accuracy. |
+| `zipformer-en-kroko` | ~30M | EN | 55 MB | Lightweight, fast. Only ~68 MB on disk. |
+
+Requires: `pip install rift-local[sherpa]`
+
+### Moonshine models
+
+| Model | Params | Languages | Size | Notes |
+|-------|--------|-----------|------|-------|
+| `moonshine-en-tiny` | 34M | EN | 26 MB | Fastest. Good for low-resource. |
+| `moonshine-en-small` | 123M | EN | 95 MB | Balanced speed/accuracy. |
+| `moonshine-en-medium` | 245M | EN | 190 MB | **Default.** Best Moonshine accuracy. |
+
+Requires: `pip install rift-local[moonshine]`
+
+Moonshine models are downloaded automatically by the `moonshine-voice` library on first use.
+
+## Usage
+
+### Server mode (for RIFT app)
+
+Start the WebSocket server with any model:
+
+```bash
+# Start server and open RIFT Transcription in your browser
+rift-local serve --open
+
+# Moonshine (default model)
+rift-local serve
+
+# sherpa-onnx
+rift-local serve --model nemotron-en
+
+# Custom host/port
+rift-local serve --model moonshine-en-tiny --host 0.0.0.0 --port 8080
+```
+
+The `--open` flag launches [RIFT Transcription](https://rift-transcription.vercel.app) in your browser, pre-configured to connect to the local server. The voice source is set to "Local" automatically — just click to start the mic.
+
+For local development of the RIFT Transcription client:
+
+```bash
+rift-local serve --open dev          # opens http://localhost:5173
+rift-local serve --open dev:3000     # custom port
+```
+
+The server auto-downloads the model on first run, then listens on:
+- **WebSocket**: `ws://127.0.0.1:2177/ws` (streaming ASR)
+- **HTTP**: `http://127.0.0.1:2177/info` (model metadata)
+
+### Server options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model` | `moonshine-en-medium` | Model name from registry |
+| `--host` | `127.0.0.1` | Bind address |
+| `--port` | `2177` | Server port |
+| `--threads` | `2` | Inference threads |
+| `--open` | off | Open browser to RIFT Transcription client |
+
+## WebSocket protocol
+
+1. Client connects to `/ws`
+2. Server sends `info` JSON (model name, features, sample rate)
+3. Client sends binary frames of Float32 PCM audio at 16 kHz
+4. Server sends `result` JSON messages with partial/final transcriptions
+5. Client sends text `"Done"` to end the session
+
+## Running tests
+
+```bash
+# Install dev + backend dependencies
+pip install -e ".[dev,sherpa,moonshine]"
+
+# Run fast tests (mocked backends, no model download)
+pytest
+
+# Run all tests including slow integration tests (downloads models)
+pytest --slow
+```
+
+Tests are in the `tests/` directory:
+- `test_server.py` — WebSocket server tests using a mock backend
+- `test_moonshine.py` — Moonshine adapter unit tests (mocked) + integration tests (slow)
+- `conftest.py` — Shared `MockBackend` fixture and `--slow` flag
+
+## Spec
+
+See [specs/rift-local.md](specs/rift-local.md) for the full design document.
+
+## License
+
+[MIT](LICENSE)

rift_local-0.1.0.dev1/PUBLISHING.md

@@ -0,0 +1,208 @@
+# Publishing rift-local to PyPI
+
+## Quick Start
+
+```bash
+# 1. Build and test
+./scripts/build.sh
+
+# 2. Upload to TestPyPI (optional but recommended)
+uv run python -m twine upload --repository testpypi dist/*
+
+# 3. Test install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ rift-local
+
+# 4. Upload to PyPI
+uv run python -m twine upload dist/*
+```
+
+## First-Time Setup
+
+### 1. Create PyPI Accounts
+
+- **TestPyPI**: https://test.pypi.org/account/register/
+- **PyPI**: https://pypi.org/account/register/
+
+### 2. Generate API Tokens
+
+For both TestPyPI and PyPI:
+1. Go to Account Settings → API tokens
+2. Click "Add API token"
+3. Name: `rift-local` (or "All projects" scope)
+4. Scope: Choose project or entire account
+5. Copy the token (starts with `pypi-`)
+
+### 3. Configure Authentication
+
+Create `~/.pypirc`:
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-YOUR-PRODUCTION-TOKEN-HERE
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR-TEST-TOKEN-HERE
+```
+
+Set permissions:
+```bash
+chmod 600 ~/.pypirc
+```
+
+## Build Script Features
+
+The `scripts/build.sh` script automatically:
+
+✅ Checks version consistency (`pyproject.toml` ↔ `__init__.py`)  
+✅ Verifies required files exist  
+✅ Warns about uncommitted changes  
+✅ Cleans old builds  
+✅ Runs tests  
+✅ Builds both wheel and source distribution  
+✅ Validates package metadata with `twine check`  
+✅ Shows next steps
+
+## Version Management
+
+Current version: `0.1.0.dev0` (development release)
+
+### Update version in TWO places:
+
+1. `pyproject.toml`:
+   ```toml
+   [project]
+   version = "0.1.0"
+   ```
+
+2. `src/rift_local/__init__.py`:
+   ```python
+   __version__ = "0.1.0"
+   ```
+
+### Version Strategy
+
+- `0.1.0.dev0` — Development release (TestPyPI testing)
+- `0.1.0` — First stable release
+- `0.1.1` — Bug fixes (patch)
+- `0.2.0` — New features (minor)
+- `1.0.0` — Stable API (major)
+
+## Testing the Package
+
+### Local Installation Test
+
+```bash
+# Create clean venv
+python3 -m venv /tmp/test_rift_local
+source /tmp/test_rift_local/bin/activate
+
+# Install from local build
+pip install dist/rift_local-*.whl
+
+# Test CLI
+rift-local --help
+rift-local list
+
+# Test Python API
+python3 -c "
+import rift_local
+print(f'Version: {rift_local.__version__}')
+from rift_local.models.registry import list_models
+print(f'Models: {len(list_models())}')
+"
+```
+
+### TestPyPI Installation Test
+
+```bash
+# Install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            rift-local
+
+# Note: --extra-index-url needed for dependencies not on TestPyPI
+```
+
+## Publishing Checklist
+
+Before uploading to PyPI:
+
+- [ ] All tests pass
+- [ ] Version updated in both places
+- [ ] README.md up to date
+- [ ] CHANGELOG updated (if exists)
+- [ ] Git committed and tagged
+- [ ] Tested on TestPyPI
+- [ ] Verified installation in clean environment
+
+## Post-Publication
+
+### Tag the release
+
+```bash
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+### Create GitHub Release
+
+1. Go to https://github.com/Leftium/rift-local/releases
+2. Click "Draft a new release"
+3. Choose tag: `v0.1.0`
+4. Release title: `v0.1.0`
+5. Add release notes
+6. Publish release
+
+## Troubleshooting
+
+### `externally-managed-environment` error
+
+The build script automatically handles this by using `uv` if available. 
+
+If needed, use a virtual environment:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+./scripts/build.sh
+```
+
+### Upload fails with 403
+
+- Check API token is correct
+- Verify package name not already taken
+- Ensure token has correct scope
+
+### Package name conflict
+
+If `rift-local` is taken, consider:
+- `rift-local-server`
+- `riftlocal`
+- `rift-inference`
+
+Change in `pyproject.toml`:
+```toml
+[project]
+name = "rift-local-server"
+```
+
+## Useful Commands
+
+```bash
+# View package contents
+tar -tzf dist/rift_local-*.tar.gz | head -20
+unzip -l dist/rift_local-*.whl
+
+# Check package on PyPI
+open https://pypi.org/project/rift-local/
+
+# Check download stats (after 24-48 hours)
+open https://pepy.tech/project/rift-local
+```

rift_local-0.1.0.dev1/README.md

@@ -0,0 +1,138 @@
+# rift-local
+
+Local inference server for [RIFT Transcription](https://github.com/Leftium/rift-transcription). Serves streaming speech recognition over WebSocket, backed by local models with automatic download.
+
+## Install
+
+```
+pip install rift-local
+```
+
+### Backend extras
+
+rift-local supports multiple ASR backends, each installed as an optional extra:
+
+```bash
+pip install rift-local[sherpa]      # sherpa-onnx (Nemotron, Kroko)
+pip install rift-local[moonshine]   # Moonshine Gen 2 (via moonshine-voice)
+pip install rift-local[sherpa,moonshine]  # both
+```
+
+On Apple Silicon, add MLX support for future GPU-accelerated batch transcription:
+
+```bash
+pip install rift-local[mlx]
+```
+
+For development (includes pytest):
+
+```bash
+pip install rift-local[dev]
+```
+
+## Models
+
+List all available models and see which are installed:
+
+```
+rift-local list
+rift-local list --installed
+```
+
+### sherpa-onnx models
+
+| Model | Params | Languages | Download | Notes |
+|-------|--------|-----------|----------|-------|
+| `nemotron-en` | 0.6B | EN | 447 MB | Best accuracy. |
+| `zipformer-en-kroko` | ~30M | EN | 55 MB | Lightweight, fast. Only ~68 MB on disk. |
+
+Requires: `pip install rift-local[sherpa]`
+
+### Moonshine models
+
+| Model | Params | Languages | Size | Notes |
+|-------|--------|-----------|------|-------|
+| `moonshine-en-tiny` | 34M | EN | 26 MB | Fastest. Good for low-resource. |
+| `moonshine-en-small` | 123M | EN | 95 MB | Balanced speed/accuracy. |
+| `moonshine-en-medium` | 245M | EN | 190 MB | **Default.** Best Moonshine accuracy. |
+
+Requires: `pip install rift-local[moonshine]`
+
+Moonshine models are downloaded automatically by the `moonshine-voice` library on first use.
+
+## Usage
+
+### Server mode (for RIFT app)
+
+Start the WebSocket server with any model:
+
+```bash
+# Start server and open RIFT Transcription in your browser
+rift-local serve --open
+
+# Moonshine (default model)
+rift-local serve
+
+# sherpa-onnx
+rift-local serve --model nemotron-en
+
+# Custom host/port
+rift-local serve --model moonshine-en-tiny --host 0.0.0.0 --port 8080
+```
+
+The `--open` flag launches [RIFT Transcription](https://rift-transcription.vercel.app) in your browser, pre-configured to connect to the local server. The voice source is set to "Local" automatically — just click to start the mic.
+
+For local development of the RIFT Transcription client:
+
+```bash
+rift-local serve --open dev          # opens http://localhost:5173
+rift-local serve --open dev:3000     # custom port
+```
+
+The server auto-downloads the model on first run, then listens on:
+- **WebSocket**: `ws://127.0.0.1:2177/ws` (streaming ASR)
+- **HTTP**: `http://127.0.0.1:2177/info` (model metadata)
+
+### Server options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model` | `moonshine-en-medium` | Model name from registry |
+| `--host` | `127.0.0.1` | Bind address |
+| `--port` | `2177` | Server port |
+| `--threads` | `2` | Inference threads |
+| `--open` | off | Open browser to RIFT Transcription client |
+
+## WebSocket protocol
+
+1. Client connects to `/ws`
+2. Server sends `info` JSON (model name, features, sample rate)
+3. Client sends binary frames of Float32 PCM audio at 16 kHz
+4. Server sends `result` JSON messages with partial/final transcriptions
+5. Client sends text `"Done"` to end the session
+
+## Running tests
+
+```bash
+# Install dev + backend dependencies
+pip install -e ".[dev,sherpa,moonshine]"
+
+# Run fast tests (mocked backends, no model download)
+pytest
+
+# Run all tests including slow integration tests (downloads models)
+pytest --slow
+```
+
+Tests are in the `tests/` directory:
+- `test_server.py` — WebSocket server tests using a mock backend
+- `test_moonshine.py` — Moonshine adapter unit tests (mocked) + integration tests (slow)
+- `conftest.py` — Shared `MockBackend` fixture and `--slow` flag
+
+## Spec
+
+See [specs/rift-local.md](specs/rift-local.md) for the full design document.
+
+## License
+
+[MIT](LICENSE)

rift_local-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rift-local"
+version = "0.1.0.dev1"
+description = "Local inference server for RIFT Transcription — streaming and batch speech recognition, LLM transforms, and CLI transcription backed by local models."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Leftium" }]
+keywords = ["speech-recognition", "transcription", "asr", "whisper", "local-inference"]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "numpy>=1.24",
+    "httpx>=0.28",
+    "pydantic>=2.0",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+
+[project.urls]
+Homepage = "https://github.com/Leftium/rift-local"
+Repository = "https://github.com/Leftium/rift-local"
+Issues = "https://github.com/Leftium/rift-local/issues"
+
+[project.scripts]
+rift-local = "rift_local.cli:main"
+
+[project.optional-dependencies]
+sherpa = ["sherpa-onnx>=1.11", "onnx>=1.16"]
+moonshine = ["moonshine-voice>=0.0.48"]
+mlx = []
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: requires downloaded models (use --slow to run)"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rift_local"]