llmwire 0.1.0__py3-none-any.whl

llmwire/__init__.py

@@ -0,0 +1,22 @@
+"""LLMWire — Lightweight multi-provider LLM client."""
+
+from llmwire.client import LLMClient
+from llmwire.config import LLMConfig, ProviderConfig
+from llmwire.exceptions import AllProvidersFailedError, LLMWireError, ProviderError
+from llmwire.models import ChatResponse, Message, StreamChunk, Usage
+from llmwire.provider import Provider
+
+__all__ = [
+    "AllProvidersFailedError",
+    "ChatResponse",
+    "LLMClient",
+    "LLMConfig",
+    "LLMWireError",
+    "Message",
+    "Provider",
+    "ProviderConfig",
+    "ProviderError",
+    "StreamChunk",
+    "Usage",
+]
+__version__ = "0.1.0"

llmwire/client.py

@@ -0,0 +1,270 @@
+"""LLMClient — the main orchestrator for multi-provider LLM access."""
+from __future__ import annotations
+
+import inspect
+import json
+from typing import TYPE_CHECKING, Any, TypeVar, cast, overload
+
+from llmwire.exceptions import AllProvidersFailedError, ProviderError
+from llmwire.models import ChatResponse, Message, StreamChunk
+from llmwire.providers import AnthropicProvider, OllamaProvider, OpenAIProvider
+from llmwire.retry import retry_with_backoff
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from pydantic import BaseModel
+
+    from llmwire.config import LLMConfig, ProviderConfig
+
+T = TypeVar("T", bound="BaseModel")
+
+
+_schema_cache: dict[type[Any], str] = {}
+
+
+def _cached_schema_json(model_cls: type[Any]) -> str:
+    """Return the JSON schema string for a Pydantic model, cached per class."""
+    if model_cls not in _schema_cache:
+        _schema_cache[model_cls] = json.dumps(model_cls.model_json_schema(), indent=2)
+    return _schema_cache[model_cls]
+
+_PROVIDER_MAP: dict[str, type[Any]] = {
+    "openai": OpenAIProvider,
+    "anthropic": AnthropicProvider,
+    "ollama": OllamaProvider,
+}
+
+
+def _create_provider(
+    config: ProviderConfig, timeout: float
+) -> OpenAIProvider | AnthropicProvider | OllamaProvider:
+    """Instantiate a provider from its configuration.
+
+    Args:
+        config: Provider configuration including name, api_key, model, base_url.
+        timeout: Request timeout in seconds forwarded to the provider.
+
+    Returns:
+        A concrete provider instance.
+
+    Raises:
+        ValueError: If the provider name is not recognised.
+    """
+    provider_cls = _PROVIDER_MAP.get(config.name)
+    if provider_cls is None:
+        known = ", ".join(_PROVIDER_MAP)
+        raise ValueError(
+            f"Unknown provider '{config.name}'. Known providers: {known}"
+        )
+
+    kwargs: dict[str, Any] = {"model": config.model, "timeout": timeout}
+
+    sig = inspect.signature(provider_cls.__init__)
+    if "api_key" in sig.parameters and config.api_key is not None:
+        kwargs["api_key"] = config.api_key
+
+    if config.base_url is not None:
+        kwargs["base_url"] = config.base_url
+
+    instance = provider_cls(**kwargs)
+    return cast("OpenAIProvider | AnthropicProvider | OllamaProvider", instance)
+
+
+class LLMClient:
+    """Orchestrates multi-provider LLM access with fallback and retry logic.
+
+    Args:
+        config: Full LLMWire configuration including provider list, fallback
+            behaviour, retry count, and timeout.
+
+    Raises:
+        ValueError: If ``config.providers`` is empty.
+
+    Example::
+
+        config = LLMConfig(providers=[ProviderConfig(name="openai", api_key="...", model="gpt-4o")])
+        client = LLMClient(config)
+        response = await client.chat("Hello!")
+        print(response.content)
+    """
+
+    def __init__(self, config: LLMConfig) -> None:
+        if not config.providers:
+            raise ValueError("At least one provider must be configured")
+        self._config = config
+        self._providers = [_create_provider(p, config.timeout) for p in config.providers]
+
+    async def close(self) -> None:
+        """Close all underlying provider HTTP clients."""
+        for provider in self._providers:
+            await provider.close()
+
+    async def __aenter__(self) -> LLMClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    def _normalize_messages(self, prompt: str | list[Message]) -> list[Message]:
+        """Convert a bare string prompt into a single-item user message list.
+
+        Args:
+            prompt: Either a plain string or an already-formed list of Messages.
+
+        Returns:
+            A list of Message objects ready to send to a provider.
+        """
+        if isinstance(prompt, str):
+            return [Message(role="user", content=prompt)]
+        return list(prompt)
+
+    def _build_schema_system_message(self, model_cls: type[Any]) -> Message:
+        """Build a system message instructing the LLM to respond with valid JSON.
+
+        Args:
+            model_cls: A Pydantic ``BaseModel`` subclass whose schema to embed.
+
+        Returns:
+            A system ``Message`` containing the JSON schema.
+        """
+        schema = _cached_schema_json(model_cls)
+        content = (
+            "You must respond with valid JSON that matches the following JSON schema. "
+            "Do not include any explanation or markdown — only the raw JSON object.\n\n"
+            f"Schema:\n{schema}"
+        )
+        return Message(role="system", content=content)
+
+    @overload
+    async def chat(
+        self,
+        prompt: str | list[Message],
+        *,
+        temperature: float = ...,
+        max_tokens: int | None = ...,
+        response_model: None = ...,
+    ) -> ChatResponse: ...
+
+    @overload
+    async def chat(
+        self,
+        prompt: str | list[Message],
+        *,
+        temperature: float = ...,
+        max_tokens: int | None = ...,
+        response_model: type[T],
+    ) -> T: ...
+
+    async def chat(
+        self,
+        prompt: str | list[Message],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        response_model: type[T] | None = None,
+    ) -> ChatResponse | T:
+        """Send a chat completion request, with optional fallback across providers.
+
+        Args:
+            prompt: A string or list of ``Message`` objects. A bare string is
+                wrapped in a single ``user`` message.
+            temperature: Sampling temperature forwarded to the provider.
+            max_tokens: Maximum tokens to generate; ``None`` uses provider default.
+            response_model: Optional Pydantic model class. When supplied, a system
+                message with the JSON schema is prepended and the response content
+                is parsed into an instance of this model.
+
+        Returns:
+            A ``ChatResponse`` when ``response_model`` is ``None``, otherwise an
+            instance of ``response_model``.
+
+        Raises:
+            AllProvidersFailedError: When all attempted providers raise
+                ``ProviderError``.
+        """
+        messages = self._normalize_messages(prompt)
+
+        if response_model is not None:
+            schema_msg = self._build_schema_system_message(response_model)
+            messages = [schema_msg, *messages]
+
+        providers_to_try = self._providers if self._config.fallback else self._providers[:1]
+
+        errors: list[ProviderError] = []
+        for provider in providers_to_try:
+
+            async def _call(
+                _provider: OpenAIProvider | AnthropicProvider | OllamaProvider = provider,
+            ) -> ChatResponse:
+                return await _provider.chat(
+                    messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                )
+
+            try:
+                response = await retry_with_backoff(
+                    _call,
+                    max_retries=self._config.max_retries,
+                    retryable_exceptions=(ProviderError,),
+                )
+            except ProviderError as exc:
+                errors.append(exc)
+                continue
+
+            if response_model is not None:
+                return response_model.model_validate_json(response.content)
+            return response
+
+        raise AllProvidersFailedError(errors)
+
+    async def stream(
+        self,
+        prompt: str | list[Message],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a chat completion response, with optional fallback across providers.
+
+        Yields chunks from the first provider that responds successfully.
+        If a provider fails before streaming starts, the next provider is tried
+        (when ``fallback=True``).
+
+        Args:
+            prompt: A string or list of ``Message`` objects.
+            temperature: Sampling temperature forwarded to the provider.
+            max_tokens: Maximum tokens to generate; ``None`` uses provider default.
+
+        Yields:
+            ``StreamChunk`` objects as tokens arrive.
+
+        Raises:
+            AllProvidersFailedError: When all attempted providers raise
+                ``ProviderError``.
+        """
+        messages = self._normalize_messages(prompt)
+        providers_to_try = self._providers if self._config.fallback else self._providers[:1]
+
+        errors: list[ProviderError] = []
+        for provider in providers_to_try:
+            has_yielded = False
+            try:
+                async for chunk in provider.stream(
+                    messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                ):
+                    has_yielded = True
+                    yield chunk
+            except ProviderError as exc:
+                if has_yielded:
+                    # Already started yielding — cannot fall back; re-raise.
+                    raise
+                errors.append(exc)
+                continue
+            else:
+                return
+
+        raise AllProvidersFailedError(errors)

llmwire/config.py

@@ -0,0 +1,41 @@
+"""LLMWire configuration."""
+from __future__ import annotations
+
+from pydantic import BaseModel, field_validator
+from pydantic_settings import BaseSettings
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a single LLM provider."""
+
+    name: str
+    api_key: str | None = None
+    model: str = ""
+    base_url: str | None = None
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def normalize_name(cls, v: object) -> object:
+        """Normalize provider name to lowercase."""
+        if isinstance(v, str):
+            return v.strip().lower()
+        return v
+
+
+class LLMConfig(BaseSettings):
+    """Main LLMWire configuration."""
+
+    model_config = {"env_prefix": "LLMKIT_", "env_nested_delimiter": "__"}
+
+    providers: list[ProviderConfig] = []
+    fallback: bool = True
+    max_retries: int = 3
+    timeout: float = 30.0
+
+    @field_validator("providers", mode="before")
+    @classmethod
+    def coerce_providers(cls, v: object) -> object:
+        """Convert indexed-dict form (from env vars) to a list."""
+        if isinstance(v, dict):
+            return [v[k] for k in sorted(v.keys(), key=lambda x: int(x))]
+        return v

llmwire/exceptions.py

@@ -0,0 +1,23 @@
+"""LLMWire exceptions."""
+from __future__ import annotations
+
+
+class LLMWireError(Exception):
+    """Base exception for LLMWire."""
+
+
+class ProviderError(LLMWireError):
+    """Raised when a single provider fails."""
+
+    def __init__(self, provider: str, message: str) -> None:
+        self.provider = provider
+        super().__init__(f"[{provider}] {message}")
+
+
+class AllProvidersFailedError(LLMWireError):
+    """Raised when all providers fail during fallback."""
+
+    def __init__(self, errors: list[ProviderError]) -> None:
+        self.errors = errors
+        providers = ", ".join(e.provider for e in errors)
+        super().__init__(f"All providers failed: {providers}")

llmwire/models.py

@@ -0,0 +1,42 @@
+"""Data models for LLMWire."""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+Role = Literal["system", "user", "assistant"]
+
+
+class Message(BaseModel):
+    """A chat message."""
+
+    role: Role
+    content: str
+
+
+class Usage(BaseModel):
+    """Token usage statistics."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class _LLMResponseBase(BaseModel):
+    """Shared fields for all LLM response types."""
+
+    content: str
+    provider: str
+    model: str
+    usage: Usage | None = None
+
+
+class ChatResponse(_LLMResponseBase):
+    """Response from an LLM chat completion."""
+
+
+class StreamChunk(_LLMResponseBase):
+    """A single chunk from a streaming response."""
+
+    done: bool = False

llmwire/provider.py

@@ -0,0 +1,36 @@
+"""Provider protocol — the interface all LLM providers implement."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from llmwire.models import ChatResponse, Message, StreamChunk
+
+
+class Provider(Protocol):
+    """Interface for LLM provider adapters."""
+
+    @property
+    def name(self) -> str: ...
+
+    async def close(self) -> None: ...
+
+    async def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> ChatResponse: ...
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamChunk]: ...

