reactifact 0.6.0__py3-none-any.whl

reactifact/providers/gemini.py

@@ -0,0 +1,284 @@
+"""Google Gemini — native contract (generativelanguage API).
+
+Chat (`generateContent`/`streamGenerateContent`) and image generation (image
+modal parts in the same endpoint). Unlike OpenAI-compatible providers, auth is
+`x-goog-api-key: <key>` (raw key, no prefix) — but header/scheme and proxy are
+configurable like everywhere else.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from ._retry import with_retry
+from .chat import _network_knobs
+from .contracts import (
+    LLMProvider,
+    LLMRequest,
+    LLMResponse,
+    LLMResponseChunk,
+    auth_value,
+)
+from .image import ImageProvider
+
+_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta"
+
+
+def _model_path(model: str) -> str:
+    return model if model.startswith("models/") else f"models/{model}"
+
+
+def _parts_text(parts: list[dict[str, Any]]) -> str:
+    return "".join(p.get("text", "") for p in parts if p.get("text"))
+
+
+class GeminiProvider(LLMProvider):
+    """Gemini (Google AI Studio) chat provider, native contract.
+
+    `contents` carries user/model turns; the system instruction is passed
+    separately in `systemInstruction`. `response_format` uses
+    `generationConfig.response_mime_type` (e.g. application/json).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "gemini-2.0-flash",
+        base_url: str = _DEFAULT_BASE,
+        timeout: float = 120.0,
+        transport: Any | None = None,
+        proxy: str | None = None,
+        auth_header: str = "x-goog-api-key",
+        auth_scheme: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        retry_attempts: int = 3,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.retry_attempts = retry_attempts
+        self._headers = {"Content-Type": "application/json"}
+        self._headers[auth_header] = auth_value(api_key, auth_scheme)
+        self._transport = transport
+        self._proxy = proxy
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=self._timeout,
+                transport=self._transport,
+                headers=self._headers,
+                proxy=self._proxy,
+            )
+        return self._client
+
+    def _payload(self, request: LLMRequest, stream: bool) -> dict[str, Any]:
+        contents: list[dict[str, Any]] = []
+        system_parts: list[str] = []
+        for m in request.messages:
+            if m.role == "system":
+                system_parts.append(m.content)
+            else:
+                role = "model" if m.role == "assistant" else "user"
+                contents.append({"role": role, "parts": [{"text": m.content}]})
+        if not contents:
+            contents = [{"role": "user", "parts": [{"text": ""}]}]
+        payload: dict[str, Any] = {"contents": contents}
+        if system_parts:
+            payload["systemInstruction"] = {
+                "parts": [{"text": "\n".join(system_parts)}]
+            }
+        temperature = (
+            request.temperature if request.temperature is not None else self.temperature
+        )
+        max_tokens = (
+            request.max_tokens if request.max_tokens is not None else self.max_tokens
+        )
+        generation: dict[str, Any] = {}
+        if temperature is not None:
+            generation["temperature"] = temperature
+        if max_tokens is not None:
+            generation["maxOutputTokens"] = max_tokens
+        if request.stop:
+            generation["stopSequences"] = request.stop
+        if request.response_format:
+            generation["response_mime_type"] = "application/json"
+        payload["generationConfig"] = generation
+        return payload
+
+    def _parse(self, data: dict[str, Any]) -> LLMResponse:
+        candidate = (data.get("candidates") or [{}])[0]
+        parts = candidate.get("content", {}).get("parts", []) or []
+        usage = data.get("usageMetadata") or {}
+        return LLMResponse(
+            text=_parts_text(parts),
+            raw=data,
+            finish_reason=candidate.get("finishReason"),
+            usage={
+                "prompt_tokens": usage.get("promptTokenCount", 0),
+                "completion_tokens": usage.get("candidatesTokenCount", 0),
+                "total_tokens": usage.get("totalTokenCount", 0),
+            },
+        )
+
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        model = request.extra.get("model") or self.model
+
+        async def _call() -> LLMResponse:
+            response = await self._get_client().post(
+                f"{self.base_url}/{_model_path(model)}:generateContent",
+                json=self._payload(request, stream=False),
+            )
+            response.raise_for_status()
+            return self._parse(response.json())
+
+        return await with_retry(_call, attempts=self.retry_attempts)
+
+    async def stream(self, request: LLMRequest) -> AsyncIterator[LLMResponseChunk]:
+        model = request.extra.get("model") or self.model
+        async with self._get_client().stream(
+            "POST",
+            f"{self.base_url}/{_model_path(model)}:streamGenerateContent?alt=sse",
+            json=self._payload(request, stream=True),
+        ) as response:
+            response.raise_for_status()
+            async for line in response.aiter_lines():
+                if not line.startswith("data:"):
+                    continue
+                data = line[len("data:") :].strip()
+                if not data:
+                    continue
+                try:
+                    blob = _json(data)
+                except ValueError:
+                    continue
+                for part in (
+                    (blob.get("candidates") or [{}])[0]
+                    .get("content", {})
+                    .get("parts", [])
+                ):
+                    text = part.get("text")
+                    if text:
+                        yield LLMResponseChunk(text=text)
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+class GeminiImageProvider(ImageProvider):
+    """Image generation via Gemini's image-modal parts (`inlineData`)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "gemini-2.0-flash-exp",
+        base_url: str = _DEFAULT_BASE,
+        timeout: float = 120.0,
+        transport: Any | None = None,
+        proxy: str | None = None,
+        auth_header: str = "x-goog-api-key",
+        auth_scheme: str | None = None,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = {"Content-Type": "application/json"}
+        self._headers[auth_header] = auth_value(api_key, auth_scheme)
+        self._transport = transport
+        self._proxy = proxy
+        self._chat = GeminiProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            proxy=proxy,
+            auth_header=auth_header,
+            auth_scheme=auth_scheme,
+        )
+
+    async def generate(self, prompt: str, **params: Any) -> bytes | None:
+        payload: dict[str, Any] = {
+            "contents": [{"role": "user", "parts": [{"text": prompt}]}],
+            "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]},
+        }
+        if params.get("aspect_ratio"):
+            payload["generationConfig"]["imageConfig"] = {
+                "aspectRatio": params["aspect_ratio"]
+            }
+
+        async def _call() -> dict[str, Any]:
+            response = await self._chat._get_client().post(
+                f"{self.base_url}/{_model_path(self.model)}:generateContent",
+                json=payload,
+            )
+            response.raise_for_status()
+            return dict(response.json())
+
+        data = await with_retry(_call, attempts=self._chat.retry_attempts)
+        parts = (data.get("candidates") or [{}])[0].get("content", {}).get("parts", [])
+        for part in parts:
+            inline = part.get("inlineData") or {}
+            if inline.get("data"):
+                return base64.b64decode(inline["data"])
+        return None
+
+    async def aclose(self) -> None:
+        await self._chat.aclose()
+
+
+def _json(text: str) -> dict[str, Any]:
+    import json
+
+    return dict(json.loads(text))
+
+
+def gemini_llm(
+    api_key: str | None = None,
+    model: str = "gemini-2.0-flash",
+    base_url: str = _DEFAULT_BASE,
+    **kwargs: Any,
+) -> GeminiProvider | None:
+    """Builds a Gemini chat provider (key from GEMINI_API_KEY).
+
+    Knobs: GEMINI_PROXY / GEMINI_AUTH_HEADER / GEMINI_AUTH_SCHEME.
+    """
+    import os
+
+    if api_key is None:
+        api_key = kwargs.get("api_key") or os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        return None
+    merged = {**_network_knobs("GEMINI", kwargs), **kwargs}
+    return GeminiProvider(api_key=api_key, model=model, base_url=base_url, **merged)
+
+
+def gemini_image(
+    api_key: str | None = None,
+    model: str = "gemini-2.0-flash-exp",
+    base_url: str = _DEFAULT_BASE,
+    **kwargs: Any,
+) -> GeminiImageProvider | None:
+    """Builds a Gemini image generator (key from GEMINI_API_KEY)."""
+    import os
+
+    if api_key is None:
+        api_key = kwargs.get("api_key") or os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        return None
+    merged = {**_network_knobs("GEMINI", kwargs), **kwargs}
+    return GeminiImageProvider(
+        api_key=api_key, model=model, base_url=base_url, **merged
+    )

reactifact/providers/github_models.py

@@ -0,0 +1,13 @@
+"""GitHub Models — OpenAI-compatible model playground with a free tier."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_llm
+
+github_models_llm = _openai_compat_llm(
+    env_prefix="GITHUB",
+    default_model="gpt-4o-mini",
+    default_base_url="https://models.github.ai/v1",
+    env_api_key_vars=("GITHUB_TOKEN", "GITHUB_API_KEY"),
+    name="github_models_llm",
+)

