reactifact 0.6.0__py3-none-any.whl

reactifact/prompts.py

@@ -0,0 +1,111 @@
+"""reactifact.prompts — minimal, strict prompt templating (§68).
+
+`PromptTemplate` renders a `{var}`-style template with *declared* variables:
+at construction time the placeholders are parsed, at render time a missing
+variable is a `KeyError` (never a silent `format` leak), and `{{`/`}}` stay
+literal braces. Domain model attributes are supported, so a template can take
+a whole artifact: `"Research {question.text} in {topic}"` and be rendered with
+`template.render(question=…, topic=…)`.
+
+`MessagesPrompt` is the same idea for a chat sequence of `(role, template)`
+rows — it renders to `list[Message]` ready for an LLM request.
+
+This is deliberately small and dependency-free: it sits between the app's
+"domain strings" and `structured_llm`/`LLMAgent.system`, without claiming to be
+a general prompting framework.
+"""
+
+from __future__ import annotations
+
+import re
+import string
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from .providers import Message, Role
+
+_FIELD = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*\Z")
+
+_formatter = string.Formatter()
+
+
+def _root_fields(template: str) -> frozenset[str]:
+    """The top-level variable names referenced by the template."""
+    roots: set[str] = set()
+    for _, field_name, _, _ in _formatter.parse(template):
+        if field_name is None or field_name == "":
+            continue
+        if _FIELD.match(field_name):
+            roots.add(field_name.split(".")[0])
+    return frozenset(roots)
+
+
+class PromptTemplate:
+    """A strict `{var}` template over the values passed to `render`."""
+
+    def __init__(
+        self,
+        template: str,
+        *,
+        defaults: Mapping[str, Any] | None = None,
+    ):
+        if not isinstance(template, str) or not template.strip():
+            raise ValueError("prompt template must be a non-empty string")
+        self._template = template
+        self._defaults = dict(defaults or {})
+        self.variables = _root_fields(template)
+
+    @property
+    def template(self) -> str:
+        return self._template
+
+    def render(self, **values: Any) -> str:
+        """Fills the placeholders; a missing declared variable is a `KeyError`."""
+        merged = {**self._defaults, **values}
+        missing = self.variables - merged.keys()
+        if missing:
+            raise KeyError(f"missing prompt variables: {', '.join(sorted(missing))}")
+        try:
+            return self._template.format(**merged)
+        except (AttributeError, IndexError, KeyError) as exc:
+            raise ValueError(
+                f"failed to render prompt (template {self._template!r}): {exc}"
+            ) from exc
+
+    def __repr__(self) -> str:
+        return f"PromptTemplate(variables={sorted(self.variables)})"
+
+
+class MessagesPrompt:
+    """A chat prompt: an ordered set of `(role, template)` rows.
+
+    Renders to `list[Message]`; every row sees the same variables and a missing
+    variable anywhere is a `KeyError`.
+    """
+
+    def __init__(self, messages: Sequence[tuple[str, str]]):
+        if not messages:
+            raise ValueError(
+                "MessagesPrompt requires at least one (role, template) row"
+            )
+        self._rows: list[tuple[Role, PromptTemplate]] = []
+        for role, template in messages:
+            if role not in ("system", "user", "assistant", "tool"):
+                raise ValueError(f"unknown message role in MessagesPrompt: {role!r}")
+            self._rows.append((cast(Role, role), PromptTemplate(template)))
+        variables: set[str] = set()
+        for _, row in self._rows:
+            variables |= set(row.variables)
+        self.variables = frozenset(variables)
+
+    def render(self, **values: Any) -> list[Message]:
+        return [
+            Message(role=role, content=template.render(**values))
+            for role, template in self._rows
+        ]
+
+    def __repr__(self) -> str:
+        return f"MessagesPrompt(roles={[r for r, _ in self._rows]})"
+
+
+__all__ = ["MessagesPrompt", "PromptTemplate"]

reactifact/providers/__init__.py

