llmwire 0.1.0__tar.gz

llmwire-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/llmwire/
+
+      - name: Test
+        run: pytest tests/ -v --cov=llmwire --cov-report=xml --cov-fail-under=80
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

llmwire-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+*.so
+.coverage
+htmlcov/
+site/

llmwire-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,146 @@
+# Architecture
+
+## Design Philosophy
+
+LLMWire is built around three principles:
+
+1. **Minimal dependencies.** The runtime requires only `httpx`, `pydantic`,
+   `pydantic-settings`, and `pyyaml`. There are no provider SDKs. Each provider
+   adapter speaks the raw HTTP API directly, keeping the install small and the
+   upgrade surface narrow.
+
+2. **Async-first.** Every I/O path is async (`httpx.AsyncClient`, `async for` streaming).
+   There is no sync wrapper; callers use `asyncio.run()` or their own event loop.
+
+3. **Protocol-based extensibility.** Providers satisfy a structural `Protocol` rather
+   than inheriting from a base class. This keeps provider implementations independent
+   and makes it easy to add new ones without touching core logic.
+
+---
+
+## Component Overview
+
+```
+                    ┌─────────────────────────────────────┐
+                    │             LLMClient                │
+                    │  ┌──────────────────────────────┐   │
+                    │  │  chat() / stream()            │   │
+                    │  │  - normalize messages         │   │
+                    │  │  - build schema system msg    │   │
+                    │  │  - iterate providers_to_try   │   │
+                    │  └──────────────────┬───────────┘   │
+                    │                     │               │
+                    │         retry_with_backoff()        │
+                    │   (exponential backoff + jitter)    │
+                    │                     │               │
+                    │        ┌────────────┴──────────┐    │
+                    │        │                       │    │
+                    │   OpenAI         Anthropic    Ollama │
+                    │  Provider        Provider   Provider │
+                    │  (httpx)         (httpx)    (httpx)  │
+                    └─────────────────────────────────────┘
+```
+
+**`LLMClient`** (`src/llmwire/client.py`) is the only public entry point. It holds an
+ordered list of provider instances built from `LLMConfig` at construction time. `chat()`
+and `stream()` iterate that list, delegating each attempt to `retry_with_backoff()`.
+
+**`retry_with_backoff`** (`src/llmwire/retry.py`) is a standalone async function that
+runs a callable up to `max_retries` times. Between attempts it sleeps for
+`base_delay * 2^attempt + jitter` seconds. It only retries exceptions in the
+`retryable_exceptions` tuple; other exceptions propagate immediately.
+
+**Provider adapters** (`src/llmwire/providers/`) are plain classes. Each constructs a
+single `httpx.AsyncClient` in `__init__` and uses it for all requests. `LLMClient`
+calls `await provider._client.aclose()` in `close()` / `__aexit__`.
+
+---
+
+## Provider Protocol
+
+`Provider` (`src/llmwire/provider.py`) is a `typing.Protocol`:
+
+```python
+class Provider(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    async def chat(
+        self, messages: list[Message], *, model: str | None, temperature: float,
+        max_tokens: int | None,
+    ) -> ChatResponse: ...
+
+    async def stream(
+        self, messages: list[Message], *, model: str | None, temperature: float,
+        max_tokens: int | None,
+    ) -> AsyncIterator[StreamChunk]: ...
+```
+
+Any class that satisfies this interface structurally can be used as a provider.
+`_PROVIDER_MAP` in `client.py` maps the string name from `ProviderConfig.name` to the
+concrete class. Adding a new provider means:
+
+1. Creating the adapter class in `src/llmwire/providers/`.
+2. Registering it in `_PROVIDER_MAP`.
+3. Exporting it from `src/llmwire/providers/__init__.py`.
+
+---
+
+## Retry and Fallback Strategy
+
+`LLMConfig.fallback` controls whether `LLMClient` tries more than one provider:
+
+- `fallback=False` — only `self._providers[0]` is tried.
+- `fallback=True` (default) — all providers are tried in order until one succeeds.
+
+Within each provider attempt, `retry_with_backoff()` retries `ProviderError` up to
+`max_retries` times. The delay sequence for `base_delay=1.0` is roughly:
+`1 s → 2 s → 4 s` (plus up to 10 % random jitter each time).
+
+If a streaming response has already started yielding chunks, a mid-stream `ProviderError`
+is re-raised immediately — falling back mid-stream would produce a corrupt response.
+
+If all providers exhaust their retries, `AllProvidersFailedError` is raised with the
+list of individual `ProviderError` instances accessible as `.errors`.
+
+---
+
+## Structured Output
+
+`LLMClient.chat(..., response_model=MyModel)` works as follows:
+
+1. The JSON schema of `MyModel` is serialised once and cached in `_schema_cache`
+   (keyed by class identity).
+2. A system `Message` is prepended instructing the model to return only raw JSON
+   matching the schema.
+3. The response content string is passed to `MyModel.model_validate_json()`, which
+   raises `pydantic.ValidationError` on malformed output.
+
+This approach is provider-agnostic and requires no function-calling support from the
+underlying API.
+
+---
+
+## File Structure
+
+```
+llmwire/
+├── src/llmwire/
+│   ├── __init__.py          # public re-exports and __version__
+│   ├── client.py            # LLMClient — main orchestrator
+│   ├── config.py            # LLMConfig, ProviderConfig (pydantic-settings)
+│   ├── exceptions.py        # LLMWireError, ProviderError, AllProvidersFailedError
+│   ├── models.py            # Message, ChatResponse, StreamChunk, Usage
+│   ├── provider.py          # Provider protocol
+│   ├── retry.py             # retry_with_backoff()
+│   └── providers/
+│       ├── __init__.py
+│       ├── anthropic.py     # AnthropicProvider
+│       ├── ollama.py        # OllamaProvider
+│       └── openai.py        # OpenAIProvider
+├── tests/                   # pytest test suite (46 tests)
+├── docs/                    # MkDocs source
+├── .github/workflows/ci.yml # GitHub Actions CI/CD
+├── pyproject.toml           # build config, dependencies, tool config
+└── mkdocs.yml               # documentation site config
+```

