open-asr-server 0.1.2__tar.gz

open_asr_server-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 codyw912
+
+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.

open_asr_server-0.1.2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: open-asr-server
+Version: 0.1.2
+Summary: OpenAI-compatible ASR server with pluggable local backends.
+Keywords: asr,speech-to-text,openai,fastapi,whisper
+Author: codyw912
+Author-email: codyw912 <32690983+codyw912@users.noreply.github.com>
+License: MIT License
+         
+         Copyright (c) 2025 codyw912
+         
+         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.
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: fastapi>=0.110
+Requires-Dist: huggingface-hub>=0.23
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: pytest>=7.4 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1 ; extra == 'dev'
+Requires-Dist: httpx>=0.25 ; extra == 'dev'
+Requires-Dist: lightning-whisper-mlx ; python_full_version < '3.12' and extra == 'lightning-whisper'
+Requires-Dist: parakeet-mlx ; extra == 'parakeet'
+Requires-Dist: mlx-whisper ; python_full_version < '3.12' and extra == 'whisper'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/codyw912/open-asr-server
+Project-URL: Repository, https://github.com/codyw912/open-asr-server
+Project-URL: Issues, https://github.com/codyw912/open-asr-server/issues
+Provides-Extra: dev
+Provides-Extra: lightning-whisper
+Provides-Extra: parakeet
+Provides-Extra: whisper
+Description-Content-Type: text/markdown
+
+# Open ASR Server
+
+[![CI](https://github.com/codyw912/open-asr-server/actions/workflows/ci.yml/badge.svg)](https://github.com/codyw912/open-asr-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/open-asr-server)](https://pypi.org/project/open-asr-server/)
+
+OpenAI-compatible ASR server with pluggable local transcription backends.
+
+## Install
+
+Base install includes the API server and shared models/formatters:
+
+```bash
+uv tool install "open-asr-server"
+```
+
+Add backend extras as needed:
+
+```bash
+uv tool install "open-asr-server[parakeet]"
+uv tool install "open-asr-server[whisper]"
+uv tool install "open-asr-server[lightning-whisper]"
+```
+
+Note: the Whisper extras currently require Python 3.11 (tiktoken build constraints on 3.12+).
+
+### Whisper troubleshooting
+
+If `uv run --extra whisper` fails on Python 3.12+, use a 3.11 interpreter for now:
+
+```bash
+uv run --python 3.11 --extra whisper -- open-asr-server serve --host 127.0.0.1 --port 8000
+```
+
+## Run
+
+Install at least one backend extra before running (the default model uses
+Parakeet MLX):
+
+```bash
+uv tool install "open-asr-server[parakeet]"
+```
+
+Then start the server:
+
+```bash
+uv tool run open-asr-server serve --host 127.0.0.1 --port 8000
+```
+
+Environment variables:
+
+- `OPEN_ASR_SERVER_DEFAULT_MODEL`: default model ID for requests
+- `OPEN_ASR_SERVER_PRELOAD`: comma-separated models to preload at startup
+- `OPEN_ASR_SERVER_API_KEY`: optional shared secret for requests
+- `OPEN_ASR_SERVER_ALLOWED_MODELS`: comma-separated allowed model IDs or patterns
+- `OPEN_ASR_SERVER_MAX_UPLOAD_BYTES`: max upload size in bytes (default: 26214400)
+- `OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE`: optional per-client request limit (off by default)
+- `OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS`: optional transcription timeout (off by default)
+- `OPEN_ASR_SERVER_TRANSCRIBE_WORKERS`: optional thread pool size for transcriptions
+- `OPEN_ASR_SERVER_MODEL_DIR`: override the Hugging Face cache location for this server
+- `OPEN_ASR_SERVER_HF_TOKEN`: optional Hugging Face token for gated/private models
+
+Models default to the Hugging Face cache unless a local path is provided. Use
+`OPEN_ASR_SERVER_MODEL_DIR` if you want a dedicated cache without changing your
+global HF environment. Use `OPEN_ASR_SERVER_HF_TOKEN` to authenticate downloads
+without setting global HF environment variables.
+
+Use `OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS` to bound long transcriptions.
+If you set `OPEN_ASR_SERVER_TRANSCRIBE_WORKERS`, transcriptions run in a
+background thread pool instead of the event loop.
+
+## Sample audio
+
+Two short clips are included in `samples/` for quick smoke tests:
+
+- `samples/jfk_0_5.flac`
+- `samples/jfk_5_10.flac`
+
+They are derived from `tests/jfk.flac` in the OpenAI Whisper repo (MIT); the
+original JFK speech is public domain.
+
+```bash
+uv run --extra parakeet scripts/smoke_parakeet.py samples/jfk_0_5.flac
+uv run --python 3.11 --extra whisper scripts/smoke_whisper.py samples/jfk_0_5.flac
+uv run --python 3.11 --extra lightning-whisper scripts/smoke_lightning.py samples/jfk_0_5.flac
+```
+
+## Backend options
+
+All backends are MLX-based today (Apple Silicon/macOS). Non-MLX backends are
+planned, but not yet supported.
+
+Model IDs determine which backend is used:
+
+- Parakeet MLX: `mlx-community/parakeet-tdt-0.6b-v3` (default) or `parakeet-*`
+- MLX Whisper: `whisper-large-v3-turbo` or `mlx-community/whisper-large-v3-turbo`
+- Lightning Whisper MLX: `lightning-whisper-distil-large-v3`
+
+## API compatibility
+
+The server implements:
+
+- `POST /v1/audio/transcriptions`
+- `GET /v1/models`
+
+Example:
+
+```bash
+curl -s -X POST "http://127.0.0.1:8000/v1/audio/transcriptions" \
+  -F "file=@audio.wav" \
+  -F "model=whisper-large-v3-turbo"
+```
+
+## Security
+
+This server is designed for trusted networks. If you expose it publicly, enable
+`OPEN_ASR_SERVER_API_KEY` and front it with a reverse proxy that provides
+TLS and rate limiting. `OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE` offers a simple
+in-process limiter for single-instance use, but it is not a substitute for
+production-grade rate limiting.
+
+API key headers:
+
+- `Authorization: Bearer <token>`
+- `X-API-Key: <token>`
+
+Use `OPEN_ASR_SERVER_ALLOWED_MODELS` to limit which model IDs can be loaded
+and prevent unbounded downloads. Avoid logging request bodies or filenames if
+those may contain sensitive data, and review reverse-proxy access logs for any
+retention concerns.
+
+## Release
+
+```bash
+uv version --bump patch
+uv run --extra dev pytest
+uv build --no-sources
+uv publish --index testpypi --token "$UV_PUBLISH_TOKEN"
+uv publish --token "$UV_PUBLISH_TOKEN"
+```

open_asr_server-0.1.2/README.md

@@ -0,0 +1,139 @@
+# Open ASR Server
+
+[![CI](https://github.com/codyw912/open-asr-server/actions/workflows/ci.yml/badge.svg)](https://github.com/codyw912/open-asr-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/open-asr-server)](https://pypi.org/project/open-asr-server/)
+
+OpenAI-compatible ASR server with pluggable local transcription backends.
+
+## Install
+
+Base install includes the API server and shared models/formatters:
+
+```bash
+uv tool install "open-asr-server"
+```
+
+Add backend extras as needed:
+
+```bash
+uv tool install "open-asr-server[parakeet]"
+uv tool install "open-asr-server[whisper]"
+uv tool install "open-asr-server[lightning-whisper]"
+```
+
+Note: the Whisper extras currently require Python 3.11 (tiktoken build constraints on 3.12+).
+
+### Whisper troubleshooting
+
+If `uv run --extra whisper` fails on Python 3.12+, use a 3.11 interpreter for now:
+
+```bash
+uv run --python 3.11 --extra whisper -- open-asr-server serve --host 127.0.0.1 --port 8000
+```
+
+## Run
+
+Install at least one backend extra before running (the default model uses
+Parakeet MLX):
+
+```bash
+uv tool install "open-asr-server[parakeet]"
+```
+
+Then start the server:
+
+```bash
+uv tool run open-asr-server serve --host 127.0.0.1 --port 8000
+```
+
+Environment variables:
+
+- `OPEN_ASR_SERVER_DEFAULT_MODEL`: default model ID for requests
+- `OPEN_ASR_SERVER_PRELOAD`: comma-separated models to preload at startup
+- `OPEN_ASR_SERVER_API_KEY`: optional shared secret for requests
+- `OPEN_ASR_SERVER_ALLOWED_MODELS`: comma-separated allowed model IDs or patterns
+- `OPEN_ASR_SERVER_MAX_UPLOAD_BYTES`: max upload size in bytes (default: 26214400)
+- `OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE`: optional per-client request limit (off by default)
+- `OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS`: optional transcription timeout (off by default)
+- `OPEN_ASR_SERVER_TRANSCRIBE_WORKERS`: optional thread pool size for transcriptions
+- `OPEN_ASR_SERVER_MODEL_DIR`: override the Hugging Face cache location for this server
+- `OPEN_ASR_SERVER_HF_TOKEN`: optional Hugging Face token for gated/private models
+
+Models default to the Hugging Face cache unless a local path is provided. Use
+`OPEN_ASR_SERVER_MODEL_DIR` if you want a dedicated cache without changing your
+global HF environment. Use `OPEN_ASR_SERVER_HF_TOKEN` to authenticate downloads
+without setting global HF environment variables.
+
+Use `OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS` to bound long transcriptions.
+If you set `OPEN_ASR_SERVER_TRANSCRIBE_WORKERS`, transcriptions run in a
+background thread pool instead of the event loop.
+
+## Sample audio
+
+Two short clips are included in `samples/` for quick smoke tests:
+
+- `samples/jfk_0_5.flac`
+- `samples/jfk_5_10.flac`
+
+They are derived from `tests/jfk.flac` in the OpenAI Whisper repo (MIT); the
+original JFK speech is public domain.
+
+```bash
+uv run --extra parakeet scripts/smoke_parakeet.py samples/jfk_0_5.flac
+uv run --python 3.11 --extra whisper scripts/smoke_whisper.py samples/jfk_0_5.flac
+uv run --python 3.11 --extra lightning-whisper scripts/smoke_lightning.py samples/jfk_0_5.flac
+```
+
+## Backend options
+
+All backends are MLX-based today (Apple Silicon/macOS). Non-MLX backends are
+planned, but not yet supported.
+
+Model IDs determine which backend is used:
+
+- Parakeet MLX: `mlx-community/parakeet-tdt-0.6b-v3` (default) or `parakeet-*`
+- MLX Whisper: `whisper-large-v3-turbo` or `mlx-community/whisper-large-v3-turbo`
+- Lightning Whisper MLX: `lightning-whisper-distil-large-v3`
+
+## API compatibility
+
+The server implements:
+
+- `POST /v1/audio/transcriptions`
+- `GET /v1/models`
+
+Example:
+
+```bash
+curl -s -X POST "http://127.0.0.1:8000/v1/audio/transcriptions" \
+  -F "file=@audio.wav" \
+  -F "model=whisper-large-v3-turbo"
+```
+
+## Security
+
+This server is designed for trusted networks. If you expose it publicly, enable
+`OPEN_ASR_SERVER_API_KEY` and front it with a reverse proxy that provides
+TLS and rate limiting. `OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE` offers a simple
+in-process limiter for single-instance use, but it is not a substitute for
+production-grade rate limiting.
+
+API key headers:
+
+- `Authorization: Bearer <token>`
+- `X-API-Key: <token>`
+
+Use `OPEN_ASR_SERVER_ALLOWED_MODELS` to limit which model IDs can be loaded
+and prevent unbounded downloads. Avoid logging request bodies or filenames if
+those may contain sensitive data, and review reverse-proxy access logs for any
+retention concerns.
+
+## Release
+
+```bash
+uv version --bump patch
+uv run --extra dev pytest
+uv build --no-sources
+uv publish --index testpypi --token "$UV_PUBLISH_TOKEN"
+uv publish --token "$UV_PUBLISH_TOKEN"
+```

open_asr_server-0.1.2/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "open-asr-server"
+version = "0.1.2"
+description = "OpenAI-compatible ASR server with pluggable local backends."
+readme = "README.md"
+authors = [
+    { name = "codyw912", email = "32690983+codyw912@users.noreply.github.com" }
+]
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+keywords = ["asr", "speech-to-text", "openai", "fastapi", "whisper"]
+dependencies = [
+    "fastapi>=0.110",
+    "huggingface-hub>=0.23",
+    "pydantic>=2.0",
+    "python-multipart>=0.0.9",
+    "typer>=0.12",
+    "uvicorn>=0.29",
+]
+
+[project.urls]
+Homepage = "https://github.com/codyw912/open-asr-server"
+Repository = "https://github.com/codyw912/open-asr-server"
+Issues = "https://github.com/codyw912/open-asr-server/issues"
+
+[project.optional-dependencies]
+parakeet = [
+    "parakeet-mlx",
+]
+whisper = [
+    "mlx-whisper; python_version < '3.12'",
+]
+lightning-whisper = [
+    "lightning-whisper-mlx; python_version < '3.12'",
+]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "httpx>=0.25",
+]
+
+[project.scripts]
+open-asr-server = "open_asr_server.cli:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["uv_build>=0.9.24,<0.10.0"]
+build-backend = "uv_build"

open_asr_server-0.1.2/src/open_asr_server/__init__.py

@@ -0,0 +1,22 @@
+"""OpenAI-compatible ASR server for local transcription."""
+
+from .config import ServerConfig
+
+__version__ = "0.1.0"
+
+def create_app(config: ServerConfig | None = None):
+    """Create the FastAPI application."""
+    from .app import create_app as _create_app
+
+    return _create_app(config)
+
+
+try:
+    app = create_app()
+except ModuleNotFoundError as exc:
+    if exc.name == "fastapi":
+        app = None
+    else:
+        raise
+
+__all__ = ["create_app", "ServerConfig", "app", "__version__"]

open_asr_server-0.1.2/src/open_asr_server/app.py

@@ -0,0 +1,57 @@
+"""FastAPI application factory."""
+
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from .backends import preload_backend
+from .config import ServerConfig
+from .routes import router
+from .utils.rate_limit import RateLimiter
+
+
+def create_app(config: ServerConfig | None = None) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        config: Server configuration. Uses defaults if not provided.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    config = config or ServerConfig.from_env()
+
+    transcribe_executor = (
+        ThreadPoolExecutor(max_workers=config.transcribe_workers)
+        if config.transcribe_workers
+        else None
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # Startup: preload models if configured
+        for model in config.preload_models:
+            preload_backend(model)
+        yield
+        # Shutdown: close executor if created
+        if transcribe_executor:
+            transcribe_executor.shutdown(wait=False)
+
+    app = FastAPI(
+        title="OpenAI-Compatible ASR Server",
+        description="Local transcription server with OpenAI Whisper API compatibility",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    app.state.config = config
+    app.state.rate_limiter = (
+        RateLimiter(config.rate_limit_per_minute)
+        if config.rate_limit_per_minute
+        else None
+    )
+    app.state.transcribe_executor = transcribe_executor
+    app.include_router(router)
+
+    return app

open_asr_server-0.1.2/src/open_asr_server/backends/__init__.py

@@ -0,0 +1,66 @@
+"""Backend registry for transcription engines."""
+
+import fnmatch
+from typing import Callable
+
+from .base import TranscriptionBackend
+
+_backends: dict[str, TranscriptionBackend] = {}
+_backend_factories: dict[str, Callable[[str], TranscriptionBackend]] = {}
+
+
+def register_backend(
+    model_pattern: str, factory: Callable[[str], TranscriptionBackend]
+) -> None:
+    """Register a backend factory for a model pattern.
+
+    Args:
+        model_pattern: Glob pattern to match model names (e.g., "parakeet-*").
+        factory: Callable that takes a model ID and returns a backend instance.
+    """
+    _backend_factories[model_pattern] = factory
+
+
+def get_backend(model: str) -> TranscriptionBackend | None:
+    """Get or create backend for model (lazy loading).
+
+    Args:
+        model: Model identifier to look up.
+
+    Returns:
+        Backend instance, or None if no matching factory found.
+    """
+    if model not in _backends:
+        for pattern, factory in _backend_factories.items():
+            if fnmatch.fnmatch(model, pattern) or model == pattern:
+                _backends[model] = factory(model)
+                break
+    return _backends.get(model)
+
+
+def preload_backend(model: str) -> TranscriptionBackend | None:
+    """Eagerly load a backend.
+
+    Args:
+        model: Model identifier to preload.
+
+    Returns:
+        Backend instance, or None if no matching factory found.
+    """
+    return get_backend(model)
+
+
+def list_registered_patterns() -> list[str]:
+    """List registered model patterns."""
+    return list(_backend_factories.keys())
+
+
+def list_loaded_models() -> list[str]:
+    """List currently loaded model instances."""
+    return list(_backends.keys())
+
+
+# Import backends to trigger registration
+from . import parakeet as _parakeet  # noqa: F401, E402
+from . import whisper as _whisper  # noqa: F401, E402
+from . import lightning_whisper as _lightning_whisper  # noqa: F401, E402

open_asr_server-0.1.2/src/open_asr_server/backends/base.py

@@ -0,0 +1,71 @@
+"""Base types and protocol for transcription backends."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class WordSegment:
+    """A single word with timestamps."""
+
+    word: str
+    start: float
+    end: float
+
+
+@dataclass
+class Segment:
+    """A segment (sentence/phrase) with timestamps."""
+
+    id: int
+    start: float
+    end: float
+    text: str
+    confidence: float | None = None
+
+
+@dataclass
+class TranscriptionResult:
+    """Unified result format for all backends."""
+
+    text: str
+    language: str | None
+    duration: float
+    words: list[WordSegment] | None = None
+    segments: list[Segment] | None = None
+
+
+@runtime_checkable
+class TranscriptionBackend(Protocol):
+    """Protocol for transcription backends.
+
+    Implement this protocol to add support for a new ASR engine.
+    """
+
+    def transcribe(
+        self,
+        audio_path: Path,
+        language: str | None = None,
+        temperature: float = 0.0,
+        word_timestamps: bool = False,
+        prompt: str | None = None,
+    ) -> TranscriptionResult:
+        """Transcribe audio file and return unified result.
+
+        Args:
+            audio_path: Path to the audio file.
+            language: Optional ISO-639-1 language code hint.
+            temperature: Sampling temperature (0.0-1.0).
+            word_timestamps: Whether to include word-level timestamps.
+            prompt: Optional prompt to guide decoding, if supported.
+
+        Returns:
+            TranscriptionResult with text and optional timestamps.
+        """
+        ...
+
+    @property
+    def supported_languages(self) -> list[str] | None:
+        """List of supported language codes, or None if auto-detect only."""
+        ...