vocal-core 0.3.0__tar.gz

vocal_core-0.3.0/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# UV
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Model cache
+.cache/
+models/
+*.ckpt
+*.pth
+*.pt
+*.safetensors
+
+# Audio files (test data)
+*.mp3
+*.wav
+*.m4a
+*.ogg
+*.flac
+
+# Logs
+*.log
+logs/
+
+# Environment variables
+.env
+.env.local
+
+# OS
+Thumbs.db

vocal_core-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include ../../../README.md
+include ../../../LICENSE
+recursive-include vocal_core *.py

vocal_core-0.3.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: vocal-core
+Version: 0.3.0
+Summary: Core model registry and adapters for Vocal - Ollama for Voice Models
+Project-URL: Homepage, https://github.com/niradler/vocal
+Project-URL: Documentation, https://github.com/niradler/vocal#readme
+Project-URL: Repository, https://github.com/niradler/vocal
+Project-URL: Issues, https://github.com/niradler/vocal/issues
+Author: Vocal Contributors
+License: SSPL-1.0
+Keywords: ai,model-registry,speech-to-text,stt,tts,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: huggingface-hub>=0.20.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyttsx3>=2.90
+Provides-Extra: piper
+Requires-Dist: piper-tts>=1.2.0; extra == 'piper'
+Requires-Dist: scipy>=1.11.0; extra == 'piper'

