dr-providers 0.1.0__tar.gz

dr_providers-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.worktrees
+.DS_Store
+*.swp
+.cache/
+.ruff_cache/
+.venv/
+dist/
+**/__pycache__/

dr_providers-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0
+
+Initial release.
+
+- OpenRouter provider via `OpenRouterProvider` and generic `ApiProvider` transport
+- Unified `LlmRequest` with `prepare()`, `endpoint()`, `headers()`, and `json_payload()`
+- Minimal chat-completions response parsing into `LlmResponse`
+- Typed config models: `ReasoningSpec`, `SamplingControls`, `LlmConfig`
+- Module layout: `errors`, `transport_config`, `providers/openrouter`, `from_prompt`
+- Public API exported from top-level `dr_providers` package
+- Optional CLI extra: `pip install dr-providers[cli]` provides `query-provider`

dr_providers-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 danielle rothermel
+
+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.

dr_providers-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: dr-providers
+Version: 0.1.0
+Summary: OpenRouter LLM query client with typed requests and responses.
+Project-URL: Repository, https://github.com/danielle-rothermel/dr-providers
+Project-URL: Issues, https://github.com/danielle-rothermel/dr-providers/issues
+Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: tenacity>=9.1.4
+Provides-Extra: cli
+Requires-Dist: typer>=0.26.7; extra == 'cli'
+Provides-Extra: notebooks
+Requires-Dist: marimo[recommended]>=0.23.10; extra == 'notebooks'
+Description-Content-Type: text/markdown
+
+# dr-providers
+
+OpenRouter LLM query client with typed requests and responses. Requires Python 3.13+.
+
+## Install
+
+```bash
+pip install dr-providers
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add dr-providers
+```
+
+### Optional CLI
+
+```bash
+pip install "dr-providers[cli]"
+query-provider --help
+```
+
+## Authentication
+
+Set your OpenRouter API key:
+
+```bash
+export OPENROUTER_API_KEY="sk-or-..."
+```
+
+## Library usage
+
+```python
+from dr_providers import (
+    LlmRequest,
+    Message,
+    MessageRole,
+    OpenRouterProvider,
+    ProviderName,
+)
+
+with OpenRouterProvider() as provider:
+    response = provider.generate(
+        LlmRequest(
+            provider=ProviderName.OPENROUTER,
+            model="openai/gpt-4o-mini",
+            messages=[
+                Message(role=MessageRole.USER, content="Say hello in one word."),
+            ],
+        )
+    )
+    print(response.text)
+```
+
+### Prompt helper
+
+For scripts and demos, `query_from_prompt` builds a request from plain strings:
+
+```python
+from dr_providers import OpenRouterProvider, ProviderName
+from dr_providers.query.from_prompt import query_from_prompt
+
+with OpenRouterProvider() as provider:
+    response = query_from_prompt(
+        provider,
+        ProviderName.OPENROUTER,
+        model="openai/gpt-4o-mini",
+        prompt="Say hello in one word.",
+    )
+```
+
+This helper is not re-exported from the top-level package.
+
+## Public API
+
+Import stable symbols from the top-level package:
+
+```python
+from dr_providers import LlmRequest, OpenRouterProvider, ReasoningSpec
+```
+
+See `dr_providers.__all__` for the full list.
+
+## Development
+
+```bash
+uv sync
+scripts/pre-check.sh
+```
+
+Run the CLI from the repo without installing:
+
+```bash
+uv run python scripts/query_provider.py --model openai/gpt-4o-mini -m "hi"
+```

dr_providers-0.1.0/README.md

