fastapi-startkit 0.40.0__tar.gz → 0.41.0__tar.gz

{fastapi_startkit-0.40.0 → fastapi_startkit-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.40.0
+Version: 0.41.0
 Summary: Fastapi Starter kit components
 Author: Bedram Tamang
 Author-email: Bedram Tamang <tmgbedu@gmail.com>

{fastapi_startkit-0.40.0 → fastapi_startkit-0.41.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.40.0"
+version = "0.41.0"
 description = "Fastapi Starter kit components"
 authors = [
     {name = "Bedram Tamang", email = "tmgbedu@gmail.com"}

{fastapi_startkit-0.40.0 → fastapi_startkit-0.41.0}/src/fastapi_startkit/ai/__init__.py

@@ -2,12 +2,28 @@
 
 Provides a LangGraph-powered declarative API for building AI agents backed
 by Anthropic, OpenAI, or Google provider SDKs.
+
+Also exposes a Laravel-style fluent API for image generation and text-to-speech::
+
+    from fastapi_startkit.ai import Image, Audio, Document
+
+    image = await Image.of("A donut on a counter").generate()
+
+    # With a photo attachment
+    doc = await Document.from_url("https://example.com/photo.jpg")
+    image = await Image.of("Make impressionist").attachments([doc]).generate()
+
+    audio = await Audio.of("Hello world").female().generate()
 """
 
 from .agent import Agent
+from .audio import Audio, AudioResponse
+from .audio_factory import AudioFactory
 from .config import AIConfig, AnthropicConfig, GoogleConfig, OpenAIConfig
 from .decorators import max_steps, max_tokens, memory, model, provider, timeout, top_p
 from .document import Document
+from .image import Image, ImageResponse
+from .image_factory import ImageFactory
 from .providers.ai_provider import AIProvider
 from .response import AgentResponse, AgentSnapshot
 
@@ -18,8 +34,14 @@ __all__ = [
     "AIConfig",
     "AIProvider",
     "AnthropicConfig",
+    "Audio",
+    "AudioResponse",
+    "AudioFactory",
     "Document",
     "GoogleConfig",
+    "Image",
+    "ImageFactory",
+    "ImageResponse",
     "OpenAIConfig",
     "max_steps",
     "max_tokens",

fastapi_startkit-0.41.0/src/fastapi_startkit/ai/audio.py

@@ -0,0 +1,214 @@
+"""Audio generation API — text-to-speech via a pluggable provider."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .audio_factory import AudioFactory
+
+try:
+    from fastapi_startkit.storage.storage import Storage
+except Exception:  # pragma: no cover
+    Storage = None  # type: ignore[assignment,misc]
+
+try:
+    from fastapi_startkit import Config
+except Exception:  # pragma: no cover
+    Config = None  # type: ignore[assignment,misc]
+
+
+class AudioResponse:
+    """Returned by :meth:`Audio.generate`.
+
+    Holds raw MP3 (or other format) bytes and provides async helpers to
+    persist the audio to any configured storage disk::
+
+        audio = await Audio.of("Hello world").generate()
+
+        path = await audio.store()                     # auto-named, private disk
+        path = await audio.storeAs("greeting.mp3")     # named, private disk
+        path = await audio.storePublicly()             # auto-named, public disk
+        path = await audio.storePubliclyAs("greeting.mp3")
+    """
+
+    def __init__(self, data: bytes, fmt: str = "mp3"):
+        self._data = data
+        self._fmt = fmt
+
+    @property
+    def data(self) -> bytes:
+        """Raw audio bytes."""
+        return self._data
+
+    def _auto_filename(self) -> str:
+        return f"{uuid.uuid4()}.{self._fmt}"
+
+    # ── Storage helpers ────────────────────────────────────────────────────────
+
+    async def store(self) -> str:
+        """Save to the default private disk with an auto-generated filename."""
+        return await self._save(self._auto_filename(), disk="local")
+
+    async def storeAs(self, name: str) -> str:
+        """Save to the default private disk with a custom filename."""
+        return await self._save(name, disk="local")
+
+    async def storePublicly(self) -> str:
+        """Save to the public disk with an auto-generated filename."""
+        return await self._save(self._auto_filename(), disk="public")
+
+    async def storePubliclyAs(self, name: str) -> str:
+        """Save to the public disk with a custom filename."""
+        return await self._save(name, disk="public")
+
+    # ── Internal ───────────────────────────────────────────────────────────────
+
+    async def _save(self, name: str, disk: str = "local") -> str:
+        return await asyncio.to_thread(self._save_sync, name, disk)
+
+    def _save_sync(self, name: str, disk: str) -> str:
+        """Try the Storage facade first; fall back to a temp file."""
+        if Storage is not None:
+            try:
+                Storage.disk(disk).put(name, self._data)
+                return name
+            except Exception:
+                pass
+        import os
+        import tempfile
+
+        path = os.path.join(tempfile.gettempdir(), name)
+        with open(path, "wb") as f:
+            f.write(self._data)
+        return path
+
+
+class Audio:
+    """Fluent builder for text-to-speech generation.
+
+    The active backend is selected from :attr:`~fastapi_startkit.ai.AIConfig.audio_provider`
+    (env: ``AI_AUDIO_PROVIDER``). Defaults to OpenAI TTS.
+
+    Usage::
+
+        audio = await Audio.of("Hello world").generate()
+        audio = await Audio.of("Hello world").female().generate()
+        audio = await Audio.of("Hello world").male().generate()
+        audio = await Audio.of("Hello world").voice("nova").generate()
+
+    Available OpenAI TTS voices: alloy, echo, fable, onyx, nova, shimmer.
+    """
+
+    # OpenAI TTS voice presets
+    _DEFAULT_VOICE = "alloy"
+    _DEFAULT_FEMALE_VOICE = "nova"
+    _DEFAULT_MALE_VOICE = "onyx"
+
+    def __init__(self, text: str):
+        self._text = text
+        self._voice: str = self._DEFAULT_VOICE
+        self._model: str = "tts-1"
+        self._speed: float = 1.0
+        self._response_format: str = "mp3"
+
+    @classmethod
+    def of(cls, text: str) -> "Audio":
+        """Create an :class:`Audio` builder with the given input text."""
+        return cls(text)
+
+    # ── Modifier methods (chainable) ───────────────────────────────────────────
+
+    def female(self) -> "Audio":
+        """Use a female voice (``nova``)."""
+        self._voice = self._DEFAULT_FEMALE_VOICE
+        return self
+
+    def male(self) -> "Audio":
+        """Use a male voice (``onyx``)."""
+        self._voice = self._DEFAULT_MALE_VOICE
+        return self
+
+    def voice(self, name: str) -> "Audio":
+        """Set an explicit TTS voice name.
+
+        OpenAI voices: ``alloy``, ``echo``, ``fable``, ``onyx``, ``nova``,
+        ``shimmer``.
+        """
+        self._voice = name
+        return self
+
+    def model(self, name: str) -> "Audio":
+        """Override the TTS model (default: ``tts-1``).
+
+        Use ``tts-1-hd`` for higher quality at the cost of latency.
+        """
+        self._model = name
+        return self
+
+    def speed(self, value: float) -> "Audio":
+        """Set speech speed (0.25 – 4.0, default: 1.0)."""
+        self._speed = value
+        return self
+
+    def format(self, fmt: str) -> "Audio":
+        """Set output format: ``mp3``, ``opus``, ``aac``, or ``flac``."""
+        self._response_format = fmt
+        return self
+
+    # ── Generation ─────────────────────────────────────────────────────────────
+
+    async def generate(self) -> AudioResponse:
+        """Call the configured TTS provider and return an :class:`AudioResponse`."""
+        provider = self._resolve_provider()
+        data = await provider.synthesize(
+            text=self._text,
+            voice=self._voice,
+            model=self._model,
+            speed=self._speed,
+            fmt=self._response_format,
+        )
+        return AudioResponse(data=data, fmt=self._response_format)
+
+    # ── Internal ───────────────────────────────────────────────────────────────
+
+    def _resolve_provider(self) -> "AudioFactory":
+        from .audio_factory import (  # noqa: PLC0415
+            ElevenLabsAudioFactory,
+            GoogleAudioFactory,
+            OpenAIAudioFactory,
+        )
+
+        provider_name = "openai"
+        api_key: Optional[str] = None
+        base_url: Optional[str] = None
+        google_key: Optional[str] = None
+        elevenlabs_key: Optional[str] = None
+
+        try:
+            ai_config = Config.get("ai") if Config is not None else None  # type: ignore[union-attr]
+            if ai_config is None:
+                raise RuntimeError("Config not available")
+            provider_name = ai_config.audio_provider
+            openai_cfg = ai_config.providers.get("openai")
+            if openai_cfg:
+                api_key = openai_cfg.key or None
+                base_url = openai_cfg.url or None
+            google_cfg = ai_config.providers.get("google")
+            if google_cfg:
+                google_key = google_cfg.key or None
+            el_cfg = ai_config.providers.get("elevenlabs")
+            if el_cfg:
+                elevenlabs_key = el_cfg.key or None
+        except Exception:
+            pass
+
+        if provider_name == "openai":
+            return OpenAIAudioFactory(api_key=api_key, base_url=base_url)
+        if provider_name == "google":
+            return GoogleAudioFactory(api_key=google_key)
+        if provider_name == "elevenlabs":
+            return ElevenLabsAudioFactory(api_key=elevenlabs_key)
+        raise ValueError(f"Unknown audio provider: {provider_name!r}. Use 'openai', 'google', or 'elevenlabs'.")

fastapi_startkit-0.41.0/src/fastapi_startkit/ai/audio_factory.py

@@ -0,0 +1,260 @@
+"""Audio synthesis provider abstractions.
+
+Providers implement the :class:`AudioFactory` ABC so that the
+:class:`~fastapi_startkit.ai.Audio` builder is not hard-wired to a single
+vendor.  Select the active provider via ``AI_AUDIO_PROVIDER`` in your
+``.env`` (or ``AIConfig.audio_provider``).
+
+Supported providers
+-------------------
+* ``openai``     — OpenAI TTS (tts-1 / tts-1-hd) (default)
+* ``google``     — Google Gemini TTS via the ``google-genai`` SDK
+* ``elevenlabs`` — ElevenLabs TTS via the ``elevenlabs`` SDK
+"""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+from abc import ABC, abstractmethod
+
+
+class AudioFactory(ABC):
+    """Abstract base for text-to-speech backends."""
+
+    @abstractmethod
+    async def synthesize(
+        self,
+        text: str,
+        voice: str,
+        model: str,
+        speed: float,
+        fmt: str,
+    ) -> bytes:
+        """Convert *text* to speech and return raw audio bytes."""
+
+
+class OpenAIAudioFactory(AudioFactory):
+    """OpenAI TTS provider using :class:`openai.AsyncOpenAI`.
+
+    Supported voices: ``alloy``, ``echo``, ``fable``, ``onyx``, ``nova``,
+    ``shimmer``.  Supported formats: ``mp3``, ``opus``, ``aac``, ``flac``.
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+        self._api_key = api_key
+        self._base_url = base_url
+
+    async def synthesize(
+        self,
+        text: str,
+        voice: str,
+        model: str,
+        speed: float,
+        fmt: str,
+    ) -> bytes:
+        from openai import AsyncOpenAI  # noqa: PLC0415
+
+        client = AsyncOpenAI(api_key=self._api_key, base_url=self._base_url)
+        response = await client.audio.speech.create(
+            model=model,
+            voice=voice,
+            input=text,
+            speed=speed,
+            response_format=fmt,
+        )
+        return response.read()
+
+
+class GoogleAudioFactory(AudioFactory):
+    """Google Gemini TTS provider via the ``google-genai`` SDK.
+
+    Requires: ``pip install google-genai``
+
+    Configure via ``.env``::
+
+        AI_AUDIO_PROVIDER=google
+        GEMINI_API_KEY=your-key        # or GOOGLE_API_KEY
+
+    Default model: ``gemini-2.5-flash-preview-tts``.
+
+    Google voice names (pass via :meth:`~fastapi_startkit.ai.Audio.voice`):
+    ``Kore``, ``Aoede``, ``Puck``, ``Charon``, ``Fenrir``, ``Leda``,
+    ``Orus``, ``Zephyr``.
+
+    OpenAI-compatible voice aliases are also accepted and mapped
+    automatically:
+
+    +----------+-------------+
+    | Alias    | Google voice|
+    +==========+=============+
+    | nova     | Aoede       |
+    | alloy    | Kore        |
+    | echo     | Charon      |
+    | fable    | Puck        |
+    | onyx     | Fenrir      |
+    | shimmer  | Leda        |
+    +----------+-------------+
+
+    The provider returns **WAV** bytes regardless of the requested format,
+    because Gemini TTS yields raw PCM16 which is wrapped in a WAV container.
+    """
+
+    # Map OpenAI-style voice aliases → Google Gemini voice names
+    _VOICE_MAP: dict[str, str] = {
+        "nova": "Aoede",
+        "alloy": "Kore",
+        "echo": "Charon",
+        "fable": "Puck",
+        "onyx": "Fenrir",
+        "shimmer": "Leda",
+    }
+
+    def __init__(self, api_key: str | None = None):
+        self._api_key = api_key
+
+    async def synthesize(
+        self,
+        text: str,
+        voice: str,
+        model: str,
+        speed: float,
+        fmt: str,
+    ) -> bytes:
+        """Synthesise *text* via Gemini TTS and return WAV bytes.
+
+        .. note::
+            The ``speed`` parameter is accepted for API compatibility but is
+            not currently supported by the Gemini TTS API.
+        """
+        from google import genai  # noqa: PLC0415
+        from google.genai import types  # noqa: PLC0415
+
+        client = genai.Client(api_key=self._api_key)
+        google_voice = self._VOICE_MAP.get(voice, voice)
+
+        response = await asyncio.to_thread(
+            client.models.generate_content,
+            model=model,
+            contents=text,
+            config=types.GenerateContentConfig(
+                response_modalities=["AUDIO"],
+                speech_config=types.SpeechConfig(
+                    voice_config=types.VoiceConfig(
+                        prebuilt_voice_config=types.PrebuiltVoiceConfig(
+                            voice_name=google_voice,
+                        )
+                    )
+                ),
+            ),
+        )
+
+        # Gemini TTS returns raw PCM16 samples — wrap in WAV container
+        pcm_data = response.candidates[0].content.parts[0].inline_data.data
+        return _pcm_to_wav(pcm_data)
+
+
+class ElevenLabsAudioFactory(AudioFactory):
+    """ElevenLabs TTS provider via the ``elevenlabs`` SDK.
+
+    Requires: ``pip install elevenlabs``
+
+    Configure via ``.env``::
+
+        AI_AUDIO_PROVIDER=elevenlabs
+        ELEVENLABS_API_KEY=your-key
+
+    Voice names are mapped to ElevenLabs voice IDs.  You can pass any
+    ElevenLabs voice ID directly via :meth:`~fastapi_startkit.ai.Audio.voice`,
+    or use one of the built-in aliases:
+
+    +----------+----------------+---------+
+    | Alias    | EL Name        | Gender  |
+    +==========+================+=========+
+    | nova     | Rachel         | female  |
+    | alloy    | Bella          | female  |
+    | shimmer  | Elli           | female  |
+    | onyx     | Adam           | male    |
+    | echo     | Antoni         | male    |
+    | fable    | Arnold         | male    |
+    +----------+----------------+---------+
+
+    Default model: ``eleven_multilingual_v2``.
+    Override with :meth:`~fastapi_startkit.ai.Audio.model`.
+
+    .. note::
+        The ``speed`` parameter is accepted for API compatibility but is
+        not currently supported by ElevenLabs.
+    """
+
+    # Map OpenAI-style aliases → ElevenLabs voice IDs
+    _VOICE_MAP: dict[str, str] = {
+        "nova": "21m00Tcm4TlvDq8ikWAM",  # Rachel — female
+        "alloy": "EXAVITQu4vr4xnSDxMaL",  # Bella  — female
+        "shimmer": "MF3mGyEYCl7XYWbV9V6O",  # Elli   — female
+        "onyx": "pNInz6obpgDQGcFmaJgB",  # Adam   — male
+        "echo": "ErXwobaYiN019PkySvjV",  # Antoni — male
+        "fable": "VR6AewLTigWG4xSOukaG",  # Arnold — male
+    }
+
+    def __init__(self, api_key: str | None = None):
+        self._api_key = api_key
+
+    async def synthesize(
+        self,
+        text: str,
+        voice: str,
+        model: str,
+        speed: float,
+        fmt: str,
+    ) -> bytes:
+        from elevenlabs.client import ElevenLabs  # noqa: PLC0415
+
+        voice_id = self._VOICE_MAP.get(voice, voice)
+        client = ElevenLabs(api_key=self._api_key)
+
+        audio_chunks = await asyncio.to_thread(
+            client.text_to_speech.convert,
+            voice_id=voice_id,
+            text=text,
+            model_id=model,
+            output_format="mp3_44100_128",
+        )
+        return b"".join(audio_chunks)
+
+
+# ─── PCM → WAV helper ─────────────────────────────────────────────────────────
+
+
+def _pcm_to_wav(
+    pcm_data: bytes,
+    sample_rate: int = 24000,
+    channels: int = 1,
+    bit_depth: int = 16,
+) -> bytes:
+    """Wrap raw PCM16 samples in a minimal RIFF/WAV container.
+
+    Gemini TTS returns signed 16-bit little-endian PCM at 24 kHz mono.
+    Most audio players and APIs accept WAV, so we wrap it here.
+    """
+    data_size = len(pcm_data)
+    byte_rate = sample_rate * channels * bit_depth // 8
+    block_align = channels * bit_depth // 8
+
+    header = struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF",
+        36 + data_size,
+        b"WAVE",
+        b"fmt ",
+        16,
+        1,  # PCM
+        channels,
+        sample_rate,
+        byte_rate,
+        block_align,
+        bit_depth,
+        b"data",
+        data_size,
+    )
+    return header + pcm_data

{fastapi_startkit-0.40.0 → fastapi_startkit-0.41.0}/src/fastapi_startkit/ai/config.py

@@ -33,6 +33,14 @@ class GoogleConfig:
     key: str = field(default_factory=lambda: env("GEMINI_API_KEY", "") or env("GOOGLE_API_KEY", ""))
 
 
+@dataclass
+class ElevenLabsConfig:
+    """Configuration for the ElevenLabs provider."""
+
+    driver: str = "elevenlabs"
+    key: str = field(default_factory=lambda: env("ELEVENLABS_API_KEY", ""))
+
+
 @dataclass
 class AIConfig:
     """Top-level AI configuration — selects the default provider and holds per-provider configs."""
@@ -44,5 +52,10 @@ class AIConfig:
             "openai": OpenAIConfig(),
             "anthropic": AnthropicConfig(),
             "google": GoogleConfig(),
+            "elevenlabs": ElevenLabsConfig(),
         }
     )
+
+    # Media-generation provider selection
+    image_provider: str = field(default_factory=lambda: env("AI_IMAGE_PROVIDER", "openai"))
+    audio_provider: str = field(default_factory=lambda: env("AI_AUDIO_PROVIDER", "openai"))