llmwire-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+
+## Dev Setup
+
+```bash
+git clone https://github.com/alexmar07/llmwire.git
+cd llmwire
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode together with `pytest`, `pytest-asyncio`,
+`pytest-cov`, `respx`, `ruff`, and `mypy`.
+
+To also build or preview the documentation:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Running Checks
+
+All three checks must pass before opening a pull request:
+
+```bash
+# Lint and format check
+ruff check src/ tests/
+
+# Static type checking
+mypy src/llmwire/
+
+# Tests with coverage report
+pytest tests/ -v --cov=src/llmwire --cov-report=term-missing
+```
+
+The CI pipeline runs these checks on Python 3.12 and 3.13.
+
+## Code Style
+
+- **Type hints** are required on every function and method signature, including
+  `self`-less module-level functions.
+- **Ruff** enforces PEP 8, import ordering, and a set of quality rules (see
+  `[tool.ruff.lint]` in `pyproject.toml`). Run `ruff check --fix` to auto-fix
+  safe violations.
+- **Mypy strict mode** is enabled. `# type: ignore` comments require a justifying
+  comment and should be rare.
+- **Docstrings** use Google style and are required on all public classes and methods.
+- Lines are limited to **100 characters**.
+
+## Adding a New Provider
+
+1. Create `src/llmwire/providers/<name>.py` with a class `<Name>Provider`.
+   The class must satisfy the `Provider` protocol (see
+   [`src/llmwire/provider.py`](src/llmwire/provider.py)):
+   - `name` property returning the lowercase provider string
+   - `async def chat(...)` returning `ChatResponse`
+   - `async def stream(...)` yielding `StreamChunk` objects
+
+2. Export the class from `src/llmwire/providers/__init__.py`.
+
+3. Add the provider to `_PROVIDER_MAP` in `src/llmwire/client.py`:
+   ```python
+   _PROVIDER_MAP: dict[str, type[Any]] = {
+       "openai": OpenAIProvider,
+       "anthropic": AnthropicProvider,
+       "ollama": OllamaProvider,
+       "<name>": <Name>Provider,   # add here
+   }
+   ```
+
+4. Write tests in `tests/test_<name>_provider.py`. Use `respx` to mock HTTP
+   calls — no real API credentials should appear in tests.
+
+5. Document the provider in `docs/getting-started.md` and update the provider
+   support table in `README.md`.
+
+## Pull Request Process
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes and ensure all checks pass (lint, type check, tests).
+3. Add or update tests so coverage stays above 80 %.
+4. Update documentation if you added or changed public API.
+5. Open a pull request against `main` with a clear description of what changes
+   and why.
+
+Pull requests are reviewed for correctness, type safety, test coverage, and
+consistency with the existing code style.

llmwire-0.1.0/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.

llmwire-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,136 @@
+# 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/docs/api-reference.md

@@ -0,0 +1,21 @@
+# API Reference
+
+::: llmwire.client.LLMClient
+
+::: llmwire.config.LLMConfig
+
+::: llmwire.config.ProviderConfig
+
+::: llmwire.models.Message
+
+::: llmwire.models.ChatResponse
+
+::: llmwire.models.StreamChunk
+
+::: llmwire.models.Usage
+
+::: llmwire.exceptions.LLMWireError
+
+::: llmwire.exceptions.ProviderError
+
+::: llmwire.exceptions.AllProvidersFailedError