@@ -0,0 +1,96 @@
+# dr-providers
+
+OpenRouter LLM query client with typed requests and responses. Requires Python 3.13+.
+
+## Install
+
+```bash
+pip install dr-providers
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add dr-providers
+```
+
+### Optional CLI
+
+```bash
+pip install "dr-providers[cli]"
+query-provider --help
+```
+
+## Authentication
+
+Set your OpenRouter API key:
+
+```bash
+export OPENROUTER_API_KEY="sk-or-..."
+```
+
+## Library usage
+
+```python
+from dr_providers import (
+    LlmRequest,
+    Message,
+    MessageRole,
+    OpenRouterProvider,
+    ProviderName,
+)
+
+with OpenRouterProvider() as provider:
+    response = provider.generate(
+        LlmRequest(
+            provider=ProviderName.OPENROUTER,
+            model="openai/gpt-4o-mini",
+            messages=[
+                Message(role=MessageRole.USER, content="Say hello in one word."),
+            ],
+        )
+    )
+    print(response.text)
+```
+
+### Prompt helper
+
+For scripts and demos, `query_from_prompt` builds a request from plain strings:
+
+```python
+from dr_providers import OpenRouterProvider, ProviderName
+from dr_providers.query.from_prompt import query_from_prompt
+
+with OpenRouterProvider() as provider:
+    response = query_from_prompt(
+        provider,
+        ProviderName.OPENROUTER,
+        model="openai/gpt-4o-mini",
+        prompt="Say hello in one word.",
+    )
+```
+
+This helper is not re-exported from the top-level package.
+
+## Public API
+
+Import stable symbols from the top-level package:
+
+```python
+from dr_providers import LlmRequest, OpenRouterProvider, ReasoningSpec
+```
+
+See `dr_providers.__all__` for the full list.
+
+## Development
+
+```bash
+uv sync
+scripts/pre-check.sh
+```
+
+Run the CLI from the repo without installing:
+
+```bash
+uv run python scripts/query_provider.py --model openai/gpt-4o-mini -m "hi"
+```

dr_providers-0.1.0/pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+name = "dr-providers"
+version = "0.1.0"
+description = "OpenRouter LLM query client with typed requests and responses."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Danielle Rothermel", email = "danielle.rothermel@gmail.com" }
+]
+requires-python = ">=3.13"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+    "tenacity>=9.1.4",
+]
+
+[project.optional-dependencies]
+cli = ["typer>=0.26.7"]
+notebooks = ["marimo[recommended]>=0.23.10"]
+
+[project.urls]
+Repository = "https://github.com/danielle-rothermel/dr-providers"
+Issues = "https://github.com/danielle-rothermel/dr-providers/issues"
+
+[project.scripts]
+query-provider = "dr_providers.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.15.18",
+    "ty>=0.0.51",
+    "typer>=0.26.7",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.env",
+    "/.env.example",
+    "/.gitignore",
+    "/.python-version",
+    "/uv.lock",
+    "/scripts",
+    "/nbs",
+    "/.cache",
+    "/.github",
+    "/tests",
+    "/dist",
+    "/AGENTS.md",
+    "/CLAUDE.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+include = ["scripts/**/*.py", "src/**/*.py", "tests/**/*.py"]
+line-length = 79
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "DTZ",
+    "E",
+    "F",
+    "FA",
+    "FBT",
+    "FLY",
+    "FURB",
+    "G",
+    "I",
+    "ICN",
+    "ISC",
+    "LOG",
+    "N",
+    "NPY",
+    "PD",
+    "PERF",
+    "PIE",
+    "PL",
+    "PTH",
+    "PT",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "SLOT",
+    "T10",
+    "TC",
+    "TID",
+    "TRY",
+    "UP",
+    "W",
+    "YTT",
+]
+ignore = ["PLR1711", "S101", "TRY003"]
+
+[tool.ruff.lint.per-file-ignores]
+"nbs/**/*.py" = ["E501", "F841", "RET503", "B018"]
+"tests/**/*.py" = ["PLR2004", "PLC0415"]
+
+[tool.ty.src]
+include = ["scripts", "src", "tests"]
+exclude = ["nbs"]

dr_providers-0.1.0/src/dr_providers/__init__.py