llmwire/providers/__init__.py

@@ -0,0 +1,6 @@
+"""LLM provider implementations."""
+from llmwire.providers.anthropic import AnthropicProvider
+from llmwire.providers.ollama import OllamaProvider
+from llmwire.providers.openai import OpenAIProvider
+
+__all__ = ["AnthropicProvider", "OllamaProvider", "OpenAIProvider"]

llmwire/providers/anthropic.py

@@ -0,0 +1,228 @@
+"""Anthropic provider implementation."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from llmwire.exceptions import ProviderError
+from llmwire.models import ChatResponse, Message, StreamChunk, Usage
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+_ANTHROPIC_VERSION = "2023-06-01"
+
+
+class AnthropicProvider:
+    """LLM provider for Anthropic's Messages API.
+
+    Uses httpx directly. Handles system message extraction into the
+    top-level ``system`` field as required by the Anthropic API.
+    Supports both chat completions and streaming via Server-Sent Events.
+
+    Args:
+        api_key: Anthropic API key.
+        model: Model identifier (e.g. "claude-3-5-sonnet-20241022").
+        base_url: API base URL. Defaults to the official Anthropic endpoint.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        base_url: str = "https://api.anthropic.com/v1",
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._model = model
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+
+    @property
+    def name(self) -> str:
+        """Provider identifier."""
+        return "anthropic"
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-api-key": self._api_key,
+            "anthropic-version": _ANTHROPIC_VERSION,
+        }
+
+    def _build_payload(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None,
+        temperature: float,
+        max_tokens: int | None,
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        """Build the request payload, extracting system messages."""
+        system_parts: list[str] = []
+        user_messages: list[dict[str, str]] = []
+
+        for msg in messages:
+            if msg.role == "system":
+                system_parts.append(msg.content)
+            else:
+                user_messages.append({"role": msg.role, "content": msg.content})
+
+        payload: dict[str, Any] = {
+            "model": model or self._model,
+            "messages": user_messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens if max_tokens is not None else 4096,
+            "stream": stream,
+        }
+        if system_parts:
+            payload["system"] = "\n".join(system_parts)
+
+        return payload
+
+    async def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> ChatResponse:
+        """Send a chat completion request.
+
+        Args:
+            messages: Conversation history. System messages are extracted
+                and placed in the top-level ``system`` field.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate. Defaults to 4096.
+
+        Returns:
+            ChatResponse with content, provider, model, and usage.
+
+        Raises:
+            ProviderError: On any non-200 HTTP response.
+        """
+        url = f"{self._base_url}/messages"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+
+        try:
+            response = await self._client.post(url, headers=self._headers(), json=payload)
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc
+
+        if response.status_code != 200:
+            raise ProviderError(self.name, f"HTTP {response.status_code}: {response.text}")
+
+        data = response.json()
+        content: str = data["content"][0]["text"]
+        resolved_model: str = data.get("model", model or self._model)
+
+        usage: Usage | None = None
+        if raw_usage := data.get("usage"):
+            prompt_tokens: int = raw_usage.get("input_tokens", 0)
+            completion_tokens: int = raw_usage.get("output_tokens", 0)
+            usage = Usage(
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                total_tokens=prompt_tokens + completion_tokens,
+            )
+
+        return ChatResponse(
+            content=content,
+            provider=self.name,
+            model=resolved_model,
+            usage=usage,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a chat completion response via SSE.
+
+        Anthropic uses typed events. Only ``content_block_delta`` events
+        with ``text_delta`` deltas produce text. ``message_stop`` signals
+        the end of the stream.
+
+        Args:
+            messages: Conversation history.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate. Defaults to 4096.
+
+        Yields:
+            StreamChunk for each text delta received.
+
+        Raises:
+            ProviderError: On any non-200 HTTP response.
+        """
+        url = f"{self._base_url}/messages"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+        resolved_model = model or self._model
+
+        try:
+            async with self._client.stream(
+                "POST", url, headers=self._headers(), json=payload
+            ) as response:
+                if response.status_code != 200:
+                    body = await response.aread()
+                    raise ProviderError(
+                        self.name, f"HTTP {response.status_code}: {body.decode()}"
+                    )
+
+                async for line in response.aiter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    raw = line[len("data: "):]
+                    try:
+                        event = json.loads(raw)
+                    except json.JSONDecodeError:
+                        continue
+
+                    event_type: str = event.get("type", "")
+
+                    if event_type == "message_stop":
+                        yield StreamChunk(
+                            content="",
+                            provider=self.name,
+                            model=resolved_model,
+                            done=True,
+                        )
+                        return
+
+                    if event_type == "content_block_delta":
+                        delta = event.get("delta", {})
+                        if delta.get("type") == "text_delta":
+                            text: str = delta.get("text", "")
+                            if text:
+                                yield StreamChunk(
+                                    content=text,
+                                    provider=self.name,
+                                    model=resolved_model,
+                                )
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc

llmwire/providers/ollama.py

@@ -0,0 +1,202 @@
+"""Ollama provider implementation for local LLM inference."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from llmwire.exceptions import ProviderError
+from llmwire.models import ChatResponse, Message, StreamChunk, Usage
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+_DEFAULT_BASE_URL = "http://localhost:11434"
+_DEFAULT_TIMEOUT = 120.0  # local models are slower
+
+
+class OllamaProvider:
+    """LLM provider for Ollama local inference server.
+
+    Connects to a locally running Ollama instance. No API key is needed.
+    Uses NDJSON for streaming (one JSON object per line).
+
+    Args:
+        model: Model identifier (e.g. "llama3.2").
+        base_url: Ollama server URL. Defaults to ``http://localhost:11434``.
+        timeout: Request timeout in seconds. Defaults to 120.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._model = model
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+
+    @property
+    def name(self) -> str:
+        """Provider identifier."""
+        return "ollama"
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    @property
+    def base_url(self) -> str:
+        """Ollama server base URL."""
+        return self._base_url
+
+    def _headers(self) -> dict[str, str]:
+        return {}
+
+    def _build_payload(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None,
+        temperature: float,
+        max_tokens: int | None,
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        options: dict[str, Any] = {"temperature": temperature}
+        if max_tokens is not None:
+            options["num_predict"] = max_tokens
+
+        return {
+            "model": model or self._model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream": stream,
+            "options": options,
+        }
+
+    async def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> ChatResponse:
+        """Send a chat completion request to the Ollama server.
+
+        Args:
+            messages: Conversation history.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate (``num_predict``).
+
+        Returns:
+            ChatResponse with content, provider, model, and usage.
+
+        Raises:
+            ProviderError: On connection errors or non-200 HTTP responses.
+        """
+        url = f"{self._base_url}/api/chat"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+
+        try:
+            response = await self._client.post(url, headers=self._headers(), json=payload)
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc
+
+        if response.status_code != 200:
+            raise ProviderError(self.name, f"HTTP {response.status_code}: {response.text}")
+
+        data = response.json()
+        content: str = data["message"]["content"]
+        resolved_model: str = data.get("model", model or self._model)
+
+        prompt_tokens: int = data.get("prompt_eval_count", 0)
+        completion_tokens: int = data.get("eval_count", 0)
+        usage = Usage(
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=prompt_tokens + completion_tokens,
+        )
+
+        return ChatResponse(
+            content=content,
+            provider=self.name,
+            model=resolved_model,
+            usage=usage,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a chat completion response via NDJSON.
+
+        Ollama streams one JSON object per line. The ``done`` field signals
+        the end of the stream.
+
+        Args:
+            messages: Conversation history.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate (``num_predict``).
+
+        Yields:
+            StreamChunk for each non-empty content token.
+
+        Raises:
+            ProviderError: On connection errors or non-200 HTTP responses.
+        """
+        url = f"{self._base_url}/api/chat"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+        resolved_model = model or self._model
+
+        try:
+            async with self._client.stream(
+                "POST", url, headers=self._headers(), json=payload
+            ) as response:
+                if response.status_code != 200:
+                    body = await response.aread()
+                    raise ProviderError(self.name, f"HTTP {response.status_code}: {body.decode()}")
+
+                async for line in response.aiter_lines():
+                    if not line.strip():
+                        continue
+                    try:
+                        event = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    chunk_content: str = event.get("message", {}).get("content", "")
+                    event_model: str = event.get("model", resolved_model)
+                    is_done: bool = event.get("done", False)
+
+                    if chunk_content:
+                        yield StreamChunk(
+                            content=chunk_content,
+                            provider=self.name,
+                            model=event_model,
+                            done=is_done,
+                        )
+
+                    if is_done:
+                        break
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc

llmwire/providers/openai.py

@@ -0,0 +1,200 @@
+"""OpenAI provider implementation."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from llmwire.exceptions import ProviderError
+from llmwire.models import ChatResponse, Message, StreamChunk, Usage
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+class OpenAIProvider:
+    """LLM provider for OpenAI-compatible APIs.
+
+    Uses httpx directly (no SDK dependency). Supports both chat completions
+    and streaming via Server-Sent Events.
+
+    Args:
+        api_key: OpenAI API key.
+        model: Model identifier (e.g. "gpt-4o").
+        base_url: API base URL. Defaults to the official OpenAI endpoint.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        base_url: str = "https://api.openai.com/v1",
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._model = model
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+
+    @property
+    def name(self) -> str:
+        """Provider identifier."""
+        return "openai"
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+        }
+
+    def _build_payload(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None,
+        temperature: float,
+        max_tokens: int | None,
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "model": model or self._model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "temperature": temperature,
+            "stream": stream,
+        }
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        return payload
+
+    async def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> ChatResponse:
+        """Send a chat completion request.
+
+        Args:
+            messages: Conversation history.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate.
+
+        Returns:
+            ChatResponse with content, provider, model, and usage.
+
+        Raises:
+            ProviderError: On any non-200 HTTP response.
+        """
+        url = f"{self._base_url}/chat/completions"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+
+        try:
+            response = await self._client.post(url, headers=self._headers(), json=payload)
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc
+
+        if response.status_code != 200:
+            raise ProviderError(self.name, f"HTTP {response.status_code}: {response.text}")
+
+        data = response.json()
+        content: str = data["choices"][0]["message"]["content"]
+        resolved_model: str = data.get("model", model or self._model)
+
+        usage: Usage | None = None
+        if raw_usage := data.get("usage"):
+            usage = Usage(
+                prompt_tokens=raw_usage.get("prompt_tokens", 0),
+                completion_tokens=raw_usage.get("completion_tokens", 0),
+                total_tokens=raw_usage.get("total_tokens", 0),
+            )
+
+        return ChatResponse(
+            content=content,
+            provider=self.name,
+            model=resolved_model,
+            usage=usage,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a chat completion response via SSE.
+
+        Args:
+            messages: Conversation history.
+            model: Override the default model.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate.
+
+        Yields:
+            StreamChunk for each token delta received.
+
+        Raises:
+            ProviderError: On any non-200 HTTP response.
+        """
+        url = f"{self._base_url}/chat/completions"
+        payload = self._build_payload(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+
+        try:
+            async with self._client.stream(
+                "POST", url, headers=self._headers(), json=payload
+            ) as response:
+                if response.status_code != 200:
+                    body = await response.aread()
+                    raise ProviderError(
+                        self.name, f"HTTP {response.status_code}: {body.decode()}"
+                    )
+
+                async for line in response.aiter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    raw = line[len("data: "):]
+                    if raw == "[DONE]":
+                        yield StreamChunk(
+                            content="",
+                            provider=self.name,
+                            model=model or self._model,
+                            done=True,
+                        )
+                        return
+                    try:
+                        event = json.loads(raw)
+                    except json.JSONDecodeError:
+                        continue
+
+                    delta_content: str = event["choices"][0]["delta"].get("content", "")
+                    event_model: str = event.get("model", model or self._model)
+
+                    if delta_content:
+                        yield StreamChunk(
+                            content=delta_content,
+                            provider=self.name,
+                            model=event_model,
+                        )
+        except httpx.TransportError as exc:
+            raise ProviderError(self.name, f"Connection failed: {exc}") from exc

llmwire/retry.py

@@ -0,0 +1,46 @@
+"""Retry logic with exponential backoff."""
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+
+async def retry_with_backoff[T](
+    fn: Callable[[], Awaitable[T]],
+    *,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    retryable_exceptions: tuple[type[Exception], ...] = (ConnectionError, TimeoutError, OSError),
+) -> T:
+    """Execute an async function with exponential backoff retry.
+
+    Args:
+        fn: The async callable to execute.
+        max_retries: Maximum number of attempts before raising.
+        base_delay: Base delay in seconds for the first backoff interval.
+        retryable_exceptions: Exception types that trigger a retry.
+
+    Returns:
+        The return value of ``fn`` on success.
+
+    Raises:
+        Exception: The last retryable exception after all attempts are exhausted,
+            or any non-retryable exception immediately.
+    """
+    last_exception: Exception | None = None
+    for attempt in range(max_retries):
+        try:
+            return await fn()
+        except retryable_exceptions as exc:
+            last_exception = exc
+            if attempt < max_retries - 1:
+                delay = base_delay * (2**attempt) + random.uniform(0, base_delay * 0.1)
+                await asyncio.sleep(delay)
+        except Exception:
+            raise
+    assert last_exception is not None
+    raise last_exception

llmwire-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: llmwire
+Version: 0.1.0
+Summary: Lightweight multi-provider LLM client for Python
+Project-URL: Homepage, https://github.com/alexmar07/llmwire
+Project-URL: Documentation, https://alexmar07.github.io/llmwire
+Project-URL: Repository, https://github.com/alexmar07/llmwire
+Author-email: Alessandro Marotta <alessand.marotta@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,async,llm,ollama,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# LLMWire
+
+[![CI](https://github.com/alexmar07/llmwire/actions/workflows/ci.yml/badge.svg)](https://github.com/alexmar07/llmwire/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/llmwire)](https://pypi.org/project/llmwire/)
+[![Python](https://img.shields.io/pypi/pyversions/llmwire)](https://pypi.org/project/llmwire/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Lightweight multi-provider LLM client for Python. A single async interface to
+OpenAI, Anthropic, and Ollama — with automatic fallback, exponential-backoff retry,
+streaming, and structured Pydantic output. No provider SDK dependencies; all requests
+go over plain `httpx`.
+
+## Features
+
+- **Unified API** — one `LLMClient` for all supported providers
+- **Async-first** — built entirely on `asyncio` and `httpx`
+- **Automatic fallback** — on provider failure, tries the next provider in the list
+- **Exponential backoff** — configurable retry with full jitter
+- **Streaming** — token-by-token via `client.stream()`, async generator interface
+- **Structured output** — pass any Pydantic `BaseModel` as `response_model`
+- **No provider SDKs** — runtime deps are only `httpx`, `pydantic`, `pydantic-settings`, `pyyaml`
+- **Environment variable config** — all settings readable from `LLMKIT_*` env vars
+
+## Quick Start
+
+```bash
+pip install llmwire
+```
+
+### Chat
+
+```python
+import asyncio
+from llmwire import LLMClient, LLMConfig, ProviderConfig
+
+config = LLMConfig(
+    providers=[
+        ProviderConfig(name="openai", api_key="sk-...", model="gpt-4o"),
+        ProviderConfig(name="anthropic", api_key="sk-ant-...", model="claude-3-5-sonnet-20241022"),
+    ]
+)
+
+async def main():
+    async with LLMClient(config) as client:
+        response = await client.chat("What is the capital of France?")
+        print(response.content)
+        # Provider: openai | Model: gpt-4o | Tokens: 42
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+async def main():
+    async with LLMClient(config) as client:
+        async for chunk in client.stream("Write a haiku about async programming."):
+            print(chunk.content, end="", flush=True)
+        print()
+```
+
+### Structured Output
+
+```python
+from pydantic import BaseModel
+
+class Sentiment(BaseModel):
+    label: str        # "positive", "negative", or "neutral"
+    confidence: float
+
+async def main():
+    async with LLMClient(config) as client:
+        result: Sentiment = await client.chat(
+            "Classify: 'I love this library!'",
+            response_model=Sentiment,
+        )
+        print(result.label, result.confidence)  # positive  0.97
+```
+
+## Configuration
+
+### Direct
+
+```python
+from llmwire import LLMConfig, ProviderConfig
+
+config = LLMConfig(
+    providers=[
+        ProviderConfig(name="openai", api_key="sk-...", model="gpt-4o"),
+        ProviderConfig(name="ollama", model="llama3.2"),          # no key needed
+    ],
+    fallback=True,    # try next provider on failure (default: True)
+    max_retries=3,    # per-provider retry attempts (default: 3)
+    timeout=30.0,     # request timeout in seconds (default: 30.0)
+)
+```
+
+### Environment Variables
+
+```bash
+export LLMKIT_PROVIDERS__0__NAME=openai
+export LLMKIT_PROVIDERS__0__API_KEY=sk-...
+export LLMKIT_PROVIDERS__0__MODEL=gpt-4o
+
+export LLMKIT_PROVIDERS__1__NAME=anthropic
+export LLMKIT_PROVIDERS__1__API_KEY=sk-ant-...
+export LLMKIT_PROVIDERS__1__MODEL=claude-3-5-sonnet-20241022
+
+export LLMKIT_FALLBACK=true
+export LLMKIT_MAX_RETRIES=3
+```
+
+```python
+config = LLMConfig()  # reads from environment
+```
+
+## Provider Support
+
+| Provider | Chat | Streaming | Auth | Default endpoint |
+|----------|------|-----------|------|-----------------|
+| OpenAI | yes | yes | API key | `https://api.openai.com/v1` |
+| Anthropic | yes | yes | API key | `https://api.anthropic.com/v1` |
+| Ollama | yes | yes | none | `http://localhost:11434` |
+
+The `base_url` field on `ProviderConfig` lets you point any provider at a compatible
+endpoint (e.g. Azure OpenAI, local OpenAI-compatible servers).
+
+## Further Reading
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — design decisions, component overview, and provider protocol
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, code style, and how to add a new provider
+- [Documentation](https://alexmar07.github.io/llmwire) — full API reference and guides
+
+## License
+
+MIT. See [LICENSE](LICENSE).

llmwire-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+llmwire/__init__.py,sha256=iuzC_QMFDqlQBQ-y1NiAvXwsS-zcNawnWQCYvCo_5uU,587
+llmwire/client.py,sha256=gL_PTXuexyg2IlGijc_Hq5gaWfp1Hi2du9IYNTmoBxU,9176
+llmwire/config.py,sha256=SuMh8XmZ1afJRul-mt9UMxlTHsguxd9MXFbzqa9B_Rc,1164
+llmwire/exceptions.py,sha256=EyAfD6I3XW3BVNCEUMrUHP8ySUsdKvwxNA9yrfQki_E,680
+llmwire/models.py,sha256=hsEELSMRCipmAZoowac-anQ0Zs5lfgcnjnerJV4-qUY,779
+llmwire/provider.py,sha256=f8cYkSW0XU4JEATVXIYAR45rtJ67nALeadeFzTLWJSo,885
+llmwire/retry.py,sha256=copsUVKgkSsr_0yxACFJMV7-2tkdYQYcFLNVCMWaS1s,1480
+llmwire/providers/__init__.py,sha256=E2OsYM2Pr6X0880XFOtru3B9peW-SnJ61MRnPyumTVw,267
+llmwire/providers/anthropic.py,sha256=RBmsm-AKD6floj67gFRGclac0CR87x6JXABDWBy8-80,7591
+llmwire/providers/ollama.py,sha256=bYqdMkzX4BLdwQi1eq9sanOkn14QAevsykQoE62XlGU,6462
+llmwire/providers/openai.py,sha256=CWKIN72wprosC3YhwysljCpl0acVSO5ok18rRUJcW7Q,6400
+llmwire-0.1.0.dist-info/METADATA,sha256=M19uBPz8r-RTf73rWoDGbdOuiZzLcyrZk6fqW811tb4,5806
+llmwire-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+llmwire-0.1.0.dist-info/licenses/LICENSE,sha256=7C2NtwSu9KtyzsvrXhVkHID3RFuva1Dyj8UhvcTAWjE,1075
+llmwire-0.1.0.dist-info/RECORD,,

llmwire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

llmwire-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandro Marotta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.