agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/backends/llm/base.py

@@ -0,0 +1,149 @@
+"""Backend-neutral language-model request and response contracts."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from agentinputlab.contracts.enums import StrEnum
+from agentinputlab.contracts.errors import CapabilityError, ValidationError
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+from agentinputlab.contracts.state import Message
+
+
+def _is_finite_nonnegative_number(value: Any) -> bool:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return False
+    try:
+        return math.isfinite(value) and value >= 0
+    except (OverflowError, TypeError, ValueError):
+        return False
+
+
+class ModelCapability(StrEnum):
+    CHAT = "chat"
+    COMPLETION = "completion"
+    JSON_OBJECT = "json_object"
+    JSON_SCHEMA = "json_schema"
+    TOOL_CALLING = "tool_calling"
+    LOGPROBS = "logprobs"
+    SEED = "seed"
+    STREAMING = "streaming"
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationRequest:
+    prompt: str = ""
+    messages: tuple[Message, ...] = ()
+    system: str = ""
+    temperature: float = 0.0
+    max_tokens: int = 512
+    seed: int | None = None
+    stop: tuple[str, ...] = ()
+    logprobs: bool = False
+    top_logprobs: int | None = None
+    response_format: Mapping[str, Any] | None = None
+    tools: tuple[Mapping[str, Any], ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        messages = tuple(self.messages)
+        stop = tuple(self.stop)
+        if not all(isinstance(message, Message) for message in messages):
+            raise ValidationError("generation messages must be Message instances")
+        if not all(isinstance(item, str) for item in stop):
+            raise ValidationError("generation stop entries must be strings")
+        if not isinstance(self.logprobs, bool):
+            raise ValidationError("logprobs must be boolean")
+        if self.top_logprobs is not None and (
+            isinstance(self.top_logprobs, bool)
+            or not isinstance(self.top_logprobs, int)
+            or not 1 <= self.top_logprobs <= 20
+        ):
+            raise ValidationError("top_logprobs must be an integer from 1 to 20 or None")
+        if self.top_logprobs is not None and not self.logprobs:
+            raise ValidationError("top_logprobs requires logprobs=True")
+        object.__setattr__(self, "messages", messages)
+        object.__setattr__(self, "stop", stop)
+        object.__setattr__(
+            self,
+            "tools",
+            tuple(freeze_mapping(tool) for tool in self.tools),
+        )
+        if self.response_format is not None:
+            object.__setattr__(
+                self,
+                "response_format",
+                freeze_mapping(self.response_format),
+            )
+        object.__setattr__(self, "metadata", freeze_mapping(self.metadata))
+        if not self.prompt and not self.messages:
+            raise ValidationError("generation request requires prompt or messages")
+        if (
+            isinstance(self.max_tokens, bool)
+            or not isinstance(self.max_tokens, int)
+            or self.max_tokens < 1
+        ):
+            raise ValidationError("max_tokens must be positive")
+        if not _is_finite_nonnegative_number(self.temperature):
+            raise ValidationError("temperature must be finite and non-negative")
+        if self.seed is not None and (
+            isinstance(self.seed, bool) or not isinstance(self.seed, int) or self.seed < 0
+        ):
+            raise ValidationError("seed must be a non-negative integer or None")
+
+    @property
+    def request_hash(self) -> str:
+        return content_hash(self)
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float | None = None
+
+    def __post_init__(self) -> None:
+        if any(
+            isinstance(value, bool) or not isinstance(value, int) or value < 0
+            for value in (self.input_tokens, self.output_tokens)
+        ):
+            raise ValidationError("usage token counts must be non-negative integers")
+        if self.cost_usd is not None and not _is_finite_nonnegative_number(self.cost_usd):
+            raise ValidationError("usage cost_usd must be finite and non-negative or None")
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationResponse:
+    text: str
+    model: str = ""
+    finish_reason: str = ""
+    usage: Usage = field(default_factory=Usage)
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "raw", freeze_mapping(self.raw))
+
+
+@runtime_checkable
+class LLMBackend(Protocol):
+    model_id: str
+    capabilities: frozenset[ModelCapability]
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        """Generate one response or raise a typed backend error."""
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        """Return serializable identity fields used by balance audits."""
+
+
+def require_capabilities(
+    backend: LLMBackend,
+    required: set[ModelCapability] | frozenset[ModelCapability],
+) -> None:
+    missing = set(required) - set(backend.capabilities)
+    if missing:
+        names = ", ".join(sorted(item.value for item in missing))
+        raise CapabilityError(f"backend {backend.model_id!r} lacks capabilities: {names}")

agentinputlab/backends/llm/callable.py

@@ -0,0 +1,108 @@
+"""Dependency-free callable and deterministic replay backends."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import content_hash
+
+from .base import (
+    GenerationRequest,
+    GenerationResponse,
+    LLMBackend,
+    ModelCapability,
+    Usage,
+)
+
+
+@dataclass(slots=True)
+class CallableBackend(LLMBackend):
+    fn: Callable[[GenerationRequest], GenerationResponse | str | Mapping[str, Any]]
+    model_id: str = "callable"
+    revision: str = "unversioned"
+    callable_id: str = ""
+    capabilities: frozenset[ModelCapability] = frozenset(
+        {ModelCapability.CHAT, ModelCapability.COMPLETION, ModelCapability.SEED}
+    )
+    calls: list[GenerationRequest] = field(default_factory=list, init=False)
+
+    def __post_init__(self) -> None:
+        if not self.revision or self.revision == "unversioned":
+            raise ValidationError("callable backend requires an explicit stable revision")
+        if not self.callable_id:
+            raise ValidationError("callable backend requires an explicit stable callable_id")
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        self.calls.append(request)
+        value = self.fn(request)
+        if isinstance(value, GenerationResponse):
+            return value
+        if isinstance(value, str):
+            return GenerationResponse(text=value, model=self.model_id)
+        return GenerationResponse(
+            text=str(value.get("text", "")),
+            model=str(value.get("model", self.model_id)),
+            finish_reason=str(value.get("finish_reason", "")),
+            usage=Usage(**dict(value.get("usage", {}))),
+            raw=dict(value),
+        )
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {
+            "backend": "callable",
+            "model_id": self.model_id,
+            "revision": self.revision,
+            "callable_id": self.callable_id,
+            "capabilities": sorted(item.value for item in self.capabilities),
+        }
+
+
+@dataclass(slots=True)
+class ReplayBackend(LLMBackend):
+    """Return recorded outputs in order and fail loudly if the cache is exhausted."""
+
+    responses: Iterable[str | GenerationResponse]
+    model_id: str = "replay"
+    capabilities: frozenset[ModelCapability] = frozenset(
+        {ModelCapability.CHAT, ModelCapability.COMPLETION, ModelCapability.SEED}
+    )
+    strict_request_hashes: tuple[str, ...] = ()
+    _queue: deque[str | GenerationResponse] = field(init=False, repr=False)
+    _calls: int = field(default=0, init=False, repr=False)
+    _fixture_hash: str = field(default="", init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        values = tuple(self.responses)
+        self._queue = deque(values)
+        self._fixture_hash = content_hash(values)
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        if self.strict_request_hashes:
+            if self._calls >= len(self.strict_request_hashes):
+                raise RuntimeError("replay request-hash fixture exhausted")
+            expected = self.strict_request_hashes[self._calls]
+            if request.request_hash != expected:
+                raise ValueError(
+                    f"replay request mismatch at {self._calls}: "
+                    f"expected {expected}, got {request.request_hash}"
+                )
+        if not self._queue:
+            raise RuntimeError("replay backend exhausted")
+        self._calls += 1
+        value = self._queue.popleft()
+        if isinstance(value, GenerationResponse):
+            return value
+        return GenerationResponse(text=value, model=self.model_id, finish_reason="replay")
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {
+            "backend": "replay",
+            "model_id": self.model_id,
+            "strict": bool(self.strict_request_hashes),
+            "fixture_hash": self._fixture_hash,
+            "request_fixture_hash": content_hash(self.strict_request_hashes),
+        }

agentinputlab/backends/llm/decomp_completion.py

@@ -0,0 +1,88 @@
+"""Raw-completion transport for the pinned DecomP GPT3Generator seam."""
+from __future__ import annotations
+
+import math
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from agentinputlab.contracts import ValidationError
+from agentinputlab.contracts.serialization import to_jsonable
+
+from .openai_compatible import OpenAICompatibleBackend, _contains_exact_text
+
+_FIELDS = frozenset({"prompt", "engine", "temperature", "max_tokens", "top_p",
+    "frequency_penalty", "presence_penalty", "stop", "n", "best_of", "logprobs"})
+
+
+def validate_native_parameters(value: Mapping) -> dict:
+    """Validate the explicit single-choice native profile without rewriting it."""
+    if (not isinstance(value, Mapping) or set(value) - _FIELDS
+            or _FIELDS - {"best_of"} - set(value)
+            or not isinstance(value.get("prompt"), str) or not value["prompt"]
+            or not isinstance(value.get("engine"), str) or not value["engine"]):
+        raise ValidationError("invalid DecomP native completion fields")
+    if (type(value["n"]) is not int or value["n"] != 1
+            or (value.get("best_of") is not None and
+                (type(value["best_of"]) is not int or value["best_of"] != 1))):
+        raise ValidationError("DecomP live profile requires n=1 and best_of=1 or None")
+    if type(value["max_tokens"]) is not int or value["max_tokens"] < 1:
+        raise ValidationError("DecomP native max_tokens must be positive")
+    for name, lower, upper in (("temperature", 0, 2), ("top_p", 0, 1),
+                               ("frequency_penalty", -2, 2), ("presence_penalty", -2, 2)):
+        number = value[name]
+        if (isinstance(number, bool) or not isinstance(number, (int, float))
+                or not math.isfinite(number) or not lower <= number <= upper):
+            raise ValidationError("invalid DecomP native sampling parameter")
+    if value["top_p"] == 0:
+        raise ValidationError("DecomP native top_p must be positive")
+    stop = value["stop"]
+    if not isinstance(stop, (list, tuple)) or not all(isinstance(s, str) and s for s in stop):
+        raise ValidationError("DecomP native stop must be a string sequence")
+    logs = value["logprobs"]
+    if logs is not None and (type(logs) is not int or not 0 <= logs <= 20):
+        raise ValidationError("invalid DecomP native logprobs")
+    return to_jsonable(value)
+
+
+@dataclass(slots=True)
+class DecompCompletionBackend(OpenAICompatibleBackend):
+    """Preserve original completion parameters and native branch-score inputs.
+
+    The caller-bound model replaces the legacy engine identity. The native
+    GPT3Generator still parses/sorts choices; no chat template, scoring rewrite,
+    response cache, fallback, or automatic retry is introduced here.
+    """
+
+    def __post_init__(self):
+        OpenAICompatibleBackend.__post_init__(self)
+        if self.extra_body:
+            raise ValidationError("DecomP native parameters cannot be overridden by extra_body")
+
+    def complete_native(self, parameters: Mapping, *, seed: int) -> Mapping:
+        value = validate_native_parameters(parameters)
+        if type(seed) is not int or seed < 0:
+            raise ValidationError("DecomP seed must be non-negative")
+        payload = {k: v for k, v in value.items() if k != "engine"}
+        payload.update(model=self.model_id, seed=seed)
+        key = self.api_key or os.environ.get(self.api_key_env, "")
+        headers = {"Content-Type": "application/json", **dict(self.extra_headers)}
+        if key:
+            headers["Authorization"] = "Bearer " + key
+        failed, response = False, None
+        try:
+            response = self.transport(self.base_url + "/completions", headers, payload, self.timeout_seconds)
+        except Exception:
+            failed = True
+        if failed:
+            raise RuntimeError("DecomP native completion transport failed; no retry")
+        if key and _contains_exact_text(response, key):
+            raise RuntimeError("DecomP completion response contains the configured credential")
+        if not isinstance(response, Mapping):
+            raise RuntimeError("DecomP native completion returned an invalid envelope")
+        return response
+
+    def fingerprint(self):
+        return {**dict(OpenAICompatibleBackend.fingerprint(self)),
+            "backend": "decomp_native_raw_completion.v1", "chat_template_applied": False,
+            "legacy_engine_binding": "explicit_caller_model_override", "automatic_retry": False}

agentinputlab/backends/llm/final_content_stop.py

@@ -0,0 +1,72 @@
+"""Explicit final-content stops for OpenAI-compatible reasoning responses.
+
+The provider does not receive logical stop strings, so it cannot terminate
+inside its separate reasoning channel. Apply stops only to the parsed final
+text; keep ALL provider usage, even tokens generated past the logical stop.
+This is opt-in and does not rewrite historical results or backend defaults.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from agentinputlab.contracts import ValidationError
+
+from .base import GenerationRequest, GenerationResponse, ModelCapability
+from .openai_compatible import OpenAICompatibleBackend
+
+FINAL_CONTENT_STOP_POLICY_ID = "openai-compatible.final-content-stop.v1"
+
+
+@dataclass(slots=True)
+class FinalContentStopBackend:
+    """Wrap a backend whose parser separates final content from raw reasoning.
+
+    No second generation is performed to recover truncated/empty content.
+    This wrapper exposes buffered ``generate`` only, not streaming. A generic
+    text decoder that merges reasoning into text cannot establish this contract.
+    """
+
+    inner: OpenAICompatibleBackend
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.inner, OpenAICompatibleBackend):
+            raise ValidationError("final-content stops require an OpenAICompatibleBackend parser")
+        if "stop" in self.inner.extra_body:
+            raise ValidationError("configure logical stops on GenerationRequest, not extra_body")
+
+    @property
+    def model_id(self) -> str:
+        return self.inner.model_id
+
+    @property
+    def capabilities(self) -> frozenset[ModelCapability]:
+        return self.inner.capabilities - {ModelCapability.STREAMING}
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {"backend": "final_content_stop", "policy_id": FINAL_CONTENT_STOP_POLICY_ID,
+            "inner": dict(self.inner.fingerprint()), "reasoning_is_final": False,
+            "charge_all_generated_tokens": True, "streaming": False}
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        if "stop" in self.inner.extra_body:
+            raise ValidationError("configure logical stops on GenerationRequest, not extra_body")
+        if not request.stop:
+            return self.inner.generate(request)
+        if any(not value for value in request.stop):
+            raise ValidationError("final-content stop entries must be non-empty")
+        response = self.inner.generate(replace(request, stop=()))
+        matches = [(response.text.find(stop), index, stop) for index, stop in enumerate(request.stop)
+                   if stop in response.text]
+        match = min(matches) if matches else None
+        return replace(response, text=response.text[:match[0]] if match else response.text,
+            finish_reason="stop" if match else response.finish_reason,
+            raw={**dict(response.raw), "agentinputlab_final_content_stop": {
+                "policy_id": FINAL_CONTENT_STOP_POLICY_ID, "requested_stop": list(request.stop),
+                "matched_stop": match[2] if match else None,
+                "provider_finish_reason": response.finish_reason,
+                "provider_usage_unchanged": True, "new_call_added_by_adapter": False}})
+
+
+__all__ = ["FINAL_CONTENT_STOP_POLICY_ID", "FinalContentStopBackend"]

agentinputlab/backends/llm/gpt_oss_final_channel.py

@@ -0,0 +1,84 @@
+"""Opt-in GPT-OSS stop compatibility for separately reported rerun variants.
+
+Legacy completion-style stops can end a Harmony analysis message before the
+model reaches its final channel. This adapter applies the same stops to final
+content only. It does not promote reasoning to an answer or increase any token
+cap. The server may generate past the logical final stop; *all* server-reported
+tokens are retained and charged. Historical results must not be relabeled with
+this adapter. It is intentionally not enabled by the production builder.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from agentinputlab.contracts.errors import ValidationError
+
+from .base import GenerationRequest, GenerationResponse, ModelCapability
+from .openai_compatible import OpenAICompatibleBackend
+
+POLICY_ID = "gpt-oss.final-channel-stop.v1"
+
+
+@dataclass(slots=True)
+class GPTOSSFinalChannelStopBackend:
+    """Keep stop strings out of Harmony analysis, with no automatic new call."""
+
+    inner: OpenAICompatibleBackend
+
+    def __post_init__(self) -> None:
+        if (
+            self.inner.model_id.casefold() != "gpt-oss-20b"
+            or self.inner.deployment_identity.get("server") != "vllm"
+        ):
+            raise ValidationError("final-channel stop compatibility requires GPT-OSS/vLLM")
+
+    @property
+    def model_id(self) -> str:
+        return self.inner.model_id
+
+    @property
+    def capabilities(self) -> frozenset[ModelCapability]:
+        return self.inner.capabilities
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {
+            "backend": "gpt_oss_final_channel_stop",
+            "policy_id": POLICY_ID,
+            "inner": dict(self.inner.fingerprint()),
+            "reasoning_is_final": False,
+            "charge_all_generated_tokens": True,
+        }
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        if not request.stop:
+            return self.inner.generate(request)
+        if any(not value for value in request.stop):
+            raise ValidationError("final-channel stop entries must be non-empty")
+        # Only logical stop handling changes. In particular max_tokens, seed,
+        # messages, tools, temperature, and metadata are not regenerated.
+        response = self.inner.generate(replace(request, stop=()))
+        matches = [
+            (response.text.find(value), index, value)
+            for index, value in enumerate(request.stop)
+            if value in response.text
+        ]
+        match = min(matches) if matches else None
+        return replace(
+            response,
+            text=response.text[:match[0]] if match else response.text,
+            finish_reason="stop" if match else response.finish_reason,
+            raw={
+                **dict(response.raw),
+                "agentinputlab_final_channel_stop": {
+                    "policy_id": POLICY_ID,
+                    "requested_stop": list(request.stop),
+                    "matched_stop": match[2] if match else None,
+                    "provider_finish_reason": response.finish_reason,
+                    "provider_usage_unchanged": True,
+                    "new_call_added_by_adapter": False,
+                },
+            },
+        )