reactifact/providers/groq.py

@@ -0,0 +1,18 @@
+"""Groq — fast inference (OpenAI-compatible), plus Whisper transcription."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_llm
+from .speech import _openai_compat_transcriber
+
+groq_llm = _openai_compat_llm(
+    env_prefix="GROQ",
+    default_model="llama-3.3-70b-versatile",
+    default_base_url="https://api.groq.com/openai/v1",
+)
+
+groq_transcriber = _openai_compat_transcriber(
+    env_prefix="GROQ",
+    default_model="whisper-large-v3-turbo",
+    default_base_url="https://api.groq.com/openai/v1",
+)

reactifact/providers/image.py

@@ -0,0 +1,157 @@
+"""Image generation: OpenRouter (/images), factory from env.
+
+Not part of the core public API — the app wires `ImageProvider`
+into resources if needed.
+"""
+
+from __future__ import annotations
+
+import base64
+from abc import ABC, abstractmethod
+from typing import Any
+
+import httpx
+
+from ._retry import with_retry
+from .chat import _network_knobs
+from .contracts import auth_value
+
+
+class ImageProvider(ABC):
+    """Image generation (e.g., OpenRouter /images)."""
+
+    @abstractmethod
+    async def generate(self, prompt: str, **params: Any) -> bytes | None:
+        """Returns PNG/JPEG bytes or None if generation failed."""
+        ...
+
+
+class OpenAICompatImageProvider(ImageProvider):
+    """OpenAI-compatible image generator (OpenAI images, OpenRouter, Azure, ...).
+
+    POSTs to `{base}/images` and decodes the `b64_json` of the first result.
+    Auth header/scheme and proxy are configurable like the chat providers.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://api.openai.com/v1",
+        api_key: str | None = None,
+        model: str = "gpt-image-1",
+        timeout: float = 120.0,
+        transport: Any | None = None,
+        proxy: str | None = None,
+        auth_header: str = "Authorization",
+        auth_scheme: str | None = "Bearer",
+        n: int = 1,
+        size: str | None = None,
+        quality: str | None = None,
+        retry_attempts: int = 3,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.n = n
+        self.size = size
+        self.quality = quality
+        self._timeout = timeout
+        self._transport = transport
+        self._proxy = proxy
+        self._auth_header = auth_header
+        self._auth_scheme = auth_scheme
+        self.retry_attempts = retry_attempts
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            headers = {"Content-Type": "application/json"}
+            if self.api_key:
+                headers[self._auth_header] = auth_value(self.api_key, self._auth_scheme)
+            self._client = httpx.AsyncClient(
+                timeout=self._timeout,
+                transport=self._transport,
+                headers=headers,
+                proxy=self._proxy,
+            )
+        return self._client
+
+    async def generate(self, prompt: str, **params: Any) -> bytes | None:
+        # Provider-level defaults (n/size/quality) can be overridden per call.
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "prompt": prompt,
+            "n": params.get("n", self.n),
+        }
+        if "size" in params:
+            payload["size"] = params["size"]
+        elif self.size is not None:
+            payload["size"] = self.size
+        if "quality" in params:
+            payload["quality"] = params["quality"]
+        elif self.quality is not None:
+            payload["quality"] = self.quality
+        for key in (
+            "aspect_ratio",
+            "resolution",
+            "output_format",
+            "style",
+            "background",
+            "moderation",
+        ):
+            if key in params:
+                payload[key] = params[key]
+
+        async def _generate() -> dict[str, Any]:
+            response = await self._get_client().post(
+                f"{self.base_url}/images", json=payload
+            )
+            response.raise_for_status()
+            return dict(response.json())
+
+        data = await with_retry(_generate, attempts=self.retry_attempts)
+        first = (data.get("data") or [None])[0]
+        if not first:
+            return None
+        if first.get("b64_json"):
+            return base64.b64decode(first["b64_json"])
+        url = first.get("url")
+        if url:
+
+            async def _fetch() -> bytes:
+                fetched = await self._get_client().get(url)
+                fetched.raise_for_status()
+                return fetched.content
+
+            return await with_retry(_fetch, attempts=self.retry_attempts)
+        return None
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+# Back-compat alias (the previous name, now that the provider is vendor-neutral).
+OpenRouterImageProvider = OpenAICompatImageProvider
+
+
+def image_from_env(**overrides: Any) -> OpenAICompatImageProvider | None:
+    """Builds an image generator from IMAGE_* / OPENROUTER_*. Returns
+    None if no key is set — the app skips renders. Optional knobs:
+    IMAGE_PROXY, IMAGE_AUTH_HEADER, IMAGE_AUTH_SCHEME."""
+    import os
+
+    api_key = (
+        overrides.get("api_key")
+        or os.getenv("IMAGE_API_KEY")
+        or os.getenv("OPENROUTER_API_KEY")
+    )
+    if not api_key:
+        return None
+    merged = {**_network_knobs("IMAGE", overrides), **overrides}
+    return OpenAICompatImageProvider(
+        base_url=os.getenv("IMAGE_BASE_URL") or "https://openrouter.ai/api/v1",
+        api_key=api_key,
+        model=os.getenv("IMAGE_MODEL", "google/gemini-3-pro-create-image-plus"),
+        **merged,
+    )

