apl-sidecar 0.1.0__py3-none-any.whl

adapters/base.py

@@ -0,0 +1,37 @@
+"""Provider adapter contract shared by offline and future network providers."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class ProviderCapabilities:
+    network: bool
+    streaming: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderRequest:
+    prompt: str
+    model: str
+    fixture_dir: Path | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProviderResponse:
+    text: str
+    provider_id: str
+    model: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class ProviderAdapter(Protocol):
+    provider_id: str
+    capabilities: ProviderCapabilities
+
+    def complete(self, request: ProviderRequest) -> ProviderResponse: ...
+

adapters/byok/_http.py

@@ -0,0 +1,66 @@
+"""Minimal JSON POST transport for BYOK adapters. Stdlib only, fail-close.
+
+Design rules (mirrors the receipt philosophy: evidence over trust):
+- hard timeout and response size cap — a hung or oversized response is a failure;
+- secrets passed by the caller are scrubbed from every raised message, so an
+  API key can never leak through a traceback, log line, or receipt;
+- no retries — a live call either happened once or it did not, which keeps
+  provider_events honest.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_TIMEOUT_S = 60.0
+MAX_RESPONSE_BYTES = 2 * 1024 * 1024  # 2 MiB
+
+
+class ByokConfigError(ValueError):
+    """Adapter is not configured correctly (missing key, model, or URL)."""
+
+
+class TransportError(RuntimeError):
+    """Network call failed. Message is always secret-scrubbed."""
+
+
+def _scrub(message: str, secrets: tuple[str, ...]) -> str:
+    for secret in secrets:
+        if secret:
+            message = message.replace(secret, "[redacted]")
+    return message
+
+
+def post_json(url: str, headers: dict[str, str], body: dict[str, Any],
+              timeout: float = DEFAULT_TIMEOUT_S,
+              max_bytes: int = MAX_RESPONSE_BYTES,
+              secrets: tuple[str, ...] = ()) -> dict[str, Any]:
+    """POST a JSON body, return the parsed JSON response. Raises TransportError."""
+    data = json.dumps(body).encode("utf-8")
+    request = urllib.request.Request(
+        url, data=data, method="POST",
+        headers={**headers, "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read(max_bytes + 1)
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = exc.read(500).decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001 — never let error reporting raise
+            pass
+        raise TransportError(_scrub(
+            f"provider returned HTTP {exc.code}: {detail}".strip(), secrets)) from None
+    except Exception as exc:  # URLError, timeout, ConnectionError, ...
+        raise TransportError(_scrub(f"request failed: {exc}", secrets)) from None
+    if len(raw) > max_bytes:
+        raise TransportError(f"response exceeded {max_bytes} bytes")
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise TransportError(_scrub(f"response is not valid JSON: {exc}", secrets)) from None
+    if not isinstance(parsed, dict):
+        raise TransportError("response JSON is not an object")
+    return parsed

adapters/byok/anthropic_provider.py

@@ -0,0 +1,104 @@
+"""BYOK adapter: Anthropic Messages API. Network, your key, off by default.
+
+Configuration is environment-only — a key never appears on a command line
+(shell history) or in a config file (accidental commit):
+
+    ANTHROPIC_API_KEY          required
+    APL_ANTHROPIC_MODEL        optional, default claude-sonnet-4-6
+    APL_ANTHROPIC_MODEL_A/_B   optional per-seat override
+    APL_ANTHROPIC_BASE_URL     optional, default https://api.anthropic.com
+                               (corporate gateways / test harnesses)
+    APL_ANTHROPIC_MAX_TOKENS   optional, default 1024
+
+The adapter sends exactly one user message containing the approved provider
+payload — no system prompt, no metadata, temperature 0. What is sent is what
+the receipt hashes.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from ..base import ProviderCapabilities, ProviderRequest, ProviderResponse
+from . import _http
+from ._http import ByokConfigError
+
+ANTHROPIC_VERSION = "2023-06-01"
+DEFAULT_BASE_URL = "https://api.anthropic.com"
+DEFAULT_MODEL = "claude-sonnet-4-6"
+
+Transport = Callable[..., dict[str, Any]]
+
+
+def _seat_env(name: str, seat: str | None) -> str | None:
+    if seat:
+        value = os.environ.get(f"{name}_{seat.upper()}")
+        if value:
+            return value
+    return os.environ.get(name)
+
+
+@dataclass(frozen=True)
+class AnthropicAdapter:
+    api_key: str
+    model: str = DEFAULT_MODEL
+    base_url: str = DEFAULT_BASE_URL
+    max_tokens: int = 1024
+    timeout: float = _http.DEFAULT_TIMEOUT_S
+    provider_id: str = "byok_anthropic"
+    capabilities: ProviderCapabilities = ProviderCapabilities(network=True)
+    transport: Transport = field(default=_http.post_json, repr=False)
+
+    @classmethod
+    def from_env(cls, seat: str | None = None, provider_id: str | None = None,
+                 transport: Transport | None = None) -> "AnthropicAdapter":
+        api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        if not api_key:
+            raise ByokConfigError("ANTHROPIC_API_KEY is not set")
+        return cls(
+            api_key=api_key,
+            model=_seat_env("APL_ANTHROPIC_MODEL", seat) or DEFAULT_MODEL,
+            base_url=os.environ.get("APL_ANTHROPIC_BASE_URL", DEFAULT_BASE_URL).rstrip("/"),
+            max_tokens=int(os.environ.get("APL_ANTHROPIC_MAX_TOKENS", "1024")),
+            provider_id=provider_id or "byok_anthropic",
+            transport=transport or _http.post_json)
+
+    @property
+    def endpoint(self) -> str:
+        return f"{self.base_url}/v1/messages"
+
+    @property
+    def endpoint_host(self) -> str:
+        return urlparse(self.base_url).hostname or self.base_url
+
+    def complete(self, request: ProviderRequest) -> ProviderResponse:
+        body = {"model": request.model or self.model,
+                "max_tokens": self.max_tokens,
+                "temperature": 0,
+                "messages": [{"role": "user", "content": request.prompt}]}
+        headers = {"x-api-key": self.api_key, "anthropic-version": ANTHROPIC_VERSION}
+        data = self.transport(self.endpoint, headers, body,
+                              timeout=self.timeout, secrets=(self.api_key,))
+        blocks = data.get("content")
+        if not isinstance(blocks, list):
+            raise _http.TransportError("anthropic response missing content blocks")
+        text = "\n".join(b.get("text", "") for b in blocks
+                         if isinstance(b, dict) and b.get("type") == "text")
+        stop_reason = data.get("stop_reason")
+        # Tri-state honesty: only known-complete stop reasons count as
+        # complete; anything unexpected is "unknown", never silently complete.
+        if stop_reason == "max_tokens":
+            completion = "truncated"
+        elif stop_reason in ("end_turn", "stop_sequence"):
+            completion = "complete"
+        else:
+            completion = "unknown"
+        return ProviderResponse(
+            text=text, provider_id=self.provider_id, model=body["model"],
+            metadata={"stop_reason": stop_reason,
+                      "completion": completion,
+                      "truncated": completion == "truncated",
+                      "usage": data.get("usage"),
+                      "endpoint_host": self.endpoint_host})

adapters/byok/openai_provider.py

@@ -0,0 +1,116 @@
+"""BYOK adapter: any OpenAI-compatible /v1/chat/completions endpoint.
+
+This one seat covers three deployments with the same code path:
+- OpenAI (or another hosted OpenAI-compatible vendor);
+- a local model server (vLLM, Ollama, llama.cpp) on loopback — the
+  customer-controlled "local seat" the enterprise docs describe;
+- the repo's own offline mock proxy (`apl proxy`), which turns the entire
+  live pipeline into an offline end-to-end rehearsal.
+
+Configuration is environment-only:
+
+    OPENAI_API_KEY           required, EXCEPT when the endpoint is loopback
+    APL_OPENAI_BASE_URL      optional, default https://api.openai.com/v1
+    APL_OPENAI_BASE_URL_A/_B optional per-seat override
+    APL_OPENAI_MODEL         required (no default — "OpenAI-compatible"
+                             does not imply any particular model exists)
+    APL_OPENAI_MODEL_A/_B    optional per-seat override
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from ..base import ProviderCapabilities, ProviderRequest, ProviderResponse
+from . import _http
+from ._http import ByokConfigError
+
+DEFAULT_BASE_URL = "https://api.openai.com/v1"
+_LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+Transport = Callable[..., dict[str, Any]]
+
+
+def _seat_env(name: str, seat: str | None) -> str | None:
+    if seat:
+        value = os.environ.get(f"{name}_{seat.upper()}")
+        if value:
+            return value
+    return os.environ.get(name)
+
+
+def is_loopback(base_url: str) -> bool:
+    return (urlparse(base_url).hostname or "") in _LOOPBACK_HOSTS
+
+
+@dataclass(frozen=True)
+class OpenAICompatAdapter:
+    model: str
+    api_key: str = ""
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = _http.DEFAULT_TIMEOUT_S
+    provider_id: str = "byok_openai"
+    capabilities: ProviderCapabilities = ProviderCapabilities(network=True)
+    transport: Transport = field(default=_http.post_json, repr=False)
+
+    @classmethod
+    def from_env(cls, seat: str | None = None, provider_id: str | None = None,
+                 transport: Transport | None = None) -> "OpenAICompatAdapter":
+        base_url = (_seat_env("APL_OPENAI_BASE_URL", seat) or DEFAULT_BASE_URL).rstrip("/")
+        api_key = os.environ.get("OPENAI_API_KEY", "")
+        if not api_key and not is_loopback(base_url):
+            raise ByokConfigError(
+                "OPENAI_API_KEY is not set and the endpoint is not loopback")
+        model = _seat_env("APL_OPENAI_MODEL", seat)
+        if not model:
+            raise ByokConfigError("APL_OPENAI_MODEL is not set")
+        return cls(model=model, api_key=api_key, base_url=base_url,
+                   provider_id=provider_id or "byok_openai",
+                   transport=transport or _http.post_json)
+
+    @property
+    def endpoint(self) -> str:
+        return f"{self.base_url}/v1/chat/completions" \
+            if not self.base_url.endswith("/v1") else f"{self.base_url}/chat/completions"
+
+    @property
+    def endpoint_host(self) -> str:
+        return urlparse(self.base_url).hostname or self.base_url
+
+    def complete(self, request: ProviderRequest) -> ProviderResponse:
+        body = {"model": request.model or self.model,
+                "temperature": 0,
+                "stream": False,
+                "messages": [{"role": "user", "content": request.prompt}]}
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = self.transport(self.endpoint, headers, body,
+                              timeout=self.timeout, secrets=(self.api_key,))
+        choices = data.get("choices")
+        if not isinstance(choices, list) or not choices:
+            raise _http.TransportError("openai-compatible response missing choices")
+        message = choices[0].get("message") if isinstance(choices[0], dict) else None
+        text = message.get("content") if isinstance(message, dict) else None
+        if not isinstance(text, str):
+            raise _http.TransportError("openai-compatible response missing message content")
+        finish_reason = choices[0].get("finish_reason")
+        # Tri-state honesty: absence of "length" is NOT proof of completeness.
+        # vLLM/Ollama/llama.cpp variants return null or vendor-specific reasons
+        # for silently capped output — those must surface as "unknown", never
+        # masquerade as complete.
+        if finish_reason == "length":
+            completion = "truncated"
+        elif finish_reason == "stop":
+            completion = "complete"
+        else:
+            completion = "unknown"
+        return ProviderResponse(
+            text=text, provider_id=self.provider_id, model=body["model"],
+            metadata={"finish_reason": finish_reason,
+                      "completion": completion,
+                      "truncated": completion == "truncated",
+                      "usage": data.get("usage"),
+                      "endpoint_host": self.endpoint_host})

adapters/local_stub/provider.py

@@ -0,0 +1,16 @@
+"""Local stub — deterministic placeholder for local-model execution.
+
+In enterprise deployments this seat is taken by a customer-controlled local
+model endpoint. In P0 it simply echoes a deterministic marker so flows that
+route a fragment to "local" have a well-defined, offline behavior.
+"""
+from __future__ import annotations
+
+import hashlib
+
+PROVIDER_ID = "local_stub"
+
+
+def respond(prompt_text: str) -> str:
+    digest = hashlib.sha256(prompt_text.encode("utf-8")).hexdigest()[:12]
+    return f"[local-stub] processed locally ({digest})"

adapters/mock.py

@@ -0,0 +1,30 @@
+"""Explicit, fixture-backed offline provider adapters."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import ProviderCapabilities, ProviderRequest, ProviderResponse
+
+
+@dataclass(frozen=True)
+class MockProviderAdapter:
+    provider_id: str
+    fixture_name: str
+    model: str
+    capabilities: ProviderCapabilities = ProviderCapabilities(network=False)
+
+    def complete(self, request: ProviderRequest) -> ProviderResponse:
+        if request.fixture_dir is None:
+            text = f"Offline mock completion from {self.provider_id}."
+        else:
+            text = (request.fixture_dir / self.fixture_name).read_text(encoding="utf-8")
+        return ProviderResponse(text=text, provider_id=self.provider_id, model=request.model)
+
+
+def default_registry():
+    from .registry import ProviderRegistry
+
+    registry = ProviderRegistry()
+    registry.register(MockProviderAdapter("mock_provider_a", "mock_answer_a.txt", "apl-mock-a"))
+    registry.register(MockProviderAdapter("mock_provider_b", "mock_answer_b.txt", "apl-mock-b"))
+    return registry

adapters/mock_provider_a/provider.py

@@ -0,0 +1,11 @@
+"""Mock provider A — offline fixture-backed. Never touches the network."""
+from __future__ import annotations
+
+from pathlib import Path
+
+PROVIDER_ID = "mock_provider_a"
+
+
+def respond(example_dir: Path | str) -> str:
+    """Return the curated mock answer for this example. Zero network."""
+    return (Path(example_dir) / "mock_answer_a.txt").read_text(encoding="utf-8")

adapters/mock_provider_b/provider.py

@@ -0,0 +1,11 @@
+"""Mock provider B — offline fixture-backed. Never touches the network."""
+from __future__ import annotations
+
+from pathlib import Path
+
+PROVIDER_ID = "mock_provider_b"
+
+
+def respond(example_dir: Path | str) -> str:
+    """Return the curated mock answer for this example. Zero network."""
+    return (Path(example_dir) / "mock_answer_b.txt").read_text(encoding="utf-8")

adapters/registry.py

@@ -0,0 +1,27 @@
+"""Explicit provider registry; importing this module never discovers plugins."""
+from __future__ import annotations
+
+from .base import ProviderAdapter
+
+
+class ProviderRegistry:
+    def __init__(self) -> None:
+        self._adapters: dict[str, ProviderAdapter] = {}
+
+    def register(self, adapter: ProviderAdapter) -> None:
+        provider_id = adapter.provider_id
+        if not provider_id:
+            raise ValueError("provider_id must not be empty")
+        if provider_id in self._adapters:
+            raise ValueError(f"provider already registered: {provider_id}")
+        self._adapters[provider_id] = adapter
+
+    def get(self, provider_id: str) -> ProviderAdapter:
+        try:
+            return self._adapters[provider_id]
+        except KeyError as exc:
+            raise KeyError(f"unknown provider: {provider_id}") from exc
+
+    def ids(self) -> tuple[str, ...]:
+        return tuple(self._adapters)
+