@@ -0,0 +1,34 @@
+from dr_providers.query import (
+    ApiProvider,
+    LlmConfig,
+    LlmRequest,
+    LlmResponse,
+    Message,
+    MessageRole,
+    OpenRouterProvider,
+    ProviderError,
+    ProviderName,
+    ProviderSemanticError,
+    ProviderTransportError,
+    ReasoningSpec,
+    RequestControls,
+    SamplingControls,
+)
+
+__all__ = [
+    "ApiProvider",
+    "LlmConfig",
+    "LlmRequest",
+    "LlmResponse",
+    "Message",
+    "MessageRole",
+    "OpenRouterProvider",
+    "ProviderError",
+    "ProviderName",
+    "ProviderSemanticError",
+    "ProviderTransportError",
+    "ReasoningSpec",
+    "RequestControls",
+    "SamplingControls",
+]
+__version__ = "0.1.0"

dr_providers-0.1.0/src/dr_providers/cli.py

@@ -0,0 +1,138 @@
+"""CLI for querying OpenRouter with model, reasoning, and sampling options."""
+
+from __future__ import annotations
+
+import typer
+
+from dr_providers import (
+    LlmResponse,
+    OpenRouterProvider,
+    ProviderName,
+    ReasoningSpec,
+    SamplingControls,
+)
+from dr_providers.names import EffortLevel
+from dr_providers.query.from_prompt import query_from_prompt
+
+
+def _parse_effort(value: str) -> EffortLevel:
+    normalized = value.lower()
+    try:
+        return EffortLevel(normalized)
+    except ValueError:
+        allowed = ", ".join(level.value for level in EffortLevel)
+        raise typer.BadParameter(
+            f"Invalid effort {value!r}. Expected one of: {allowed}"
+        ) from None
+
+
+def _build_reasoning(
+    *,
+    effort: str | None,
+    reasoning_enabled: bool | None,
+) -> ReasoningSpec | None:
+    if effort is not None and reasoning_enabled is not None:
+        raise typer.BadParameter(
+            "Use --effort for effort-style models or "
+            "--reasoning-enabled/--reasoning-disabled for toggle-style "
+            "models, not both."
+        )
+    if effort is not None:
+        return ReasoningSpec(effort=_parse_effort(effort))
+    if reasoning_enabled is not None:
+        return ReasoningSpec(enabled=reasoning_enabled)
+    return None
+
+
+def _build_sampling(
+    *,
+    temperature: float | None,
+    top_p: float | None,
+) -> SamplingControls | None:
+    if temperature is None and top_p is None:
+        return None
+    return SamplingControls(temperature=temperature, top_p=top_p)
+
+
+def _query_provider(  # noqa: PLR0913
+    *,
+    effort: str | None,
+    reasoning_enabled: bool | None,
+    temperature: float | None,
+    top_p: float | None,
+    max_tokens: int | None,
+    model: str,
+    message: str,
+) -> LlmResponse:
+    reasoning = _build_reasoning(
+        effort=effort,
+        reasoning_enabled=reasoning_enabled,
+    )
+    sampling = _build_sampling(temperature=temperature, top_p=top_p)
+    with OpenRouterProvider() as provider:
+        return query_from_prompt(
+            provider=provider,
+            provider_name=ProviderName.OPENROUTER,
+            model=model,
+            prompt=message,
+            reasoning=reasoning,
+            sampling=sampling,
+            max_tokens=max_tokens,
+        )
+
+
+def query(  # noqa: PLR0913
+    model: str = typer.Option(..., "--model", help="OpenRouter model id."),
+    message: str = typer.Option(
+        ...,
+        "--message",
+        "-m",
+        help="User message to send.",
+    ),
+    effort: str | None = typer.Option(
+        None,
+        "--effort",
+        "-e",
+        help="Reasoning effort (low, medium, high) for effort-style models.",
+    ),
+    reasoning_enabled: bool | None = typer.Option(  # noqa: FBT001
+        None,
+        "--reasoning-enabled/--reasoning-disabled",
+        help="Enable or disable reasoning for toggle-style models.",
+    ),
+    max_tokens: int | None = typer.Option(
+        None,
+        "--max-tokens",
+        help="Completion token limit. Omit to use provider defaults.",
+    ),
+    temperature: float | None = typer.Option(
+        None,
+        "--temperature",
+        "--temp",
+        help="Sampling temperature.",
+    ),
+    top_p: float | None = typer.Option(
+        None,
+        "--top-p",
+        help="Sampling top-p.",
+    ),
+) -> None:
+    response = _query_provider(
+        model=model,
+        message=message,
+        effort=effort,
+        reasoning_enabled=reasoning_enabled,
+        temperature=temperature,
+        top_p=top_p,
+        max_tokens=max_tokens,
+    )
+    typer.echo(response.text)
+    typer.echo(f"({response.latency_ms} ms)", err=True)
+
+
+def main() -> None:
+    typer.run(query)
+
+
+if __name__ == "__main__":
+    main()