reactifact/providers/mistral.py

@@ -0,0 +1,17 @@
+"""Mistral AI — cloud chat and embeddings (OpenAI-compatible)."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_embedder, _openai_compat_llm
+
+mistral_llm = _openai_compat_llm(
+    env_prefix="MISTRAL",
+    default_model="mistral-large-latest",
+    default_base_url="https://api.mistral.ai/v1",
+)
+
+mistral_embedder = _openai_compat_embedder(
+    env_prefix="MISTRAL",
+    default_model="mistral-embed",
+    default_base_url="https://api.mistral.ai/v1",
+)

reactifact/providers/nvidia.py

@@ -0,0 +1,18 @@
+"""NVIDIA NIM — hosted open models (OpenAI-compatible), plus embeddings."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_embedder, _openai_compat_llm
+
+nvidia_nim_llm = _openai_compat_llm(
+    env_prefix="NVIDIA",
+    default_model="meta/llama-3.3-70b-instruct",
+    default_base_url="https://integrate.api.nvidia.com/v1",
+    name="nvidia_nim_llm",
+)
+
+nvidia_embedder = _openai_compat_embedder(
+    env_prefix="NVIDIA",
+    default_model="nvidia/llama-3.2-nv-embedqa-1b-v2",
+    default_base_url="https://integrate.api.nvidia.com/v1",
+)