vocal_core-0.3.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "vocal-core"
+version = "0.3.0"
+description = "Core model registry and adapters for Vocal - Ollama for Voice Models"
+requires-python = ">=3.11"
+license = { text = "SSPL-1.0" }
+authors = [
+    { name = "Vocal Contributors" }
+]
+keywords = ["speech-to-text", "tts", "stt", "whisper", "model-registry", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "faster-whisper>=1.0.0",
+    "huggingface-hub>=0.20.0",
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+    "pyttsx3>=2.90",
+    "numpy>=1.24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/niradler/vocal"
+Documentation = "https://github.com/niradler/vocal#readme"
+Repository = "https://github.com/niradler/vocal"
+Issues = "https://github.com/niradler/vocal/issues"
+
+[project.optional-dependencies]
+piper = [
+    "piper-tts>=1.2.0",
+    "scipy>=1.11.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

vocal_core-0.3.0/tests/test_registry.py

@@ -0,0 +1,44 @@
+import pytest
+
+from vocal_core import ModelRegistry
+
+
+@pytest.mark.asyncio
+async def test_model_registry_init():
+    """Test that ModelRegistry initializes correctly"""
+    registry = ModelRegistry()
+    assert registry is not None
+    assert registry.storage_path.exists()
+
+
+@pytest.mark.asyncio
+async def test_list_models():
+    """Test listing models from HuggingFace provider"""
+    registry = ModelRegistry()
+    models = await registry.list_models(task="stt")
+
+    assert len(models) > 0
+    assert all(m.task.value == "stt" for m in models)
+
+    whisper_models = [m for m in models if "whisper" in m.id.lower()]
+    assert len(whisper_models) > 0
+
+
+@pytest.mark.asyncio
+async def test_get_model_info():
+    """Test getting specific model info"""
+    registry = ModelRegistry()
+    model = await registry.get_model("openai/whisper-tiny")
+
+    assert model is not None
+    assert model.id == "openai/whisper-tiny"
+    assert model.task.value == "stt"
+    assert model.provider.value == "huggingface"
+
+
+@pytest.mark.asyncio
+async def test_model_registry_providers():
+    """Test that registry has providers configured"""
+    registry = ModelRegistry()
+    assert "huggingface" in registry.providers
+    assert registry.providers["huggingface"] is not None

vocal_core-0.3.0/vocal_core/__init__.py

@@ -0,0 +1,35 @@
+from .adapters import (
+    BaseAdapter,
+    FasterWhisperAdapter,
+    STTAdapter,
+    TranscriptionResult,
+    TranscriptionSegment,
+    TranscriptionWord,
+)
+from .registry import (
+    ModelBackend,
+    ModelInfo,
+    ModelProvider,
+    ModelRegistry,
+    ModelStatus,
+    ModelTask,
+    format_bytes,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "ModelRegistry",
+    "ModelInfo",
+    "ModelStatus",
+    "ModelBackend",
+    "ModelProvider",
+    "ModelTask",
+    "format_bytes",
+    "BaseAdapter",
+    "STTAdapter",
+    "TranscriptionResult",
+    "TranscriptionSegment",
+    "TranscriptionWord",
+    "FasterWhisperAdapter",
+]

vocal_core-0.3.0/vocal_core/adapters/__init__.py

@@ -0,0 +1,29 @@
+from .base import BaseAdapter
+from .stt import (
+    FasterWhisperAdapter,
+    STTAdapter,
+    TranscriptionResult,
+    TranscriptionSegment,
+    TranscriptionWord,
+)
+from .tts import (
+    PiperTTSAdapter,
+    SimpleTTSAdapter,
+    TTSAdapter,
+    TTSResult,
+    Voice,
+)
+
+__all__ = [
+    "BaseAdapter",
+    "STTAdapter",
+    "TranscriptionResult",
+    "TranscriptionSegment",
+    "TranscriptionWord",
+    "FasterWhisperAdapter",
+    "TTSAdapter",
+    "TTSResult",
+    "Voice",
+    "SimpleTTSAdapter",
+    "PiperTTSAdapter",
+]

vocal_core-0.3.0/vocal_core/adapters/base.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+
+class BaseAdapter(ABC):
+    """Base interface for model adapters (STT, TTS, etc.)"""
+
+    @abstractmethod
+    async def load_model(self, model_path: Path, device: str = "auto", **kwargs) -> None:
+        """
+        Load model from local path
+
+        Args:
+            model_path: Path to model files
+            device: Device to load model on ('cpu', 'cuda', 'auto')
+            **kwargs: Additional backend-specific parameters
+        """
+        pass
+
+    @abstractmethod
+    async def unload_model(self) -> None:
+        """Unload model from memory"""
+        pass
+
+    @abstractmethod
+    def is_loaded(self) -> bool:
+        """Check if model is currently loaded"""
+        pass
+
+    @abstractmethod
+    def get_model_info(self) -> dict[str, Any]:
+        """Get information about the loaded model"""
+        pass

vocal_core-0.3.0/vocal_core/adapters/stt/__init__.py

@@ -0,0 +1,15 @@
+from .base import (
+    STTAdapter,
+    TranscriptionResult,
+    TranscriptionSegment,
+    TranscriptionWord,
+)
+from .faster_whisper import FasterWhisperAdapter
+
+__all__ = [
+    "STTAdapter",
+    "TranscriptionResult",
+    "TranscriptionSegment",
+    "TranscriptionWord",
+    "FasterWhisperAdapter",
+]

vocal_core-0.3.0/vocal_core/adapters/stt/base.py

@@ -0,0 +1,70 @@
+from abc import abstractmethod
+from pathlib import Path
+from typing import BinaryIO
+
+from pydantic import BaseModel
+
+from ..base import BaseAdapter
+
+
+class TranscriptionSegment(BaseModel):
+    """A segment of transcribed text with timing"""
+
+    id: int
+    start: float
+    end: float
+    text: str
+    tokens: list[int] | None = None
+    temperature: float | None = None
+    avg_logprob: float | None = None
+    compression_ratio: float | None = None
+    no_speech_prob: float | None = None
+
+
+class TranscriptionWord(BaseModel):
+    """Word-level timestamp"""
+
+    word: str
+    start: float
+    end: float
+    probability: float | None = None
+
+
+class TranscriptionResult(BaseModel):
+    """Transcription result"""
+
+    text: str
+    language: str
+    duration: float
+    segments: list[TranscriptionSegment] | None = None
+    words: list[TranscriptionWord] | None = None
+
+
+class STTAdapter(BaseAdapter):
+    """Base interface for Speech-to-Text adapters"""
+
+    @abstractmethod
+    async def transcribe(
+        self,
+        audio: str | Path | BinaryIO,
+        language: str | None = None,
+        task: str = "transcribe",
+        temperature: float = 0.0,
+        word_timestamps: bool = False,
+        **kwargs,
+    ) -> TranscriptionResult:
+        """
+        Transcribe audio to text
+
+        Args:
+            audio: Audio file path or file-like object
+            language: Language code (ISO 639-1) or None for auto-detect
+            task: Task type ('transcribe' or 'translate')
+            temperature: Sampling temperature (0.0 = greedy)
+            word_timestamps: Whether to include word-level timestamps
+            **kwargs: Additional backend-specific parameters
+
+        Returns:
+            TranscriptionResult with text and metadata
+        """
+        pass

vocal_core-0.3.0/vocal_core/adapters/stt/faster_whisper.py

@@ -0,0 +1,218 @@
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, BinaryIO
+
+from faster_whisper import WhisperModel
+
+from ...utils import optimize_inference_settings
+from .base import (
+    STTAdapter,
+    TranscriptionResult,
+    TranscriptionSegment,
+    TranscriptionWord,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FasterWhisperAdapter(STTAdapter):
+    """
+    faster-whisper implementation with GPU optimization
+
+    Automatically detects and uses GPU when available for 4x+ faster inference.
+    Falls back to optimized CPU inference when GPU is not available.
+    """
+
+    def __init__(self):
+        self.model: WhisperModel | None = None
+        self.model_path: Path | None = None
+        self.device: str = "auto"
+        self.compute_type: str = "auto"
+
+    async def load_model(
+        self,
+        model_path: Path,
+        device: str = "auto",
+        compute_type: str = "auto",
+        **kwargs,
+    ) -> None:
+        """
+        Load Whisper model with optimal settings
+
+        Args:
+            model_path: Path to model files
+            device: Device to use ('cpu', 'cuda', 'auto')
+            compute_type: Compute type ('int8', 'int8_float16', 'float16', 'float32', 'auto')
+            **kwargs: Additional faster-whisper parameters
+        """
+        if self.model is not None:
+            await self.unload_model()
+
+        self.model_path = model_path
+
+        model_size = "base"
+        if "tiny" in str(model_path):
+            model_size = "tiny"
+        elif "small" in str(model_path):
+            model_size = "small"
+        elif "medium" in str(model_path):
+            model_size = "medium"
+        elif "large" in str(model_path):
+            model_size = "large"
+
+        settings = optimize_inference_settings(device, model_size)
+
+        self.device = settings["device"]
+        self.compute_type = settings["compute_type"] if compute_type == "auto" else compute_type
+
+        load_kwargs = {
+            "device": self.device,
+            "compute_type": self.compute_type,
+        }
+
+        if self.device == "cpu" and "num_workers" in settings:
+            load_kwargs["num_workers"] = settings["num_workers"]
+            load_kwargs["cpu_threads"] = settings.get("cpu_threads", 0)
+
+        load_kwargs.update(kwargs)
+
+        logger.info(f"Loading model from {model_path} on {self.device} with compute_type={self.compute_type}")
+
+        self.model = WhisperModel(str(model_path), **load_kwargs)
+
+        logger.info(f"Model loaded successfully on {self.device}")
+
+    async def unload_model(self) -> None:
+        """Unload model from memory and free GPU/CPU resources"""
+        if self.model is not None:
+            del self.model
+            self.model = None
+            self.model_path = None
+
+            if self.device == "cuda":
+                try:
+                    import torch
+
+                    torch.cuda.empty_cache()
+                    logger.info("GPU memory cleared")
+                except Exception as e:
+                    logger.warning(f"Failed to clear GPU cache: {e}")
+
+    def is_loaded(self) -> bool:
+        """Check if model is loaded"""
+        return self.model is not None
+
+    def get_model_info(self) -> dict[str, Any]:
+        """Get model information including device and optimization details"""
+        info = {
+            "model_path": str(self.model_path) if self.model_path else None,
+            "device": self.device,
+            "compute_type": self.compute_type,
+            "loaded": self.is_loaded(),
+        }
+
+        if self.device == "cuda":
+            try:
+                import torch
+
+                if torch.cuda.is_available():
+                    info["gpu_name"] = torch.cuda.get_device_name(0)
+                    info["vram_allocated_gb"] = torch.cuda.memory_allocated(0) / (1024**3)
+                    info["vram_total_gb"] = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+            except Exception:
+                pass
+
+        return info
+
+    async def transcribe(
+        self,
+        audio: str | Path | BinaryIO,
+        language: str | None = None,
+        task: str = "transcribe",
+        temperature: float = 0.0,
+        word_timestamps: bool = False,
+        beam_size: int = 5,
+        vad_filter: bool = True,
+        **kwargs,
+    ) -> TranscriptionResult:
+        """
+        Transcribe audio with optimized settings
+
+        Args:
+            audio: Audio file path or file-like object
+            language: Language code or None for auto-detect
+            task: 'transcribe' or 'translate'
+            temperature: Sampling temperature (0.0 for greedy)
+            word_timestamps: Enable word-level timestamps
+            beam_size: Beam size (5 is a good balance, 1 for faster greedy decoding)
+            vad_filter: Enable Voice Activity Detection for better performance
+            **kwargs: Additional faster-whisper parameters
+
+        Returns:
+            TranscriptionResult with text and metadata
+        """
+        if not self.is_loaded():
+            raise RuntimeError("Model not loaded. Call load_model() first.")
+
+        temp_file = None
+        try:
+            if isinstance(audio, (str, Path)):
+                audio_path = str(audio)
+            else:
+                temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".audio")
+                temp_file.write(audio.read())
+                temp_file.close()
+                audio_path = temp_file.name
+
+            transcribe_kwargs = {
+                "language": language,
+                "task": task,
+                "temperature": temperature,
+                "word_timestamps": word_timestamps,
+                "beam_size": beam_size,
+                "vad_filter": vad_filter,
+            }
+            transcribe_kwargs.update(kwargs)
+
+            segments, info = self.model.transcribe(audio_path, **transcribe_kwargs)
+
+            segments_list = []
+            words_list = []
+            full_text = []
+
+            for idx, segment in enumerate(segments):
+                full_text.append(segment.text)
+
+                seg = TranscriptionSegment(
+                    id=idx,
+                    start=segment.start,
+                    end=segment.end,
+                    text=segment.text,
+                    avg_logprob=segment.avg_logprob,
+                    no_speech_prob=segment.no_speech_prob,
+                )
+                segments_list.append(seg)
+
+                if word_timestamps and hasattr(segment, "words"):
+                    for word in segment.words:
+                        words_list.append(
+                            TranscriptionWord(
+                                word=word.word,
+                                start=word.start,
+                                end=word.end,
+                                probability=word.probability if hasattr(word, "probability") else None,
+                            )
+                        )
+
+            return TranscriptionResult(
+                text=" ".join(full_text).strip(),
+                language=info.language,
+                duration=info.duration if hasattr(info, "duration") else 0.0,
+                segments=segments_list if segments_list else None,
+                words=words_list if words_list else None,
+            )
+
+        finally:
+            if temp_file and Path(temp_file.name).exists():
+                Path(temp_file.name).unlink()

vocal_core-0.3.0/vocal_core/adapters/tts/__init__.py

@@ -0,0 +1,4 @@
+from .base import TTSAdapter, TTSResult, Voice
+from .piper import PiperTTSAdapter, SimpleTTSAdapter
+
+__all__ = ["TTSAdapter", "TTSResult", "Voice", "SimpleTTSAdapter", "PiperTTSAdapter"]

vocal_core-0.3.0/vocal_core/adapters/tts/base.py

@@ -0,0 +1,63 @@
+from abc import abstractmethod
+
+from pydantic import BaseModel
+
+from ..base import BaseAdapter
+
+
+class Voice(BaseModel):
+    """Voice configuration for TTS"""
+
+    id: str
+    name: str
+    language: str
+    gender: str | None = None
+
+
+class TTSResult(BaseModel):
+    """Text-to-Speech result"""
+
+    audio_data: bytes
+    sample_rate: int
+    duration: float
+    format: str
+
+
+class TTSAdapter(BaseAdapter):
+    """Base interface for Text-to-Speech adapters"""
+
+    @abstractmethod
+    async def synthesize(
+        self,
+        text: str,
+        voice: str | None = None,
+        speed: float = 1.0,
+        pitch: float = 1.0,
+        output_format: str = "wav",
+        **kwargs,
+    ) -> TTSResult:
+        """
+        Synthesize text to speech
+
+        Args:
+            text: Text to convert to speech
+            voice: Voice ID to use (None for default)
+            speed: Speech speed multiplier (1.0 = normal)
+            pitch: Voice pitch multiplier (1.0 = normal)
+            output_format: Output audio format (wav, mp3, etc.)
+            **kwargs: Additional backend-specific parameters
+
+        Returns:
+            TTSResult with audio data and metadata
+        """
+        pass
+
+    @abstractmethod
+    async def get_voices(self) -> list[Voice]:
+        """
+        Get list of available voices
+
+        Returns:
+            List of Voice objects
+        """
+        pass