spaik-sdk 0.6.2__py3-none-any.whl

spaik_sdk/attachments/storage/impl/local_file_storage.py

@@ -0,0 +1,101 @@
+import json
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from spaik_sdk.attachments.models import FileMetadata
+from spaik_sdk.attachments.storage.base_file_storage import BaseFileStorage
+
+
+class LocalFileStorage(BaseFileStorage):
+    def __init__(self, data_dir: str = "data/files"):
+        self.data_dir = Path(data_dir)
+        self.files_dir = self.data_dir / "content"
+        self.metadata_dir = self.data_dir / "metadata"
+
+        self.files_dir.mkdir(parents=True, exist_ok=True)
+        self.metadata_dir.mkdir(parents=True, exist_ok=True)
+
+    def _file_path(self, file_id: str) -> Path:
+        return self.files_dir / file_id
+
+    def _metadata_path(self, file_id: str) -> Path:
+        return self.metadata_dir / f"{file_id}.json"
+
+    def _save_metadata(self, metadata: FileMetadata) -> None:
+        with open(self._metadata_path(metadata.file_id), "w") as f:
+            json.dump(metadata.to_dict(), f)
+
+    def _load_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        metadata_path = self._metadata_path(file_id)
+        if not metadata_path.exists():
+            return None
+        try:
+            with open(metadata_path, "r") as f:
+                return FileMetadata.from_dict(json.load(f))
+        except (json.JSONDecodeError, KeyError):
+            return None
+
+    async def store(
+        self,
+        data: bytes,
+        mime_type: str,
+        owner_id: str,
+        filename: Optional[str] = None,
+    ) -> FileMetadata:
+        file_id = str(uuid.uuid4())
+
+        file_path = self._file_path(file_id)
+        with open(file_path, "wb") as f:
+            f.write(data)
+
+        metadata = FileMetadata(
+            file_id=file_id,
+            mime_type=mime_type,
+            owner_id=owner_id,
+            size_bytes=len(data),
+            filename=filename,
+        )
+        self._save_metadata(metadata)
+
+        return metadata
+
+    async def retrieve(self, file_id: str) -> tuple[bytes, FileMetadata]:
+        metadata = await self.get_metadata(file_id)
+        if metadata is None:
+            raise FileNotFoundError(f"File not found: {file_id}")
+
+        file_path = self._file_path(file_id)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File content not found: {file_id}")
+
+        with open(file_path, "rb") as f:
+            data = f.read()
+
+        return data, metadata
+
+    async def get_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        return self._load_metadata(file_id)
+
+    async def delete(self, file_id: str) -> bool:
+        file_path = self._file_path(file_id)
+        metadata_path = self._metadata_path(file_id)
+
+        deleted = False
+        if file_path.exists():
+            file_path.unlink()
+            deleted = True
+        if metadata_path.exists():
+            metadata_path.unlink()
+            deleted = True
+
+        return deleted
+
+    async def exists(self, file_id: str) -> bool:
+        return self._file_path(file_id).exists() and self._metadata_path(file_id).exists()
+
+    def clear_all(self) -> None:
+        for file_path in self.files_dir.glob("*"):
+            file_path.unlink()
+        for metadata_path in self.metadata_dir.glob("*.json"):
+            metadata_path.unlink()

spaik_sdk/audio/__init__.py

@@ -0,0 +1,12 @@
+from spaik_sdk.audio.options import AudioFormat, STTOptions, TTSOptions, TTSVoice
+from spaik_sdk.audio.stt import SpeechToText
+from spaik_sdk.audio.tts import TextToSpeech
+
+__all__ = [
+    "TextToSpeech",
+    "SpeechToText",
+    "TTSOptions",
+    "STTOptions",
+    "TTSVoice",
+    "AudioFormat",
+]

spaik_sdk/audio/options.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class AudioFormat(Enum):
+    MP3 = "mp3"
+    OPUS = "opus"
+    AAC = "aac"
+    FLAC = "flac"
+    WAV = "wav"
+    PCM = "pcm"
+
+
+class TTSVoice(Enum):
+    """Common TTS voices across providers."""
+
+    # OpenAI voices
+    ALLOY = "alloy"
+    ECHO = "echo"
+    FABLE = "fable"
+    ONYX = "onyx"
+    NOVA = "nova"
+    SHIMMER = "shimmer"
+
+    # Gemini voices (subset)
+    ZEPHYR = "Zephyr"
+    PUCK = "Puck"
+    CHARON = "Charon"
+    KORE = "Kore"
+    FENRIR = "Fenrir"
+    AOEDE = "Aoede"
+
+
+@dataclass
+class TTSOptions:
+    """Options for text-to-speech synthesis."""
+
+    voice: str = "alloy"
+    speed: float = 1.0
+    output_format: AudioFormat = AudioFormat.MP3
+    language: str | None = None
+    vendor: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class STTOptions:
+    """Options for speech-to-text transcription."""
+
+    language: str | None = None
+    prompt: str | None = None
+    temperature: float = 0.0
+    vendor: dict[str, Any] = field(default_factory=dict)