@@ -0,0 +1,153 @@
+"""Providers package: contracts + implementations (chat, embeddings, images, fakes).
+
+The app configures the needed providers when initializing resources;
+the core public API (`reactifact`) exports only contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .anthropic import AnthropicProvider, anthropic_llm
+from .azure import azure_llm
+from .cerebras import cerebras_llm
+from .chat import (
+    OpenAICompatEmbedder,
+    OpenAICompatProvider,
+    embedder_from_env,
+    llm_from_env,
+)
+from .contracts import (
+    EmbeddingProvider,
+    LLMProvider,
+    LLMRequest,
+    LLMResponse,
+    LLMResponseChunk,
+    Message,
+    Role,
+)
+from .deepseek import deepseek_llm
+from .fake import FakeEmbedder, FakeLLM
+from .fireworks import fireworks_embedder, fireworks_llm
+from .gemini import GeminiImageProvider, GeminiProvider, gemini_image, gemini_llm
+from .github_models import github_models_llm
+from .groq import groq_llm, groq_transcriber
+from .image import (
+    ImageProvider,
+    OpenAICompatImageProvider,
+    OpenRouterImageProvider,
+    image_from_env,
+)
+from .mistral import mistral_embedder, mistral_llm
+from .nvidia import nvidia_embedder, nvidia_nim_llm
+from .ollama import ollama_llm
+from .openai import openai_embedder, openai_llm
+from .openrouter import (
+    openrouter_embedder,
+    openrouter_image,
+    openrouter_llm,
+    openrouter_speech,
+)
+from .perplexity import perplexity_llm
+from .qwen import qwen_embedder, qwen_llm
+from .speech import (
+    OpenAICompatSpeech,
+    OpenAICompatTranscriber,
+    SpeechProvider,
+    TranscriberProvider,
+    speech_from_env,
+    transcriber_from_env,
+)
+from .together import together_embedder, together_llm
+from .video import (
+    LumaVideoProvider,
+    OpenRouterVideoProvider,
+    RunwayVideoProvider,
+    SoraVideoProvider,
+    VideoProvider,
+    VideoResult,
+    video_from_env,
+)
+from .xai import xai_llm
+from .zai import zai_llm
+
+
+def from_env(**overrides: Any) -> LLMProvider | None:
+    """One-call provider selection: `OPENROUTER_API_KEY` first, else a local
+    OpenAI-compatible endpoint via `OPENAI_BASE_URL`, else `None` (offline).
+
+    This is the exact two-branch selection every example in this repo hand-
+    rolls as a local `build_llm()` (deliberately, per example, so a reader
+    sees the wiring — see `examples/*/main.py`); use this instead when you
+    just want the common default in your own app without copying that block.
+    Overrides (`model`, `max_tokens`, `temperature`, ...) are forwarded to
+    whichever provider ends up selected.
+    """
+    return openrouter_llm(**overrides) or llm_from_env(**overrides)
+
+
+__all__ = [
+    "AnthropicProvider",
+    "EmbeddingProvider",
+    "FakeEmbedder",
+    "FakeLLM",
+    "GeminiImageProvider",
+    "GeminiProvider",
+    "ImageProvider",
+    "LLMProvider",
+    "LLMRequest",
+    "LLMResponse",
+    "LLMResponseChunk",
+    "LumaVideoProvider",
+    "Message",
+    "OpenAICompatEmbedder",
+    "OpenAICompatImageProvider",
+    "OpenAICompatProvider",
+    "OpenAICompatSpeech",
+    "OpenAICompatTranscriber",
+    "OpenRouterImageProvider",
+    "OpenRouterVideoProvider",
+    "Role",
+    "RunwayVideoProvider",
+    "SoraVideoProvider",
+    "SpeechProvider",
+    "TranscriberProvider",
+    "VideoProvider",
+    "VideoResult",
+    "anthropic_llm",
+    "azure_llm",
+    "cerebras_llm",
+    "deepseek_llm",
+    "embedder_from_env",
+    "fireworks_embedder",
+    "fireworks_llm",
+    "from_env",
+    "gemini_image",
+    "gemini_llm",
+    "github_models_llm",
+    "groq_llm",
+    "groq_transcriber",
+    "image_from_env",
+    "llm_from_env",
+    "mistral_embedder",
+    "mistral_llm",
+    "nvidia_embedder",
+    "nvidia_nim_llm",
+    "ollama_llm",
+    "openai_embedder",
+    "openai_llm",
+    "openrouter_embedder",
+    "openrouter_image",
+    "openrouter_llm",
+    "openrouter_speech",
+    "perplexity_llm",
+    "qwen_embedder",
+    "qwen_llm",
+    "speech_from_env",
+    "together_embedder",
+    "together_llm",
+    "transcriber_from_env",
+    "video_from_env",
+    "xai_llm",
+    "zai_llm",
+]

reactifact/providers/_retry.py

@@ -0,0 +1,61 @@
+"""Shared network-retry helper for HTTP-based LLM providers.
+
+Every `complete()` implementation in this package hits the same class of
+transient failures (429 rate limits, 5xx, connection resets/timeouts) and,
+before this module, retried none of them — a single blip failed the call
+outright. Not in `contracts.py`: the core stays free of the httpx dependency
+(see that module's docstring); this lives in the `providers` package instead
+and is imported by the concrete implementations that need it.
+
+Scoped to `complete()` only, deliberately not `stream()`: a streaming call
+can fail after already yielding chunks to the caller, and retrying by
+restarting the request would silently duplicate what was already streamed.
+`complete()` fails atomically (nothing to un-yield), so it's safe to retry
+in full.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+import httpx
+
+T = TypeVar("T")
+
+#: HTTP statuses worth retrying: rate limit + server-side errors. Anything
+#: else (400/401/403/404, ...) is a request/auth problem retrying won't fix.
+RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+async def with_retry(
+    call: Callable[[], Awaitable[T]],
+    *,
+    attempts: int = 3,
+    base_delay: float = 0.5,
+) -> T:
+    """Retries `call` on transient HTTP failures with exponential backoff.
+
+    Retries `httpx.TransportError` (connection reset, timeout, DNS...) and
+    `httpx.HTTPStatusError` whose status is in `RETRYABLE_STATUS`; any other
+    exception — including a non-retryable status — propagates on the first
+    attempt. `attempts=1` disables retrying entirely.
+    """
+    for attempt in range(attempts):
+        try:
+            return await call()
+        except httpx.HTTPStatusError as exc:
+            if (
+                exc.response.status_code not in RETRYABLE_STATUS
+                or attempt + 1 >= attempts
+            ):
+                raise
+        except httpx.TransportError:
+            if attempt + 1 >= attempts:
+                raise
+        await asyncio.sleep(base_delay * (2**attempt))
+    raise AssertionError("unreachable: loop always returns or raises")
+
+
+__all__ = ["RETRYABLE_STATUS", "with_retry"]

reactifact/providers/anthropic.py

@@ -0,0 +1,182 @@
+"""Anthropic — Messages API (not OpenAI-compatible: a separate contract)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from ._retry import with_retry
+from .contracts import (
+    LLMProvider,
+    LLMRequest,
+    LLMResponse,
+    LLMResponseChunk,
+    auth_value,
+)
+
+
+class AnthropicProvider(LLMProvider):
+    """Provider for the Anthropic Messages API (/v1/messages, x-api-key).
+
+    Auth defaults to the Anthropic convention (`x-api-key` header, raw key) but
+    is configurable like the other providers (auth_header/auth_scheme/proxy).
+    `response_format` does not exist in Anthropic — structured output is obtained
+    via plain JSON in the text (the tolerant parse_structured covers this).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "claude-3-5-sonnet-latest",
+        base_url: str = "https://api.anthropic.com/v1",
+        timeout: float = 90.0,
+        transport: Any | None = None,
+        extra_headers: dict[str, str] | None = None,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        proxy: str | None = None,
+        auth_header: str = "x-api-key",
+        auth_scheme: str | None = None,
+        retry_attempts: int = 3,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # Anthropic's Messages API requires `max_tokens`; 4096 is the library
+        # default. Pass an explicit value to change it, or override per call.
+        self.max_tokens = max_tokens if max_tokens is not None else 4096
+        self.temperature = temperature
+        self.retry_attempts = retry_attempts
+        self._headers = {
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+            **(extra_headers or {}),
+        }
+        self._headers.setdefault(auth_header.lower(), 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]:
+        system = "\n\n".join(m.content for m in request.messages if m.role == "system")
+        messages = [
+            {"role": m.role, "content": m.content}
+            for m in request.messages
+            if m.role in ("user", "assistant")
+        ]
+        if not messages:
+            messages = [{"role": "user", "content": ""}]
+        temperature = (
+            request.temperature if request.temperature is not None else self.temperature
+        )
+        payload: dict[str, Any] = {
+            "model": request.extra.get("model") or self.model,
+            "max_tokens": (
+                request.max_tokens
+                if request.max_tokens is not None
+                else self.max_tokens
+            ),
+            "messages": messages,
+            "stream": stream,
+        }
+        if temperature is not None:
+            payload["temperature"] = temperature
+        if system:
+            payload["system"] = system
+        if request.stop:
+            payload["stop_sequences"] = request.stop
+        for key, value in request.extra.items():
+            if key != "model":
+                payload[key] = value
+        return payload
+
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        async def _call() -> LLMResponse:
+            response = await self._get_client().post(
+                f"{self.base_url}/messages",
+                json=self._payload(request, stream=False),
+            )
+            response.raise_for_status()
+            data = response.json()
+            text = "".join(
+                block.get("text", "")
+                for block in data.get("content", [])
+                if block.get("type") == "text"
+            )
+            return LLMResponse(
+                text=text,
+                raw=data,
+                finish_reason=data.get("stop_reason"),
+                usage=data.get("usage", {}),
+            )
+
+        return await with_retry(_call, attempts=self.retry_attempts)
+
+    async def stream(self, request: LLMRequest) -> AsyncIterator[LLMResponseChunk]:
+        async with self._get_client().stream(
+            "POST",
+            f"{self.base_url}/messages",
+            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 or data == "[DONE]":
+                    continue
+                try:
+                    blob = json.loads(data)
+                except ValueError:
+                    continue
+                if blob.get("type") == "content_block_delta":
+                    delta = blob.get("delta", {})
+                    text = delta.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
+
+
+def anthropic_llm(
+    api_key: str | None = None,
+    model: str = "claude-3-5-sonnet-latest",
+    **kwargs: Any,
+) -> AnthropicProvider | None:
+    """Builds an Anthropic provider (key from ANTHROPIC_API_KEY).
+
+    Optional knobs in env or kwargs: ANTHROPIC_PROXY / proxy,
+    ANTHROPIC_AUTH_HEADER / auth_header (default x-api-key),
+    ANTHROPIC_AUTH_SCHEME / auth_scheme (default raw key).
+    """
+    import os
+
+    if api_key is None:
+        api_key = kwargs.get("api_key") or os.getenv("ANTHROPIC_API_KEY")
+    if not api_key:
+        return None
+    kwargs.setdefault("proxy", os.getenv("ANTHROPIC_PROXY") or None)
+    kwargs.setdefault(
+        "auth_header",
+        os.getenv("ANTHROPIC_AUTH_HEADER") or "x-api-key",
+    )
+    scheme = kwargs.get("auth_scheme") or os.getenv("ANTHROPIC_AUTH_SCHEME")
+    kwargs["auth_scheme"] = scheme if scheme else None
+    return AnthropicProvider(api_key=api_key, model=model, **kwargs)

reactifact/providers/azure.py

@@ -0,0 +1,31 @@
+"""Azure OpenAI — chat (OpenAI-compatible, deployment-as-model)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .chat import OpenAICompatProvider, _network_knobs
+
+
+def azure_llm(
+    endpoint: str,
+    api_key: str | None = None,
+    deployment: str | None = None,
+    **kwargs: Any,
+) -> OpenAICompatProvider:
+    """OpenAI-compatible Azure provider.
+
+    `endpoint` is the resource URL, e.g.
+    https://my-resource.openai.azure.com/openai/deployments/my-deployment;
+    pass `deployment` or set AZURE_OPENAI_API_KEY / AZURE_OPENAI_DEPLOYMENT.
+    """
+    import os
+
+    if api_key is None:
+        api_key = kwargs.get("api_key") or os.getenv("AZURE_OPENAI_API_KEY")
+    if deployment is None:
+        deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
+    merged = {**_network_knobs("AZURE", kwargs), **kwargs}
+    return OpenAICompatProvider(
+        base_url=endpoint, api_key=api_key, model=deployment, **merged
+    )

reactifact/providers/cerebras.py

@@ -0,0 +1,11 @@
+"""Cerebras — ultra-fast inference (OpenAI-compatible)."""
+
+from __future__ import annotations
+
+from .chat import _openai_compat_llm
+
+cerebras_llm = _openai_compat_llm(
+    env_prefix="CEREBRAS",
+    default_model="llama-3.3-70b",
+    default_base_url="https://api.cerebras.ai/v1",
+)