jharness-providers 0.1.0__tar.gz

jharness_providers-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Local AI assistant/workspace state
+.codex/
+.claude/
+.gemini/
+.aider*
+
+# Pinned specification snapshot generated by scripts/sync_spec.py
+.jharness-spec/
+
+# Python
+__pycache__/
+*.py[cod]
+.python-version
+.venv/
+venv/
+ENV/
+
+# Python tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Packaging/build artifacts
+dist/
+build/
+*.egg-info/
+
+# Node/TypeScript SDK artifacts
+node_modules/
+coverage/
+.turbo/
+.next/
+*.tsbuildinfo
+
+# Logs
+*.log

jharness_providers-0.1.0/LICENSE

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

jharness_providers-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: jharness-providers
+Version: 0.1.0
+Summary: Concrete model provider adapters for the JHarness runtime
+Project-URL: Documentation, https://github.com/Ezio2000/jharness-python/tree/main/docs
+Project-URL: Homepage, https://github.com/Ezio2000/jharness-python
+Project-URL: Issues, https://github.com/Ezio2000/jharness-python/issues
+Project-URL: Repository, https://github.com/Ezio2000/jharness-python.git
+Author: JHarness contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,deepseek,model,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jharness-kernel<0.2.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# jharness-providers
+
+`jharness-providers` contains optional concrete implementations of the
+provider-neutral `jharness.kernel.Model` protocol. Public adapters are imported from
+provider namespaces:
+
+```bash
+uv add jharness-providers
+```
+
+```python
+from jharness.providers.anthropic import AnthropicModel
+from jharness.providers.deepseek import deepseek_anthropic_profile
+from jharness.providers.openai import OpenAIChatCompletionsModel
+```
+
+Provider transports, profiles, and codecs do not define runtime semantics.
+See the
+[provider documentation](https://github.com/Ezio2000/jharness-python/blob/main/docs/model-providers.md)
+and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_providers-0.1.0/README.md

@@ -0,0 +1,21 @@
+# jharness-providers
+
+`jharness-providers` contains optional concrete implementations of the
+provider-neutral `jharness.kernel.Model` protocol. Public adapters are imported from
+provider namespaces:
+
+```bash
+uv add jharness-providers
+```
+
+```python
+from jharness.providers.anthropic import AnthropicModel
+from jharness.providers.deepseek import deepseek_anthropic_profile
+from jharness.providers.openai import OpenAIChatCompletionsModel
+```
+
+Provider transports, profiles, and codecs do not define runtime semantics.
+See the
+[provider documentation](https://github.com/Ezio2000/jharness-python/blob/main/docs/model-providers.md)
+and
+[Python package boundaries](https://github.com/Ezio2000/jharness-python/blob/main/docs/python-package-boundaries.md).

jharness_providers-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "jharness-providers"
+version = "0.1.0"
+description = "Concrete model provider adapters for the JHarness runtime"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "JHarness contributors" }]
+keywords = ["ai", "anthropic", "deepseek", "model", "openai"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "jharness-kernel>=0.1.0,<0.2.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/Ezio2000/jharness-python/tree/main/docs"
+Homepage = "https://github.com/Ezio2000/jharness-python"
+Issues = "https://github.com/Ezio2000/jharness-python/issues"
+Repository = "https://github.com/Ezio2000/jharness-python.git"
+
+[tool.uv.sources]
+jharness-kernel = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jharness"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

jharness_providers-0.1.0/src/jharness/providers/__init__.py

@@ -0,0 +1,7 @@
+"""Concrete model provider adapters.
+
+Import provider-specific adapters from their provider namespace, for example
+`jharness.providers.openai`.
+"""
+
+__all__: list[str] = []

jharness_providers-0.1.0/src/jharness/providers/_http.py

@@ -0,0 +1,371 @@
+"""Shared HTTP transport primitives for provider adapters."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, cast
+
+import httpx
+
+from jharness.kernel import DeltaSink, ModelDelta, ModelError, ModelErrorInfo, ModelResponse
+
+_RETRYABLE_STATUS_CODES = frozenset({408, 409, 429, 500, 502, 503, 504})
+_CLIENT_OPTION_NAMES = frozenset({"client", "headers", "profile", "timeout"})
+
+ProfileT = TypeVar("ProfileT")
+
+PayloadFactory = Callable[[], Mapping[str, object]]
+HeadersFactory = Callable[[Mapping[str, object]], Mapping[str, str]]
+ResponseDecoder = Callable[[Mapping[str, object]], ModelResponse]
+FrameDecoder = Callable[[str | None, str], tuple[bool, Sequence[ModelDelta]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderClientConfig(Generic[ProfileT]):
+    """Validated transport configuration shared by concrete provider clients."""
+
+    base_url: str
+    api_key: str
+    model: str
+    profile: ProfileT
+    timeout: float | httpx.Timeout | None
+    headers: Mapping[str, str]
+    client: httpx.AsyncClient | None
+
+
+def provider_client_config(
+    *,
+    base_url: str,
+    api_key: str,
+    model: str,
+    options: Mapping[str, Any],
+    default_profile: ProfileT,
+    constructor_name: str,
+) -> ProviderClientConfig[ProfileT]:
+    """Normalize the common constructor surface for one provider client."""
+
+    unexpected = set(options).difference(_CLIENT_OPTION_NAMES)
+    if unexpected:
+        option = min(unexpected)
+        raise TypeError(f"{constructor_name}() got an unexpected keyword argument {option!r}")
+    if not base_url:
+        raise ValueError("base_url must not be empty")
+    if not api_key:
+        raise ValueError("api_key must not be empty")
+    if not model:
+        raise ValueError("model must not be empty")
+    profile = cast(ProfileT | None, options.get("profile")) or default_profile
+    return ProviderClientConfig(
+        base_url.rstrip("/"),
+        api_key,
+        model,
+        profile,
+        cast(float | httpx.Timeout | None, options.get("timeout")),
+        dict(cast(Mapping[str, str] | None, options.get("headers")) or {}),
+        cast(httpx.AsyncClient | None, options.get("client")),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderErrorPolicy:
+    """Provider-specific details needed by the shared transport error boundary."""
+
+    provider: str
+    codec_error: type[ValueError]
+    request_id_headers: tuple[str, ...]
+    error_code_keys: tuple[str, ...]
+    additional_retryable_status_codes: frozenset[int] = frozenset()
+    body_request_id_key: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ServerSentEvent:
+    """One decoded SSE frame."""
+
+    event: str | None
+    data: str
+
+
+async def invoke_json_model(
+    *,
+    client: httpx.AsyncClient | None,
+    timeout: float | httpx.Timeout | None,
+    url: str,
+    payload: PayloadFactory,
+    headers: HeadersFactory,
+    decode: ResponseDecoder,
+    errors: ProviderErrorPolicy,
+    response_shape_error: str,
+) -> ModelResponse:
+    """Execute one JSON model request through the shared provider error boundary."""
+
+    response: httpx.Response | None = None
+    try:
+        body = payload()
+        async with managed_async_client(client, timeout) as http:
+            response = await http.post(url, headers=headers(body), json=body)
+            await ensure_success_response(response, errors)
+            value: object = response.json()
+            if not isinstance(value, Mapping):
+                raise errors.codec_error(response_shape_error)
+            decoded = cast(Mapping[str, object], value)
+            if "error" in decoded:
+                raise ModelError(
+                    _body_error_info(
+                        decoded,
+                        errors,
+                        status_code=response.status_code,
+                        response_text="provider response error",
+                        request_id=response_request_id(response, errors.request_id_headers),
+                        metadata=response_error_metadata(response),
+                    )
+                )
+            return decode(decoded)
+    except (ModelError, httpx.HTTPError, ValueError) as exc:
+        raise _model_error(exc, response, errors) from exc
+
+
+async def invoke_sse_model(
+    *,
+    client: httpx.AsyncClient | None,
+    timeout: float | httpx.Timeout | None,
+    url: str,
+    payload: PayloadFactory,
+    headers: HeadersFactory,
+    decode_frame: FrameDecoder,
+    completed_response: Callable[[], ModelResponse],
+    emit_delta: DeltaSink | None,
+    errors: ProviderErrorPolicy,
+    incomplete_error: str,
+) -> ModelResponse:
+    """Execute one SSE model request and return its provider-assembled response."""
+
+    response: httpx.Response | None = None
+    try:
+        body = payload()
+        saw_done = False
+        async with (
+            managed_async_client(client, timeout) as http,
+            http.stream("POST", url, headers=headers(body), json=body) as response,
+        ):
+            await ensure_success_response(response, errors)
+            async for frame in iter_server_sent_events(response):
+                done, deltas = decode_frame(frame.event, frame.data)
+                if emit_delta is not None:
+                    for delta in deltas:
+                        await emit_delta(delta)
+                if done:
+                    saw_done = True
+                    break
+        if not saw_done:
+            raise errors.codec_error(incomplete_error)
+        return completed_response()
+    except (ModelError, httpx.HTTPError, ValueError) as exc:
+        raise _model_error(exc, response, errors) from exc
+
+
+@asynccontextmanager
+async def managed_async_client(
+    client: httpx.AsyncClient | None,
+    timeout: float | httpx.Timeout | None,
+) -> AsyncGenerator[httpx.AsyncClient]:
+    """Reuse an injected client or own a short-lived provider client."""
+
+    if client is not None:
+        yield client
+        return
+    async with httpx.AsyncClient(timeout=timeout) as owned_client:
+        yield owned_client
+
+
+async def ensure_success_response(
+    response: httpx.Response,
+    policy: ProviderErrorPolicy,
+) -> None:
+    """Accept only 2xx responses and preserve the complete HTTP error envelope."""
+
+    if 200 <= response.status_code < 300:
+        return
+    try:
+        _ = response.text
+    except httpx.ResponseNotRead:
+        await response.aread()
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    raise ModelError(
+        _body_error_info(
+            body,
+            policy,
+            status_code=response.status_code,
+            response_text=response.text or response.reason_phrase or "provider error",
+            request_id=response_request_id(response, policy.request_id_headers),
+            metadata=response_error_metadata(response),
+        )
+    )
+
+
+async def iter_server_sent_events(response: httpx.Response) -> AsyncIterator[ServerSentEvent]:
+    """Parse an HTTP response body into SSE frames according to field boundaries."""
+
+    event_name: str | None = None
+    data_lines: list[str] = []
+    async for line in response.aiter_lines():
+        if line == "":
+            if data_lines:
+                yield ServerSentEvent(event=event_name, data="\n".join(data_lines))
+            event_name = None
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, separator, raw_value = line.partition(":")
+        if not separator:
+            raw_value = ""
+        value = raw_value[1:] if raw_value.startswith(" ") else raw_value
+        if field == "event":
+            event_name = value
+        elif field == "data":
+            data_lines.append(value)
+    if data_lines:
+        yield ServerSentEvent(event=event_name, data="\n".join(data_lines))
+
+
+def response_error_metadata(response: httpx.Response) -> dict[str, str]:
+    """Return portable HTTP context that is useful beyond provider error bodies."""
+
+    location = response.headers.get("location")
+    return {} if not location else {"location": location}
+
+
+def response_request_id(
+    response: httpx.Response,
+    header_names: Sequence[str],
+) -> str | None:
+    """Return the first non-empty request identifier from provider header names."""
+
+    for header_name in header_names:
+        request_id = response.headers.get(header_name)
+        if request_id:
+            return request_id
+    return None
+
+
+def stream_body_error(
+    body: Mapping[str, object],
+    policy: ProviderErrorPolicy,
+) -> ModelError:
+    """Build the standard model error for an error carried by an SSE payload."""
+
+    return ModelError(
+        _body_error_info(
+            body,
+            policy,
+            status_code=None,
+            response_text="provider stream error",
+            request_id=None,
+        )
+    )
+
+
+def decode_json_object(
+    data: str,
+    error: type[ValueError],
+    error_message: str,
+) -> Mapping[str, object]:
+    parsed: object = json.loads(data)
+    if not isinstance(parsed, Mapping):
+        raise error(error_message)
+    return cast(Mapping[str, object], parsed)
+
+
+def _model_error(
+    exc: Exception,
+    response: httpx.Response | None,
+    policy: ProviderErrorPolicy,
+) -> ModelError:
+    if isinstance(exc, ModelError):
+        info = exc.info
+    else:
+        if isinstance(exc, httpx.TimeoutException):
+            code, retryable = "timeout", True
+        elif isinstance(exc, httpx.NetworkError | httpx.RemoteProtocolError | httpx.ProxyError):
+            code, retryable = exc.__class__.__name__, True
+        elif isinstance(exc, httpx.HTTPError):
+            code, retryable = exc.__class__.__name__, False
+        elif isinstance(exc, policy.codec_error):
+            code, retryable = "codec_error", False
+        elif isinstance(exc, json.JSONDecodeError):
+            code, retryable = "invalid_json", False
+        else:
+            code, retryable = exc.__class__.__name__, False
+        info = ModelErrorInfo(
+            message=str(exc) or exc.__class__.__name__,
+            provider=policy.provider,
+            code=code,
+            retryable=retryable,
+        )
+    if response is not None:
+        metadata = dict(info.metadata)
+        metadata.update(response_error_metadata(response))
+        info = ModelErrorInfo(
+            message=info.message,
+            provider=info.provider,
+            code=info.code,
+            status_code=response.status_code,
+            retryable=info.retryable,
+            request_id=(
+                response_request_id(response, policy.request_id_headers) or info.request_id
+            ),
+            metadata=metadata,
+        )
+    return ModelError(info)
+
+
+def _body_error_info(
+    error_body: object,
+    policy: ProviderErrorPolicy,
+    *,
+    status_code: int | None,
+    response_text: str,
+    request_id: str | None,
+    metadata: Mapping[str, object] | None = None,
+) -> ModelErrorInfo:
+    message = response_text
+    code: str | None = None
+    body_request_id: str | None = None
+    if isinstance(error_body, Mapping):
+        error_mapping = cast(Mapping[str, object], error_body)
+        if policy.body_request_id_key is not None:
+            raw_request_id = error_mapping.get(policy.body_request_id_key)
+            if isinstance(raw_request_id, str) and raw_request_id:
+                body_request_id = raw_request_id
+        error_value = error_mapping.get("error")
+        if isinstance(error_value, Mapping):
+            nested = cast(Mapping[str, object], error_value)
+            raw_message = nested.get("message")
+            if isinstance(raw_message, str) and raw_message:
+                message = raw_message
+            for key in policy.error_code_keys:
+                item = nested.get(key)
+                if isinstance(item, str) and item:
+                    code = item
+                    break
+        elif isinstance(error_value, str) and error_value:
+            message = error_value
+    return ModelErrorInfo(
+        message=message,
+        provider=policy.provider,
+        code=code or "provider_error",
+        status_code=status_code,
+        retryable=(
+            status_code in _RETRYABLE_STATUS_CODES
+            or status_code in policy.additional_retryable_status_codes
+        ),
+        request_id=request_id or body_request_id,
+        metadata={} if metadata is None else metadata,
+    )

jharness_providers-0.1.0/src/jharness/providers/_json.py

@@ -0,0 +1,43 @@
+"""Small scalar guards shared by provider wire codecs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, NoReturn, cast
+
+
+@dataclass(frozen=True, slots=True)
+class JsonValues:
+    """Validate common JSON scalar shapes with a provider-local error type."""
+
+    error_type: type[ValueError]
+
+    def mapping(self, value: object, label: str) -> Mapping[str, Any]:
+        if not isinstance(value, Mapping):
+            self._raise(f"{label} must be an object")
+        return cast(Mapping[str, Any], value)
+
+    def required_string(self, value: object, label: str) -> str:
+        if not isinstance(value, str):
+            self._raise(f"{label} must be a string")
+        if not value:
+            self._raise(f"{label} must not be empty")
+        return value
+
+    def optional_string(self, value: object) -> str | None:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            self._raise("expected string or null")
+        return value
+
+    def optional_integer(self, value: object) -> int | None:
+        if value is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, int):
+            self._raise("expected integer or null")
+        return value
+
+    def _raise(self, message: str) -> NoReturn:
+        raise self.error_type(message)

jharness_providers-0.1.0/src/jharness/providers/_profiles.py

@@ -0,0 +1,42 @@
+"""Small validation vocabulary shared by provider profile values."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any, cast
+
+
+def required_string(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def copy_json_mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{label} must be a mapping")
+    result: dict[str, Any] = {}
+    for key, item in cast(Mapping[object, object], value).items():
+        if not isinstance(key, str) or not key:
+            raise ValueError(f"{label} keys must be non-empty strings")
+        result[key] = deepcopy(item)
+    return result
+
+
+def copy_string_mapping(
+    value: object,
+    label: str,
+    *,
+    entry_description: str = "non-empty strings",
+) -> dict[str, str]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{label} must be a mapping")
+    result: dict[str, str] = {}
+    for key, item in cast(Mapping[object, object], value).items():
+        if not isinstance(key, str) or not key:
+            raise ValueError(f"{label} keys must be {entry_description}")
+        if not isinstance(item, str) or not item:
+            raise ValueError(f"{label} values must be {entry_description}")
+        result[key] = item
+    return result