llm: spec v0.8 llm-provider (proposal 0006) — phase 4 (#17)

* llm: spec v0.8 llm-provider (proposal 0006) — phase 4

Land the stateless LLM provider abstraction. Adds `openarmature.llm`
with the typed Message/Tool/Response surface, the seven §7 error
categories, list-level boundary validation, and an OpenAI-compatible
HTTPX provider that talks to the OpenAI hosted API plus local servers
(vLLM, LM Studio, llama.cpp).

The canonical TRANSIENT_CATEGORIES set moves into llm.errors so retry
middleware imports it from a single source of truth — Phase 2
hardcoded the same set ahead of llm-provider landing.

Test coverage: 8 spec conformance fixtures (drives the real provider
through httpx.MockTransport so wire-mapping is exercised end-to-end)
plus 46 unit tests covering per-role validation, tool-call id
verbatim preservation, error category contracts, and the
HTTP-status-to-category mapping table.

* llm: enforce Usage non-negative constraint per spec §6

Spec §6 documents `Usage` token counts as non-negative integers, but
the fields were plain `int | None` and silently accepted negatives.
Add `Field(ge=0)` so a malformed wire response surfaces as
`provider_invalid_response` (the `_parse_response` Usage build wraps
the resulting `ValidationError`, matching the existing
`AssistantMessage` pattern).

* llm: document why validate_message_list skips role alternation

Future readers (and users hitting vLLM-Mistral 400s) need a pointer to
where the role-alternation constraint lives. Strict templates enforce
user→assistant alternation server-side; OpenAI and Anthropic don't.
Pre-rejecting at the client boundary would over-restrict the
permissive case.

* llm: group providers under llm/providers/ subpackage

Mirrors the openarmature.graph.middleware shape so the package layout
signals where future providers (Anthropic, Bedrock, gateway-shaped)
will live. Public surface is unchanged — `from openarmature.llm import
OpenAIProvider` still works via the package-root re-export.

* llm: clarify transient-set count and legacy finish_reason mapping

Two doc-only cleanups from PR #17 review:

- errors.py: TRANSIENT_CATEGORIES has three entries, not four —
  comment was off by one.
- providers/openai.py: tighten the comment on the
  `finish_reason: "function_call"` → `"tool_calls"` rename so it's
  clear this is a value rename (per spec §8.2 / conformance fixture
  005), not a message-field transformation. We do not translate the
  deprecated single `message.function_call` shape — none of the
  backends we currently target emit it.

Author: chris-colinsky

pyproject.toml

@@ -13,6 +13,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 dependencies = [
     "pydantic>=2.7",
+    "httpx>=0.27",
 ]
 
 [project.urls]

src/openarmature/graph/middleware/retry.py

@@ -20,20 +20,13 @@
 from collections.abc import Awaitable, Callable, Mapping
 from typing import Any
 
+from openarmature.llm.errors import TRANSIENT_CATEGORIES
+
 from ._core import NextCall
 
-# Default transient set per pipeline-utilities §6.1: matches against an
-# exception's ``category`` attribute (or the cause's, if the exception is
-# a NodeException wrapper). The canonical strings are spec-defined and
-# loose-coupled to llm-provider §7 — implementers don't have to import
-# the llm-provider module to wire up retry.
-TRANSIENT_CATEGORIES: frozenset[str] = frozenset(
-    {
-        "provider_rate_limit",
-        "provider_unavailable",
-        "provider_model_not_loaded",
-    }
-)
+# ``TRANSIENT_CATEGORIES`` is re-exported via this module's __all__
+# below. Canonical source of truth lives in ``openarmature.llm.errors``
+# (per llm-provider §7) — the retry middleware is just a consumer.
 
 
 def default_classifier(exc: Exception, _state: Any) -> bool:

src/openarmature/llm/__init__.py

@@ -0,0 +1,85 @@
+"""openarmature.llm — llm-provider capability per spec proposal 0006.
+
+Public surface: typed ``Message`` / ``Tool`` / ``Response``, the
+``Provider`` Protocol, the canonical error categories, and an
+OpenAI-compatible provider. Users write::
+
+    from openarmature.llm import (
+        AssistantMessage,
+        OpenAIProvider,
+        Provider,
+        SystemMessage,
+        Tool,
+        ToolCall,
+        UserMessage,
+    )
+
+All seven §7 error categories and the canonical ``TRANSIENT_CATEGORIES``
+frozenset are also re-exported here so callers writing custom retry
+classifiers don't have to reach into ``openarmature.llm.errors``.
+"""
+
+from .errors import (
+    PROVIDER_AUTHENTICATION,
+    PROVIDER_INVALID_MODEL,
+    PROVIDER_INVALID_REQUEST,
+    PROVIDER_INVALID_RESPONSE,
+    PROVIDER_MODEL_NOT_LOADED,
+    PROVIDER_RATE_LIMIT,
+    PROVIDER_UNAVAILABLE,
+    TRANSIENT_CATEGORIES,
+    LlmProviderError,
+    ProviderAuthentication,
+    ProviderInvalidModel,
+    ProviderInvalidRequest,
+    ProviderInvalidResponse,
+    ProviderModelNotLoaded,
+    ProviderRateLimit,
+    ProviderUnavailable,
+)
+from .messages import (
+    AssistantMessage,
+    Message,
+    SystemMessage,
+    Tool,
+    ToolCall,
+    ToolMessage,
+    UserMessage,
+)
+from .provider import Provider, validate_message_list, validate_tools
+from .providers import OpenAIProvider
+from .response import FinishReason, Response, RuntimeConfig, Usage
+
+__all__ = [
+    "PROVIDER_AUTHENTICATION",
+    "PROVIDER_INVALID_MODEL",
+    "PROVIDER_INVALID_REQUEST",
+    "PROVIDER_INVALID_RESPONSE",
+    "PROVIDER_MODEL_NOT_LOADED",
+    "PROVIDER_RATE_LIMIT",
+    "PROVIDER_UNAVAILABLE",
+    "TRANSIENT_CATEGORIES",
+    "AssistantMessage",
+    "FinishReason",
+    "LlmProviderError",
+    "Message",
+    "OpenAIProvider",
+    "Provider",
+    "ProviderAuthentication",
+    "ProviderInvalidModel",
+    "ProviderInvalidRequest",
+    "ProviderInvalidResponse",
+    "ProviderModelNotLoaded",
+    "ProviderRateLimit",
+    "ProviderUnavailable",
+    "Response",
+    "RuntimeConfig",
+    "SystemMessage",
+    "Tool",
+    "ToolCall",
+    "ToolMessage",
+    "Usage",
+    "UserMessage",
+    "validate_message_list",
+    "validate_tools",
+]

src/openarmature/llm/errors.py

@@ -0,0 +1,149 @@
+"""Errors raised by an llm-provider implementation.
+
+Per spec llm-provider §7: a provider call (``ready()`` or
+``complete()``) MAY raise one of seven canonical category errors.
+Each error class carries a ``category`` class attribute matching the
+canonical string identifier so callers can dispatch on the category
+without matching exception types directly.
+
+This module is also the single source of truth for the canonical
+category strings — :data:`TRANSIENT_CATEGORIES` lives here, and
+``openarmature.graph.middleware.retry``'s default classifier imports
+it. Phase 2's retry middleware deliberately hardcoded the set to
+avoid a circular dependency before llm-provider was implemented;
+now that this module exists, the strings have a real home.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Canonical category strings (spec §7)
+# ---------------------------------------------------------------------------
+
+PROVIDER_AUTHENTICATION = "provider_authentication"
+PROVIDER_UNAVAILABLE = "provider_unavailable"
+PROVIDER_INVALID_MODEL = "provider_invalid_model"
+PROVIDER_MODEL_NOT_LOADED = "provider_model_not_loaded"
+PROVIDER_RATE_LIMIT = "provider_rate_limit"
+PROVIDER_INVALID_RESPONSE = "provider_invalid_response"
+PROVIDER_INVALID_REQUEST = "provider_invalid_request"
+
+
+# Per spec §7 "Retry classification": these three categories are
+# *transient* — a retry MAY succeed. The other four
+# (`provider_authentication`, `provider_invalid_model`,
+# `provider_invalid_request`, `provider_invalid_response`) are
+# non-transient and MUST NOT be retried by the default classifier.
+#
+# Note: ``finish_reason: "error"`` is also transient per spec §7, but
+# that's a Response-level signal rather than an exception category, so
+# it isn't part of this set — the default retry middleware operates on
+# raised exceptions.
+TRANSIENT_CATEGORIES: frozenset[str] = frozenset(
+    {
+        PROVIDER_RATE_LIMIT,
+        PROVIDER_UNAVAILABLE,
+        PROVIDER_MODEL_NOT_LOADED,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Exception classes
+# ---------------------------------------------------------------------------
+
+
+class LlmProviderError(Exception):
+    """Base for all llm-provider errors. Each subclass carries a
+    ``category`` class attribute matching one of the spec §7 strings.
+
+    Provider-originated errors SHOULD preserve the underlying provider
+    exception as ``__cause__`` so callers can reach the wire-level
+    detail when needed.
+    """
+
+    category: str
+
+
+class ProviderAuthentication(LlmProviderError):
+    """Auth failed — invalid key, expired token, missing credentials."""
+
+    category = PROVIDER_AUTHENTICATION
+
+
+class ProviderUnavailable(LlmProviderError):
+    """Provider is unreachable — network failure, 5xx error, DNS, timeout."""
+
+    category = PROVIDER_UNAVAILABLE
+
+
+class ProviderInvalidModel(LlmProviderError):
+    """The bound model does not exist on this provider. Terminal —
+    retry will not succeed without changing the bound model."""
+
+    category = PROVIDER_INVALID_MODEL
+
+
+class ProviderModelNotLoaded(LlmProviderError):
+    """The bound model is known to the provider but is not currently
+    serving (e.g., a local vLLM/LM Studio/llama.cpp server has the
+    model configured but not loaded). Distinct from
+    ``provider_invalid_model`` because retry MAY succeed once loading
+    completes."""
+
+    category = PROVIDER_MODEL_NOT_LOADED
+
+
+class ProviderRateLimit(LlmProviderError):
+    """Provider returned a rate-limit response (HTTP 429 or equivalent).
+
+    When the provider supplies a ``Retry-After`` header (or its
+    equivalent), the parsed seconds-to-wait surfaces on
+    :attr:`retry_after`. ``None`` if the provider didn't include one.
+    """
+
+    category = PROVIDER_RATE_LIMIT
+    retry_after: float | None
+
+    def __init__(self, *args: Any, retry_after: float | None = None) -> None:
+        super().__init__(*args)
+        self.retry_after = retry_after
+
+
+class ProviderInvalidResponse(LlmProviderError):
+    """Provider returned a malformed response that cannot be parsed
+    into the §6 shape (missing required fields, invalid tool_calls
+    structure, invalid JSON)."""
+
+    category = PROVIDER_INVALID_RESPONSE
+
+
+class ProviderInvalidRequest(LlmProviderError):
+    """The request was malformed before sending (per-role message
+    constraints violated, ``tool_call_id`` does not match an earlier
+    assistant tool call, duplicate tool names, etc.). Raised by the
+    implementation's pre-send validation, not by the provider."""
+
+    category = PROVIDER_INVALID_REQUEST
+
+
+__all__ = [
+    "PROVIDER_AUTHENTICATION",
+    "PROVIDER_INVALID_MODEL",
+    "PROVIDER_INVALID_REQUEST",
+    "PROVIDER_INVALID_RESPONSE",
+    "PROVIDER_MODEL_NOT_LOADED",
+    "PROVIDER_RATE_LIMIT",
+    "PROVIDER_UNAVAILABLE",
+    "TRANSIENT_CATEGORIES",
+    "LlmProviderError",
+    "ProviderAuthentication",
+    "ProviderInvalidModel",
+    "ProviderInvalidRequest",
+    "ProviderInvalidResponse",
+    "ProviderModelNotLoaded",
+    "ProviderRateLimit",
+    "ProviderUnavailable",
+]