reactifact/providers/ollama.py

@@ -0,0 +1,18 @@
+"""Ollama (local, OpenAI-compatible /v1)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .chat import OpenAICompatProvider
+
+
+def ollama_llm(
+    model: str = "qwen2.5:7b",
+    base_url: str = "http://localhost:11434/v1",
+    timeout: float = 120.0,
+    **kwargs: Any,
+) -> OpenAICompatProvider:
+    return OpenAICompatProvider(
+        base_url=base_url, model=model, timeout=timeout, **kwargs
+    )

reactifact/providers/openai.py

@@ -0,0 +1,44 @@
+"""OpenAI — cloud chat and embeddings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .chat import OpenAICompatEmbedder, OpenAICompatProvider, _network_knobs
+
+
+def openai_llm(
+    model: str | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> OpenAICompatProvider | None:
+    if api_key is None:
+        import os
+
+        api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        return None  # without a key the app runs on its deterministic fallbacks
+    merged = {**_network_knobs("OPENAI", kwargs), **kwargs}
+    return OpenAICompatProvider(
+        base_url=base_url or "https://api.openai.com/v1",
+        api_key=api_key,
+        model=model or "gpt-4o-mini",
+        **merged,
+    )
+
+
+def openai_embedder(
+    model: str = "text-embedding-3-small",
+    base_url: str = "https://api.openai.com/v1",
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> OpenAICompatEmbedder:
+    if api_key is None:
+        import os
+
+        api_key = os.getenv("OPENAI_API_KEY")
+    merged = {**_network_knobs("OPENAI", kwargs), **kwargs}
+    return OpenAICompatEmbedder(
+        base_url=base_url, api_key=api_key, model=model, **merged
+    )

reactifact/providers/openrouter.py

@@ -0,0 +1,70 @@
+"""OpenRouter — model router: chat (fast mode by default), images,
+embeddings, and text-to-speech. Video lives in `reactifact.providers.video`
+(`OpenRouterVideoProvider`, alongside the other video vendors). Speech-to-
+text is *not* offered here: OpenRouter's `/audio/transcriptions` takes a
+base64-JSON body, not the multipart file upload every other transcriber in
+this package expects — a real API difference, not an oversight."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .chat import OpenAICompatProvider, _network_knobs, _openai_compat_embedder
+from .image import OpenAICompatImageProvider
+from .speech import _openai_compat_speech
+
+
+def openrouter_llm(
+    model: str = "deepseek/deepseek-v4-flash",
+    base_url: str = "https://openrouter.ai/api/v1",
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> OpenAICompatProvider | None:
+    import os
+
+    if api_key is None:
+        api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        return None  # without a key OpenRouter does not work — the app falls back
+    model = os.getenv("OPENROUTER_MODEL") or model
+    extra_body: dict[str, Any] = dict(kwargs.pop("extra_body", None) or {})
+    # hybrid models: disable reasoning by default (fast mode)
+    extra_body.setdefault("reasoning", {"enabled": False})
+    merged = {**_network_knobs("OPENROUTER", kwargs), **kwargs}
+    return OpenAICompatProvider(
+        base_url=base_url,
+        api_key=api_key,
+        model=model,
+        extra_body=extra_body,
+        **merged,
+    )
+
+
+def openrouter_image(
+    model: str = "google/gemini-3-pro-create-image-plus",
+    base_url: str = "https://openrouter.ai/api/v1",
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> OpenAICompatImageProvider:
+    if api_key is None:
+        import os
+
+        api_key = os.getenv("OPENROUTER_API_KEY")
+    merged = {**_network_knobs("OPENROUTER", kwargs), **kwargs}
+    return OpenAICompatImageProvider(
+        base_url=base_url, api_key=api_key, model=model, **merged
+    )
+
+
+openrouter_embedder = _openai_compat_embedder(
+    env_prefix="OPENROUTER",
+    default_model="openai/text-embedding-3-small",
+    default_base_url="https://openrouter.ai/api/v1",
+)
+
+openrouter_speech = _openai_compat_speech(
+    env_prefix="OPENROUTER",
+    default_model="openai/gpt-4o-mini-tts",
+    default_voice="alloy",
+    default_base_url="https://openrouter.ai/api/v1",
+)

reactifact/providers/perplexity.py

@@ -0,0 +1,11 @@
+"""Perplexity — Sonar answer API (OpenAI-compatible, built-in web search)."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_llm
+
+perplexity_llm = _openai_compat_llm(
+    env_prefix="PERPLEXITY",
+    default_model="sonar-pro",
+    default_base_url="https://api.perplexity.ai",
+)

reactifact/providers/qwen.py

@@ -0,0 +1,17 @@
+"""Qwen (Alibaba DashScope) — chat (OpenAI-compatible), plus embeddings."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_embedder, _openai_compat_llm
+
+qwen_llm = _openai_compat_llm(
+    env_prefix="QWEN",
+    default_model="qwen-plus",
+    default_base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+)
+
+qwen_embedder = _openai_compat_embedder(
+    env_prefix="QWEN",
+    default_model="text-embedding-v2",
+    default_base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+)