dr_providers-0.1.0/src/dr_providers/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from dr_providers.names import EffortLevel, ProviderName  # noqa: TC001
+
+
+class ReasoningSpec(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    enabled: bool | None = None
+    effort: EffortLevel | None = None
+
+
+class SamplingControls(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    temperature: float | None = None
+    top_p: float | None = None
+
+    def is_empty(self) -> bool:
+        return self.temperature is None and self.top_p is None
+
+
+class LlmConfig(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    provider: ProviderName
+    model: str
+    max_tokens: int | None = None
+    reasoning: ReasoningSpec | None = None
+    sampling: SamplingControls | None = None

dr_providers-0.1.0/src/dr_providers/names.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Self
+
+
+class ProviderName(StrEnum):
+    _api_base_url: str
+
+    def __new__(cls, value: str, api_base_url: str) -> Self:
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        obj._api_base_url = api_base_url
+        return obj
+
+    OPENROUTER = "openrouter", "https://openrouter.ai/api/v1"
+
+    def api_key_env(self) -> str:
+        return f"{self.name}_API_KEY"
+
+    @property
+    def api_base_url(self) -> str:
+        return self._api_base_url
+
+
+class EffortLevel(StrEnum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class ControlRequestStyle(StrEnum):
+    NONE = "none"
+    ENABLED_FLAG = "enabled_flag"
+    EFFORT = "effort"
+
+
+class MessageRole(StrEnum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+# TODO: remove this
+class OpenRouterReasoningKey(StrEnum):
+    REASONING = "reasoning"
+    ENABLED = "enabled"
+    EFFORT = "effort"

dr_providers-0.1.0/src/dr_providers/query/__init__.py

@@ -0,0 +1,29 @@
+from dr_providers.config import LlmConfig, ReasoningSpec, SamplingControls
+from dr_providers.names import MessageRole, ProviderName
+from dr_providers.query.errors import (
+    ProviderError,
+    ProviderSemanticError,
+    ProviderTransportError,
+)
+from dr_providers.query.providers import OpenRouterProvider
+from dr_providers.query.reasoning import RequestControls
+from dr_providers.query.request import LlmRequest, Message
+from dr_providers.query.response import LlmResponse
+from dr_providers.query.transport import ApiProvider
+
+__all__ = [
+    "ApiProvider",
+    "LlmConfig",
+    "LlmRequest",
+    "LlmResponse",
+    "Message",
+    "MessageRole",
+    "OpenRouterProvider",
+    "ProviderError",
+    "ProviderName",
+    "ProviderSemanticError",
+    "ProviderTransportError",
+    "ReasoningSpec",
+    "RequestControls",
+    "SamplingControls",
+]

dr_providers-0.1.0/src/dr_providers/query/errors.py

@@ -0,0 +1,10 @@
+class ProviderError(Exception):
+    pass
+
+
+class ProviderTransportError(ProviderError):
+    pass
+
+
+class ProviderSemanticError(ProviderError):
+    pass

dr_providers-0.1.0/src/dr_providers/query/from_prompt.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dr_providers.names import MessageRole, ProviderName
+from dr_providers.query.request import LlmRequest, Message
+
+if TYPE_CHECKING:
+    from dr_providers.config import ReasoningSpec, SamplingControls
+    from dr_providers.query.response import LlmResponse
+    from dr_providers.query.transport import ApiProvider
+
+
+def query_from_prompt(  # noqa: PLR0913
+    provider: ApiProvider,
+    provider_name: ProviderName,
+    model: str,
+    prompt: str,
+    *,
+    system: str | None = None,
+    max_tokens: int | None = None,
+    reasoning: ReasoningSpec | None = None,
+    sampling: SamplingControls | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> LlmResponse:
+    messages: list[Message] = []
+    if system is not None:
+        messages.append(Message(role=MessageRole.SYSTEM, content=system))
+    messages.append(Message(role=MessageRole.USER, content=prompt))
+    request = LlmRequest(
+        provider=provider_name,
+        model=model,
+        messages=messages,
+        max_tokens=max_tokens,
+        reasoning=reasoning,
+        sampling=sampling,
+        metadata=metadata or {},
+    )
+    return provider.generate(request)

dr_providers-0.1.0/src/dr_providers/query/providers/__init__.py

@@ -0,0 +1,3 @@
+from dr_providers.query.providers.openrouter import OpenRouterProvider
+
+__all__ = ["OpenRouterProvider"]

dr_providers-0.1.0/src/dr_providers/query/providers/openrouter.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+from dr_providers.names import ProviderName
+from dr_providers.query.transport import ApiProvider
+from dr_providers.query.transport_config import ProviderConfig
+
+
+class OpenRouterProvider(ApiProvider):
+    def __init__(
+        self,
+        *,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            config=ProviderConfig(
+                name=ProviderName.OPENROUTER,
+                base_url=ProviderName.OPENROUTER.api_base_url,
+                api_key_env=ProviderName.OPENROUTER.api_key_env(),
+            ),
+            client=client,
+        )

dr_providers-0.1.0/src/dr_providers/query/reasoning.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dr_providers.config import ReasoningSpec  # noqa: TC001
+
+
+class ReasoningWarning(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    message: str
+    provider: str | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+def _reasoning_extra_body(spec: ReasoningSpec) -> dict[str, Any]:
+    if spec.enabled is not None:
+        payload: dict[str, Any] = {"enabled": spec.enabled}
+    elif spec.effort is not None:
+        payload = {"effort": spec.effort}
+    else:
+        payload = {"reasoning": True}
+    return {"reasoning": payload}
+
+
+class RequestControls(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    extra_body: dict[str, Any] = Field(default_factory=dict)
+    warnings: list[ReasoningWarning] = Field(default_factory=list)
+
+    @classmethod
+    def from_reasoning(
+        cls, reasoning: ReasoningSpec | None
+    ) -> RequestControls:
+        if reasoning is None:
+            return cls()
+        return cls(extra_body=_reasoning_extra_body(reasoning))

dr_providers-0.1.0/src/dr_providers/query/request.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+from dr_providers.config import ReasoningSpec, SamplingControls  # noqa: TC001
+from dr_providers.names import MessageRole, ProviderName  # noqa: TC001
+from dr_providers.query.reasoning import ReasoningWarning, RequestControls
+from dr_providers.query.transport_config import ProviderConfig, resolve_api_key
+
+
+class Message(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    role: MessageRole
+    content: str
+
+
+class LlmRequest(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    provider: ProviderName
+    model: str
+    messages: list[Message]
+    max_tokens: int | None = None
+    reasoning: ReasoningSpec | None = None
+    sampling: SamplingControls | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    base_url: str | None = Field(default=None, exclude=True)
+    chat_path: str | None = Field(default=None, exclude=True)
+    api_key: str | None = Field(default=None, exclude=True, repr=False)
+    idempotency_key: str | None = Field(default=None, exclude=True)
+    extra_body: dict[str, Any] = Field(default_factory=dict, exclude=True)
+    warnings: list[ReasoningWarning] = Field(
+        default_factory=list, exclude=True
+    )
+
+    @property
+    def has_sampling_controls(self) -> bool:
+        return self.sampling is not None and not self.sampling.is_empty()
+
+    @property
+    def sampling_temperature(self) -> float | None:
+        return self.sampling.temperature if self.sampling is not None else None
+
+    @property
+    def sampling_top_p(self) -> float | None:
+        return self.sampling.top_p if self.sampling is not None else None
+
+    def prepare(
+        self,
+        config: ProviderConfig,
+        *,
+        controls: RequestControls | None = None,
+    ) -> LlmRequest:
+        request_controls = controls or RequestControls.from_reasoning(
+            self.reasoning
+        )
+        return self.model_copy(
+            update={
+                "base_url": config.base_url,
+                "chat_path": config.chat_path,
+                "api_key": resolve_api_key(config, label=self.provider),
+                "idempotency_key": self._resolve_idempotency_key(),
+                "extra_body": request_controls.extra_body,
+                "warnings": request_controls.warnings,
+            }
+        )
+
+    def _resolve_idempotency_key(self) -> str:
+        raw_idempotency_key = self.metadata.get("idempotency_key")
+        if isinstance(raw_idempotency_key, str) and raw_idempotency_key:
+            return raw_idempotency_key
+        return uuid4().hex
+
+    def _require_prepared(self) -> None:
+        if self.api_key is None or self.base_url is None:
+            raise ValueError("LlmRequest is not prepared for transport")
+
+    def endpoint(self) -> str:
+        self._require_prepared()
+        base_url = self.base_url
+        if base_url is None:
+            raise ValueError("LlmRequest is not prepared for transport")
+        if self.chat_path is None:
+            return base_url
+        return base_url.rstrip("/") + self.chat_path
+
+    def headers(self) -> dict[str, str]:
+        self._require_prepared()
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Idempotency-Key": self.idempotency_key or "",
+        }
+
+    def json_payload(self) -> dict[str, Any]:
+        self._require_prepared()
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": [
+                {"role": message.role, "content": message.content}
+                for message in self.messages
+            ],
+        }
+        if self.sampling_temperature is not None:
+            payload["temperature"] = self.sampling_temperature
+        if self.sampling_top_p is not None:
+            payload["top_p"] = self.sampling_top_p
+        if self.max_tokens is not None:
+            # TODO: will this break things?
+            payload["max_tokens"] = self.max_tokens
+            payload["max_completion_tokens"] = self.max_tokens
+
+        overlapping_keys = sorted(set(self.extra_body) & set(payload))
+        if overlapping_keys:
+            conflicts = ", ".join(overlapping_keys)
+            raise ValueError(
+                "extra_body conflicts with "
+                f"validated payload keys: {conflicts}"
+            )
+        payload.update(self.extra_body)
+        return payload

dr_providers-0.1.0/src/dr_providers/query/response.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+from enum import IntEnum
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dr_providers.query.errors import (
+    ProviderSemanticError,
+    ProviderTransportError,
+)
+from dr_providers.query.reasoning import ReasoningWarning  # noqa: TC001
+
+if TYPE_CHECKING:
+    import httpx
+
+    from dr_providers.query.request import LlmRequest
+
+
+class HttpStatusCode(IntEnum):
+    TRANSIENT_ERROR = 500
+    TIMEOUT = 408
+    TOO_MANY_REQUESTS = 429
+    BAD_REQUEST = 400
+
+
+def validate_http_response(
+    *,
+    provider_label: str,
+    status_code: int,
+    response_text_preview: str,
+    json_error: str | None,
+    response_shape_error: str | None,
+) -> None:
+    if status_code >= HttpStatusCode.TRANSIENT_ERROR or status_code in {
+        HttpStatusCode.TIMEOUT,
+        HttpStatusCode.TOO_MANY_REQUESTS,
+    }:
+        raise ProviderTransportError(
+            f"{provider_label} transient error status={status_code} "
+            f"body={response_text_preview}"
+        )
+    if status_code >= HttpStatusCode.BAD_REQUEST:
+        raise ProviderSemanticError(
+            f"{provider_label} rejected request status={status_code} "
+            f"body={response_text_preview}"
+        )
+    if json_error is not None:
+        raise ProviderTransportError(
+            f"{provider_label} invalid JSON response: {json_error}"
+        )
+    if response_shape_error is not None:
+        raise ProviderSemanticError(
+            f"{provider_label} response shape invalid: {response_shape_error}"
+        )
+
+
+class CallError(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    error_type: str
+    message: str
+    retryable: bool = False
+    raw_json: dict[str, Any] | None = None
+
+
+class LlmResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    raw_json: dict[str, Any] = Field(default_factory=dict)
+    provider: str
+    model: str
+    latency_ms: int
+    text: str
+    finish_reason: str | None = None
+    warnings: list[Any] = Field(default_factory=list)
+
+
+def _parse_response_json(
+    response: httpx.Response,
+) -> tuple[dict[str, Any] | None, str | None, str | None]:
+    try:
+        body_raw = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        return None, str(exc), None
+    if not isinstance(body_raw, dict):
+        return None, None, "expected JSON object"
+    return body_raw, None, None
+
+
+def _extract_completion_fields(
+    body: dict[str, Any], *, provider_label: str
+) -> tuple[str, str | None]:
+    choices = body.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise ProviderSemanticError(
+            f"{provider_label} response missing choices"
+        )
+    choice = choices[0]
+    if not isinstance(choice, dict):
+        raise ProviderSemanticError(
+            f"{provider_label} response choice invalid"
+        )
+    finish_reason = choice.get("finish_reason")
+    finish_reason_str = (
+        finish_reason if isinstance(finish_reason, str) else None
+    )
+    message = choice.get("message")
+    if not isinstance(message, dict):
+        return "", finish_reason_str
+    content = message.get("content")
+    text = content if isinstance(content, str) else ""
+    return text, finish_reason_str
+
+
+def llm_response_from_http(
+    response: httpx.Response,
+    request: LlmRequest,
+    *,
+    latency_ms: int,
+    warnings: list[ReasoningWarning],
+) -> LlmResponse:
+    provider_label = str(request.provider)
+    response_text_preview = response.text[:500]
+    body_raw, json_error, shape_error = _parse_response_json(response)
+    validate_http_response(
+        provider_label=provider_label,
+        status_code=response.status_code,
+        response_text_preview=response_text_preview,
+        json_error=json_error,
+        response_shape_error=shape_error,
+    )
+    if body_raw is None:
+        raise ProviderSemanticError(
+            f"{provider_label} response shape invalid: missing body"
+        )
+    text, finish_reason = _extract_completion_fields(
+        body_raw, provider_label=provider_label
+    )
+    return LlmResponse(
+        text=text,
+        finish_reason=finish_reason,
+        latency_ms=latency_ms,
+        raw_json=body_raw,
+        provider=provider_label,
+        model=request.model,
+        warnings=warnings,
+    )

dr_providers-0.1.0/src/dr_providers/query/transport.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Self
+
+import httpx
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+from dr_providers.query.errors import ProviderTransportError
+from dr_providers.query.reasoning import RequestControls
+from dr_providers.query.response import llm_response_from_http
+
+if TYPE_CHECKING:
+    from dr_providers.query.request import LlmRequest
+    from dr_providers.query.response import LlmResponse
+    from dr_providers.query.transport_config import (
+        ProviderAvailabilityStatus,
+        ProviderConfig,
+    )
+
+
+class ProviderTransport(ABC):
+    _config: ProviderConfig
+
+    @property
+    def name(self) -> str:
+        return self._config.name
+
+    @property
+    def config(self) -> ProviderConfig:
+        return self._config
+
+    def availability_status(self) -> ProviderAvailabilityStatus:
+        return self._config.availability_status()
+
+    def is_available(self) -> bool:
+        return self.availability_status().available
+
+    @abstractmethod
+    def generate(self, request: LlmRequest) -> LlmResponse:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        return None
+
+
+class ApiProvider(ProviderTransport):
+    _config: ProviderConfig
+
+    def __init__(
+        self,
+        *,
+        config: ProviderConfig,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._config = config
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=config.timeout_seconds)
+
+    @property
+    def config(self) -> ProviderConfig:
+        return self._config
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    @retry(
+        retry=retry_if_exception_type(
+            (httpx.TimeoutException, httpx.TransportError)
+        ),
+        wait=wait_exponential_jitter(initial=0.5, max=8),
+        stop=stop_after_attempt(3),
+        reraise=True,
+    )
+    def _post_with_retry(self, prepared: LlmRequest) -> httpx.Response:
+        return self._client.post(
+            prepared.endpoint(),
+            headers=prepared.headers(),
+            json=prepared.json_payload(),
+        )
+
+    def generate(self, request: LlmRequest) -> LlmResponse:
+        controls = RequestControls.from_reasoning(request.reasoning)
+        prepared = request.prepare(self._config, controls=controls)
+        started = time.perf_counter()
+        try:
+            response = self._post_with_retry(prepared)
+        except (httpx.TimeoutException, httpx.TransportError) as exc:
+            raise ProviderTransportError(
+                f"{self.name} HTTP request failed: {exc}"
+            ) from exc
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        return llm_response_from_http(
+            response,
+            request,
+            latency_ms=latency_ms,
+            warnings=prepared.warnings,
+        )

dr_providers-0.1.0/src/dr_providers/query/transport_config.py

@@ -0,0 +1,94 @@
+import os
+import shutil
+from typing import Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
+
+from dr_providers.query.errors import ProviderSemanticError
+
+
+class ProviderAvailabilityStatus(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    provider: str
+    available: bool
+    missing_env_vars: tuple[str, ...] = Field(default_factory=tuple)
+    missing_executables: tuple[str, ...] = Field(default_factory=tuple)
+    supports_structured_output: bool = False
+
+
+class ProviderConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    supports_structured_output: bool = True
+    required_env_vars: list[str] = Field(default_factory=list)
+    required_executables: list[str] = Field(default_factory=list)
+    timeout_seconds: float = 120.0
+    base_url: str
+    api_key_env: str
+    api_key: str | None = None
+    chat_path: str | None = "/chat/completions"
+
+    @field_validator("chat_path")
+    @classmethod
+    def _ensure_leading_slash(cls, v: str | None) -> str | None:
+        if v is None:
+            return None
+        if not v.startswith("/"):
+            return f"/{v}"
+        return v
+
+    @model_validator(mode="after")
+    def _compute_api_env_requirements(self) -> Self:
+        if not self.api_key and self.api_key_env not in self.required_env_vars:
+            object.__setattr__(
+                self,
+                "required_env_vars",
+                [*self.required_env_vars, self.api_key_env],
+            )
+        return self
+
+    def missing_env_vars(self) -> tuple[str, ...]:
+        return tuple(
+            env_var
+            for env_var in self.required_env_vars
+            if not os.getenv(env_var)
+        )
+
+    def missing_executables(self) -> tuple[str, ...]:
+        return tuple(
+            executable
+            for executable in self.required_executables
+            if shutil.which(executable) is None
+        )
+
+    def availability_status(self) -> ProviderAvailabilityStatus:
+        missing_env = self.missing_env_vars()
+        missing_exec = self.missing_executables()
+        return ProviderAvailabilityStatus(
+            provider=self.name,
+            available=not missing_env and not missing_exec,
+            missing_env_vars=missing_env,
+            missing_executables=missing_exec,
+            supports_structured_output=self.supports_structured_output,
+        )
+
+
+def resolve_api_key(
+    config: ProviderConfig, *, label: str | None = None
+) -> str:
+    key = config.api_key or os.getenv(config.api_key_env)
+    if not key:
+        provider_label = label or config.name
+        raise ProviderSemanticError(
+            f"Missing API key for {provider_label}. "
+            f"Set {config.api_key_env} or pass config.api_key"
+        )
+    return key