spaik_sdk/audio/providers/__init__.py

@@ -0,0 +1 @@
+# Audio providers

spaik_sdk/audio/providers/google_tts.py

@@ -0,0 +1,77 @@
+import base64
+
+import httpx
+
+from spaik_sdk.audio.options import TTSOptions
+
+GOOGLE_GENERATIVE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models"
+
+
+async def synthesize(
+    text: str,
+    model: str,
+    api_key: str,
+    options: TTSOptions,
+    endpoint: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> bytes:
+    """
+    Synthesize speech using Google's Gemini TTS API.
+
+    Args:
+        text: The text to convert to speech
+        model: The model to use (e.g., "gemini-2.5-flash-tts", "gemini-2.5-pro-tts")
+        api_key: Google API key
+        options: TTS options
+        endpoint: Optional custom endpoint
+        headers: Optional additional headers
+
+    Returns:
+        Audio bytes (WAV format from Gemini)
+    """
+    base_url = endpoint or GOOGLE_GENERATIVE_ENDPOINT
+    url = f"{base_url}/{model}:generateContent?key={api_key}"
+
+    request_headers = {
+        "Content-Type": "application/json",
+    }
+    if headers:
+        request_headers.update(headers)
+
+    # Build the speech config
+    speech_config: dict = {
+        "voiceConfig": {
+            "prebuiltVoiceConfig": {
+                "voiceName": options.voice,
+            }
+        }
+    }
+
+    generation_config: dict = {
+        "responseModalities": ["AUDIO"],
+        "speechConfig": speech_config,
+    }
+    generation_config.update(options.vendor)
+
+    payload = {
+        "contents": [{"parts": [{"text": text}]}],
+        "generationConfig": generation_config,
+    }
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        response = await client.post(url, headers=request_headers, json=payload)
+        if response.status_code != 200:
+            raise ValueError(f"Google TTS API error {response.status_code}: {response.text}")
+        data = response.json()
+
+    candidates = data.get("candidates", [])
+    if not candidates:
+        raise ValueError("No audio generated by Gemini TTS API")
+
+    parts = candidates[0].get("content", {}).get("parts", [])
+    for part in parts:
+        if "inlineData" in part:
+            audio_b64 = part["inlineData"]["data"]
+            return base64.b64decode(audio_b64)
+
+    raise ValueError("No audio data found in Gemini TTS API response")

spaik_sdk/audio/providers/openai_stt.py

@@ -0,0 +1,71 @@
+import httpx
+
+from spaik_sdk.audio.options import STTOptions
+
+OPENAI_STT_ENDPOINT = "https://api.openai.com/v1/audio/transcriptions"
+
+
+async def transcribe(
+    audio_bytes: bytes,
+    model: str,
+    api_key: str,
+    options: STTOptions,
+    filename: str = "audio.webm",
+    endpoint: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> str:
+    """
+    Transcribe audio using OpenAI's Whisper API.
+
+    Args:
+        audio_bytes: The audio data to transcribe
+        model: The model to use (e.g., "whisper-1", "gpt-4o-transcribe")
+        api_key: OpenAI API key
+        options: STT options
+        filename: Filename hint for the audio format
+        endpoint: Optional custom endpoint
+        headers: Optional additional headers
+
+    Returns:
+        Transcribed text
+    """
+    url = endpoint or OPENAI_STT_ENDPOINT
+
+    request_headers = {
+        "Authorization": f"Bearer {api_key}",
+    }
+    if headers:
+        request_headers.update(headers)
+
+    # Determine content type from filename
+    content_type = "audio/webm"
+    if filename.endswith(".mp3"):
+        content_type = "audio/mpeg"
+    elif filename.endswith(".wav"):
+        content_type = "audio/wav"
+    elif filename.endswith(".m4a"):
+        content_type = "audio/mp4"
+    elif filename.endswith(".ogg"):
+        content_type = "audio/ogg"
+
+    # Build multipart form data
+    files = {
+        "file": (filename, audio_bytes, content_type),
+    }
+    data: dict[str, str] = {
+        "model": model,
+        "response_format": "text",
+    }
+
+    if options.language:
+        data["language"] = options.language
+    if options.prompt:
+        data["prompt"] = options.prompt
+    if options.temperature > 0:
+        data["temperature"] = str(options.temperature)
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        response = await client.post(url, headers=request_headers, files=files, data=data)
+        if response.status_code != 200:
+            raise ValueError(f"OpenAI STT API error {response.status_code}: {response.text}")
+        return response.text.strip()

spaik_sdk/audio/providers/openai_tts.py

@@ -0,0 +1,111 @@
+from collections.abc import AsyncIterator
+
+import httpx
+
+from spaik_sdk.audio.options import AudioFormat, TTSOptions
+
+OPENAI_TTS_ENDPOINT = "https://api.openai.com/v1/audio/speech"
+
+
+def _get_format_map() -> dict[AudioFormat, str]:
+    return {
+        AudioFormat.MP3: "mp3",
+        AudioFormat.OPUS: "opus",
+        AudioFormat.AAC: "aac",
+        AudioFormat.FLAC: "flac",
+        AudioFormat.WAV: "wav",
+        AudioFormat.PCM: "pcm",
+    }
+
+
+def _build_payload(text: str, model: str, options: TTSOptions) -> dict:
+    format_map = _get_format_map()
+    payload: dict = {
+        "model": model,
+        "input": text,
+        "voice": options.voice,
+        "response_format": format_map.get(options.output_format, "mp3"),
+        "speed": options.speed,
+    }
+    payload.update(options.vendor)
+    return payload
+
+
+def _build_headers(api_key: str, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    if extra_headers:
+        headers.update(extra_headers)
+    return headers
+
+
+async def synthesize(
+    text: str,
+    model: str,
+    api_key: str,
+    options: TTSOptions,
+    endpoint: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> bytes:
+    """
+    Synthesize speech using OpenAI's TTS API.
+
+    Args:
+        text: The text to convert to speech
+        model: The model to use (e.g., "tts-1", "tts-1-hd", "gpt-4o-mini-tts")
+        api_key: OpenAI API key
+        options: TTS options
+        endpoint: Optional custom endpoint
+        headers: Optional additional headers
+
+    Returns:
+        Audio bytes in the specified format
+    """
+    url = endpoint or OPENAI_TTS_ENDPOINT
+    request_headers = _build_headers(api_key, headers)
+    payload = _build_payload(text, model, options)
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        response = await client.post(url, headers=request_headers, json=payload)
+        if response.status_code != 200:
+            raise ValueError(f"OpenAI TTS API error {response.status_code}: {response.text}")
+        return response.content
+
+
+async def synthesize_stream(
+    text: str,
+    model: str,
+    api_key: str,
+    options: TTSOptions,
+    endpoint: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> AsyncIterator[bytes]:
+    """
+    Stream synthesized speech using OpenAI's TTS API.
+
+    Yields audio chunks as they arrive, allowing playback to start immediately.
+
+    Args:
+        text: The text to convert to speech
+        model: The model to use (e.g., "tts-1", "tts-1-hd", "gpt-4o-mini-tts")
+        api_key: OpenAI API key
+        options: TTS options
+        endpoint: Optional custom endpoint
+        headers: Optional additional headers
+
+    Yields:
+        Audio bytes chunks
+    """
+    url = endpoint or OPENAI_TTS_ENDPOINT
+    request_headers = _build_headers(api_key, headers)
+    payload = _build_payload(text, model, options)
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        async with client.stream("POST", url, headers=request_headers, json=payload) as response:
+            if response.status_code != 200:
+                content = await response.aread()
+                raise ValueError(f"OpenAI TTS API error {response.status_code}: {content.decode()}")
+            async for chunk in response.aiter_bytes(chunk_size=4096):
+                yield chunk

spaik_sdk/audio/stt.py

@@ -0,0 +1,61 @@
+from spaik_sdk.audio.options import STTOptions
+from spaik_sdk.audio.providers import openai_stt
+from spaik_sdk.config.env import env_config
+from spaik_sdk.config.get_credentials_provider import credentials_provider
+
+
+class SpeechToText:
+    """
+    Speech-to-text transcriber using OpenAI Whisper.
+
+    Note: Only OpenAI is supported for STT as Gemini doesn't have
+    a dedicated speech-to-text API endpoint.
+    """
+
+    def __init__(
+        self,
+        model: str | None = None,
+        endpoint: str | None = None,
+        headers: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the SpeechToText transcriber.
+
+        Args:
+            model: STT model name. If None, uses STT_MODEL env var or defaults to whisper-1.
+            endpoint: Optional custom API endpoint.
+            headers: Optional additional HTTP headers.
+        """
+        self.model = model or env_config.get_key("STT_MODEL", "whisper-1", required=False)
+        self.endpoint = endpoint
+        self.headers = headers
+
+    async def transcribe(
+        self,
+        audio_bytes: bytes,
+        options: STTOptions | None = None,
+        filename: str = "audio.webm",
+    ) -> str:
+        """
+        Transcribe audio to text.
+
+        Args:
+            audio_bytes: The audio data to transcribe.
+            options: STT options (language, prompt hint, etc.)
+            filename: Filename hint for audio format detection.
+
+        Returns:
+            Transcribed text string.
+        """
+        opts = options or STTOptions()
+        api_key = credentials_provider.get_provider_key("openai")
+
+        return await openai_stt.transcribe(
+            audio_bytes=audio_bytes,
+            model=self.model,
+            api_key=api_key,
+            options=opts,
+            filename=filename,
+            endpoint=self.endpoint,
+            headers=self.headers,
+        )

spaik_sdk/audio/tts.py

@@ -0,0 +1,124 @@
+from collections.abc import AsyncIterator
+
+from spaik_sdk.audio.options import TTSOptions
+from spaik_sdk.audio.providers import google_tts, openai_tts
+from spaik_sdk.config.env import env_config
+from spaik_sdk.config.get_credentials_provider import credentials_provider
+
+
+class TextToSpeech:
+    """
+    Text-to-speech synthesizer supporting multiple providers.
+
+    Automatically detects the provider based on the model name.
+    Supports OpenAI (tts-1, tts-1-hd, gpt-4o-mini-tts) and
+    Google Gemini (gemini-2.5-flash-tts, gemini-2.5-pro-tts).
+    """
+
+    def __init__(
+        self,
+        model: str | None = None,
+        endpoint: str | None = None,
+        headers: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the TextToSpeech synthesizer.
+
+        Args:
+            model: TTS model name. If None, uses TTS_MODEL env var.
+            endpoint: Optional custom API endpoint.
+            headers: Optional additional HTTP headers.
+        """
+        self.model = model or env_config.get_key("TTS_MODEL", "tts-1", required=False)
+        self.endpoint = endpoint
+        self.headers = headers
+
+    def _get_provider(self) -> str:
+        """Determine the provider based on model name."""
+        model_lower = self.model.lower()
+        if model_lower.startswith("tts-") or model_lower.startswith("gpt-"):
+            return "openai"
+        elif model_lower.startswith("gemini"):
+            return "google"
+        else:
+            raise ValueError(f"Unknown TTS model provider for: {self.model}")
+
+    async def synthesize(
+        self,
+        text: str,
+        options: TTSOptions | None = None,
+    ) -> bytes:
+        """
+        Synthesize speech from text.
+
+        Args:
+            text: The text to convert to speech.
+            options: TTS options (voice, speed, format, etc.)
+
+        Returns:
+            Audio bytes in the specified format.
+        """
+        opts = options or TTSOptions()
+        provider = self._get_provider()
+
+        if provider == "openai":
+            api_key = credentials_provider.get_provider_key("openai")
+            return await openai_tts.synthesize(
+                text=text,
+                model=self.model,
+                api_key=api_key,
+                options=opts,
+                endpoint=self.endpoint,
+                headers=self.headers,
+            )
+        elif provider == "google":
+            api_key = credentials_provider.get_provider_key("google")
+            return await google_tts.synthesize(
+                text=text,
+                model=self.model,
+                api_key=api_key,
+                options=opts,
+                endpoint=self.endpoint,
+                headers=self.headers,
+            )
+        else:
+            raise ValueError(f"Unsupported TTS provider: {provider}")
+
+    async def synthesize_stream(
+        self,
+        text: str,
+        options: TTSOptions | None = None,
+    ) -> AsyncIterator[bytes]:
+        """
+        Stream synthesized speech from text.
+
+        Yields audio chunks as they arrive, allowing playback to start immediately.
+        Currently only supported for OpenAI models.
+
+        Args:
+            text: The text to convert to speech.
+            options: TTS options (voice, speed, format, etc.)
+
+        Yields:
+            Audio bytes chunks.
+        """
+        opts = options or TTSOptions()
+        provider = self._get_provider()
+
+        if provider == "openai":
+            api_key = credentials_provider.get_provider_key("openai")
+            async for chunk in openai_tts.synthesize_stream(
+                text=text,
+                model=self.model,
+                api_key=api_key,
+                options=opts,
+                endpoint=self.endpoint,
+                headers=self.headers,
+            ):
+                yield chunk
+        elif provider == "google":
+            # Google doesn't support streaming, fall back to full synthesis
+            audio_bytes = await self.synthesize(text, options)
+            yield audio_bytes
+        else:
+            raise ValueError(f"Unsupported TTS provider: {provider}")

spaik_sdk/config/credentials_provider.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+
+
+class CredentialsProvider(ABC):
+    @abstractmethod
+    def get_key(self, key: str, default: str = "", required: bool = True) -> str:
+        pass
+
+    def get_provider_key(self, provider: str) -> str:
+        return self.get_key(f"{provider.upper()}_API_KEY")

spaik_sdk/config/env.py

@@ -0,0 +1,59 @@
+import os
+from typing import Dict
+
+from spaik_sdk.models.llm_model import LLMModel
+from spaik_sdk.models.model_registry import ModelRegistry
+from spaik_sdk.models.providers.provider_type import ProviderType
+from spaik_sdk.prompt.prompt_loader_mode import PromptLoaderMode
+from spaik_sdk.tracing.trace_sink_mode import TraceSinkMode
+
+
+class EnvConfig:
+    def get_key(self, key: str, default: str = "", required: bool = True) -> str:
+        value = os.environ.get(key, default)
+        if required and not value:
+            raise ValueError(f"Environment variable {key} is required but not set")
+        return value
+
+    def get_azure_keys(self) -> Dict[str, str]:
+        return {
+            "api_key": self.get_key("AZURE_API_KEY"),
+            "api_version": self.get_key("AZURE_API_VERSION"),
+            "endpoint": self.get_key("AZURE_ENDPOINT"),
+            "o3-mini_deployment": self.get_key("AZURE_O3_MINI_DEPLOYMENT", required=False),
+            "gpt-4_1_deployment": self.get_key("AZURE_GPT_4_1_DEPLOYMENT", required=False),
+            "gpt-4o_deployment": self.get_key("AZURE_GPT_4O_DEPLOYMENT", required=False),
+        }
+
+    def get_default_model(self) -> LLMModel:
+        return ModelRegistry.from_name(self.get_key("DEFAULT_MODEL"))
+
+    def get_provider_type(self) -> ProviderType:
+        provider_type_name = self.get_key("MODEL_PROVIDER", required=False)
+        if not provider_type_name:
+            return ProviderType.from_model_name(self.get_default_model().name)
+        return ProviderType.from_name(provider_type_name)
+
+    def is_debug_mode(self, key: str) -> bool:
+        debug_modes = self.get_key("DEBUG_MODES", required=False)
+        if debug_modes:
+            return key in debug_modes.split(",")
+        return False
+
+    def get_prompts_dir(self) -> str:
+        return self.get_key("PROMPTS_DIR", "prompts")
+
+    def get_prompt_loader_mode(self) -> PromptLoaderMode:
+        return PromptLoaderMode.from_name(self.get_key("PROMPT_LOADER_MODE", "local"))
+
+    def get_trace_sink_mode(self) -> TraceSinkMode:
+        return TraceSinkMode.from_name(self.get_key("TRACE_SINK_MODE", "local"))
+
+    def get_credentials_provider_type(self) -> str:
+        return self.get_key("CREDENTIALS_PROVIDER_TYPE", "env")
+
+    def get_image_model(self) -> str:
+        return self.get_key("IMAGE_MODEL")
+
+
+env_config = EnvConfig()

spaik_sdk/config/env_credentials_provider.py

@@ -0,0 +1,7 @@
+from spaik_sdk.config.credentials_provider import CredentialsProvider
+from spaik_sdk.config.env import env_config
+
+
+class EnvCredentialsProvider(CredentialsProvider):
+    def get_key(self, key: str, default: str = "", required: bool = True) -> str:
+        return env_config.get_key(key, default, required)