typevet 0.1.0.dev1__py3-none-any.whl

typevet/adapters/inbound/cord_semantic_acceptance_cli.py

@@ -0,0 +1,135 @@
+r"""Operator CLI for offline CORD combined receipt semantic acceptance (#184).
+
+A receipt with a top-level ``stopped`` string reports the stop and exits 1
+with no floor table. A ``stopped`` value that is not a string or ``null`` is
+a malformed receipt and exits 2 (#216).
+
+Examples:
+    ```console
+    $ uv run python -m typevet.adapters.inbound.cord_semantic_acceptance_cli \\
+        tests/fixtures/cord/semantic_acceptance/labeled_synthetic_pass.json
+    | check | bound | limit | measured | n | status |
+    ...
+    accepted: true
+    ```
+
+See Also:
+    - [typevet.evaluation.cord_semantic_acceptance][]: ``accept_combined_receipt``
+    - [typevet.evaluation.cord_semantic_acceptance_report][]: table formatting
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from typevet.evaluation.cord_semantic_acceptance_report import (
+    evaluate_combined_receipt,
+    format_semantic_acceptance_report,
+)
+
+_EXIT_ACCEPT = 0
+_EXIT_REJECT = 1
+_EXIT_USAGE_OR_MALFORMED = 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    return argparse.ArgumentParser(
+        description=(
+            "Evaluate one saved CORD combined-modality receipt against the "
+            "frozen #161 revision 1 semantic floors. Exit 0 only when accepted."
+        ),
+    )
+
+
+def _load_receipt(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        msg = f"receipt path is not a file: {path}"
+        raise ValueError(msg)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        msg = f"cannot read receipt: {path}"
+        raise ValueError(msg) from exc
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        msg = f"receipt is not valid JSON: {path}"
+        raise ValueError(msg) from exc
+    if not isinstance(parsed, dict):
+        msg = "receipt root must be a JSON object"
+        raise TypeError(msg)
+    return parsed
+
+
+def _stopped_exit(stopped: object) -> int | None:
+    if stopped is None:
+        return None
+    if not isinstance(stopped, str):
+        msg = "error: malformed receipt: stopped must be a string or null"
+        print(msg, file=sys.stderr)
+        return _EXIT_USAGE_OR_MALFORMED
+    print(f"stopped: {stopped.strip() or '<unspecified>'}", file=sys.stderr)
+    return _EXIT_REJECT
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Load a receipt path, print the floor table, return a process exit code.
+
+    Args:
+        argv: CLI args; defaults to ``sys.argv[1:]`` (one receipt path).
+
+    The top-level ``stopped`` value selects one of four cases:
+
+    - Missing or ``null``: the floor table is evaluated and printed.
+    - A string with text: ``stopped: <reason>`` on stderr, exit ``1``, no
+      floor table.
+    - An empty or whitespace-only string: ``stopped: <unspecified>`` on
+      stderr, exit ``1``, no floor table.
+    - Any other value (for example ``true``, an object or a number): a
+      malformed-receipt error on stderr, exit ``2``, no floor table.
+
+    Returns:
+        ``0`` when ``accepted`` is true, ``1`` when checks fail or the run
+        stopped, ``2`` on usage errors, malformed receipts, or
+        ``ValueError`` / ``TypeError`` from parsing.
+    """
+    parser = _build_parser()
+    parser.add_argument(
+        "receipt",
+        type=Path,
+        help="Path to a saved combined CORD outcome JSON file",
+    )
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        if code in (0, None):
+            return _EXIT_ACCEPT
+        return (
+            _EXIT_USAGE_OR_MALFORMED
+            if code == _EXIT_USAGE_OR_MALFORMED
+            else _EXIT_REJECT
+        )
+    try:
+        receipt = _load_receipt(args.receipt)
+    except (ValueError, TypeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return _EXIT_USAGE_OR_MALFORMED
+    stopped_code = _stopped_exit(receipt.get("stopped"))
+    if stopped_code is not None:
+        return stopped_code
+    try:
+        outcome = evaluate_combined_receipt(receipt)
+    except (ValueError, TypeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return _EXIT_USAGE_OR_MALFORMED
+    print(format_semantic_acceptance_report(outcome))
+    return _EXIT_ACCEPT if outcome.accepted else _EXIT_REJECT
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

typevet/adapters/inbound/helpers.py

@@ -0,0 +1,67 @@
+"""Sync bridge for async generation callers (scripts and CLIs).
+
+Examples:
+    ```python
+    from typevet import GenerationRequest
+    from typevet.adapters.inbound import run_sync
+    from typevet.adapters.outbound import AsyncFakeGenerationAdapter
+
+    schema = {
+        "type": "object",
+        "properties": {"ok": {"type": "boolean"}},
+        "required": ["ok"],
+        "additionalProperties": False,
+    }
+    port = AsyncFakeGenerationAdapter(value={"ok": True})
+    result = run_sync(
+        port.generate(GenerationRequest(prompt="Say ok.", schema=schema, model="fake"))
+    )
+    assert result.value["ok"] is True
+    ```
+
+See Also:
+    - [typevet.ports.async_generation][]: AsyncGenerationPort
+    - [typevet.adapters.inbound.api][]: Sync ``generate`` helper
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+
+def run_sync[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine synchronously and return its result.
+
+    Use this from plain scripts instead of adding ``*_sync`` methods on ports.
+    Pass a coroutine object (for example ``port.generate(request)``), not the
+    unbound method.
+
+    Args:
+        coro: Coroutine to execute (typically from ``AsyncGenerationPort.generate``).
+
+    Returns:
+        The coroutine result (for example a ``GenerationResult``).
+
+    Raises:
+        TypeError: When ``coro`` is not a coroutine object.
+        RuntimeError: When called from a thread that already has a running loop.
+    """
+    if not asyncio.iscoroutine(coro):
+        msg = (
+            f"run_sync() requires a coroutine object, got {type(coro).__name__}. "
+            "Call the async method first: run_sync(port.generate(request))"
+        )
+        raise TypeError(msg)
+
+    try:
+        return asyncio.run(coro)
+    except RuntimeError as exc:
+        if "asyncio.run() cannot be called from a running event loop" in str(exc):
+            msg = (
+                "run_sync() cannot run while an event loop is already active. "
+                "Await port.generate(...) in async code instead."
+            )
+            raise RuntimeError(msg) from exc
+        raise

typevet/adapters/inbound/settings.py

@@ -0,0 +1,154 @@
+"""Environment-backed llama.cpp settings for the composition root.
+
+Outbound adapters take explicit constructor arguments. Only a composition root
+(CLI, MCP server, or live test harness) reads ``TYPEVET_LLAMA__*`` variables
+and passes the values into [typevet.adapters.outbound.llama_cpp][].
+
+Diagnostic log settings live in [typevet.adapters.diagnostics.settings][].
+
+Examples:
+    ```python
+    from typevet.adapters.inbound.settings import (
+        llama_cpp_adapter,
+        load_llama_settings,
+    )
+
+    settings = load_llama_settings()
+    with llama_cpp_adapter(settings) as port:
+        pass  # port.generate(...)
+    ```
+
+See Also:
+    - [typevet.adapters.outbound.llama_cpp][]: Sync llama.cpp adapter
+    - [typevet.adapters.diagnostics.settings][]: ``TYPEVET_LOG__*`` settings
+    - docs/reference/configuration.md: Environment variable reference
+    - docs/how-to/run-a-multimodal-live-smoke.md: ``multimodal_model`` consumer
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from typevet.adapters.outbound.llama_cpp import LlamaCppGenerationAdapter
+
+_DEFAULT_BASE_URL = "http://127.0.0.1:8090"
+_DEFAULT_TIMEOUT = 300.0
+_DEFAULT_MULTIMODAL_MODEL = "gemma-3-4b-it-q4km-mm"
+
+
+@dataclass(frozen=True, slots=True)
+class LlamaSettings:
+    """Connection options for a local llama.cpp OpenAI-compat router.
+
+    Attributes:
+        base_url (str): Router root without a trailing slash.
+        timeout (float): HTTP request timeout in seconds.
+        default_model (str | None): Default model id when a call omits one.
+        multimodal_model (str): Model id the opt-in image smoke asks for.
+
+    Examples:
+        ```python
+        from typevet.adapters.inbound.settings import LlamaSettings
+
+        LlamaSettings(base_url="http://127.0.0.1:8090", timeout=300.0)
+        ```
+    """
+
+    base_url: str = _DEFAULT_BASE_URL
+    timeout: float = _DEFAULT_TIMEOUT
+    default_model: str | None = None
+    multimodal_model: str = _DEFAULT_MULTIMODAL_MODEL
+
+
+def _read_base_url(source: Mapping[str, str]) -> str:
+    nested = source.get("TYPEVET_LLAMA__BASE_URL", "").strip()
+    if nested:
+        return nested.rstrip("/")
+    legacy = source.get("TYPEVET_LLAMA_URL", "").strip()
+    if legacy:
+        return legacy.rstrip("/")
+    return _DEFAULT_BASE_URL
+
+
+def _read_default_model(source: Mapping[str, str]) -> str | None:
+    nested = source.get("TYPEVET_LLAMA__DEFAULT_MODEL", "").strip()
+    if nested:
+        return nested
+    legacy = source.get("TYPEVET_GEMMA_MODEL", "").strip()
+    return legacy or None
+
+
+def _read_multimodal_model(source: Mapping[str, str]) -> str:
+    nested = source.get("TYPEVET_LLAMA__MULTIMODAL_MODEL", "").strip()
+    return nested or _DEFAULT_MULTIMODAL_MODEL
+
+
+def _read_timeout(source: Mapping[str, str]) -> float:
+    raw = source.get("TYPEVET_LLAMA__TIMEOUT", "").strip()
+    if not raw:
+        return _DEFAULT_TIMEOUT
+    try:
+        timeout = float(raw)
+    except ValueError as exc:
+        msg = "TYPEVET_LLAMA__TIMEOUT must be a positive number of seconds"
+        raise ValueError(msg) from exc
+    if timeout <= 0:
+        msg = "TYPEVET_LLAMA__TIMEOUT must be a positive number of seconds"
+        raise ValueError(msg)
+    return timeout
+
+
+def load_llama_settings(
+    environ: Mapping[str, str] | None = None,
+) -> LlamaSettings:
+    """Read ``TYPEVET_LLAMA__*`` variables for the composition root.
+
+    Legacy single-segment names ``TYPEVET_LLAMA_URL`` and ``TYPEVET_GEMMA_MODEL``
+    remain supported when the nested names are unset.
+    ``TYPEVET_LLAMA__MULTIMODAL_MODEL`` names the model id for the opt-in image
+    smoke and has no legacy alias.
+
+    Args:
+        environ: Mapping to read. Defaults to ``os.environ``.
+
+    Returns:
+        Frozen settings with defaults for missing keys.
+
+    Raises:
+        ValueError: When ``TYPEVET_LLAMA__TIMEOUT`` is not a positive number.
+    """
+    source = os.environ if environ is None else environ
+    return LlamaSettings(
+        base_url=_read_base_url(source),
+        timeout=_read_timeout(source),
+        default_model=_read_default_model(source),
+        multimodal_model=_read_multimodal_model(source),
+    )
+
+
+def llama_cpp_adapter(settings: LlamaSettings) -> LlamaCppGenerationAdapter:
+    """Build a sync llama.cpp adapter from composition-root settings.
+
+    Args:
+        settings: Values read from the environment or constructed in tests.
+
+    Returns:
+        An adapter that does not read ``os.environ`` itself.
+
+    Examples:
+        ```python
+        from typevet.adapters.inbound.settings import (
+            llama_cpp_adapter,
+            load_llama_settings,
+        )
+
+        with llama_cpp_adapter(load_llama_settings()) as port:
+            pass
+        ```
+    """
+    return LlamaCppGenerationAdapter(
+        base_url=settings.base_url,
+        timeout=settings.timeout,
+    )

typevet/adapters/outbound/__init__.py

@@ -0,0 +1,62 @@
+"""Outbound adapter package.
+
+Examples:
+    ```python
+    from typevet.adapters.outbound import (
+        AsyncFakeGenerationAdapter,
+        AsyncLlamaCppGenerationAdapter,
+        AsyncVllmGenerationAdapter,
+        ChatContentFraming,
+        FakeGenerationAdapter,
+        LlamaCppCandidateScoringAdapter,
+        LlamaCppGenerationAdapter,
+        VllmCandidateScoringAdapter,
+        VllmGenerationAdapter,
+    )
+    ```
+
+See Also:
+    - [typevet.adapters.outbound.llama_cpp][]: Local llama.cpp router adapter
+    - [typevet.adapters.outbound.fake][]: Offline validating fake
+    - [typevet.adapters.outbound.vllm_scoring][]: vLLM chat logprob scorer
+    - [typevet.adapters.outbound.vllm_generation][]: vLLM structured generation
+    - [typevet.adapters.outbound.vllm_generation_async][]: Async vLLM generation
+    - [typevet.adapters.outbound.vllm_http][]: vLLM HTTP error mapping
+    - [typevet.adapters.outbound.chat_completion][]: Shared content and schema checks
+    - [typevet.adapters.outbound.http_errors][]: Shared HTTP error limits
+
+Attributes:
+    AsyncFakeGenerationAdapter (type): Offline async validating fake.
+    AsyncLlamaCppGenerationAdapter (type): Async OpenAI-compat llama.cpp adapter.
+    AsyncVllmGenerationAdapter (type): Async vLLM generation with a POST limit.
+    ChatContentFraming (type): Plain chat content framing for vLLM scoring.
+    FakeGenerationAdapter (type): Offline adapter that validates a fixed value.
+    LlamaCppCandidateScoringAdapter (type): Pre-sampling ``/completion`` scorer.
+    LlamaCppGenerationAdapter (type): OpenAI-compat llama.cpp adapter.
+    VllmCandidateScoringAdapter (type): vLLM chat completions logprob scorer.
+    VllmGenerationAdapter (type): vLLM structured-output generation adapter.
+"""
+
+from typevet.adapters.outbound.async_fake import AsyncFakeGenerationAdapter
+from typevet.adapters.outbound.async_llama_cpp import AsyncLlamaCppGenerationAdapter
+from typevet.adapters.outbound.fake import FakeGenerationAdapter
+from typevet.adapters.outbound.llama_cpp import LlamaCppGenerationAdapter
+from typevet.adapters.outbound.llama_cpp_scoring import LlamaCppCandidateScoringAdapter
+from typevet.adapters.outbound.vllm_generation import VllmGenerationAdapter
+from typevet.adapters.outbound.vllm_generation_async import AsyncVllmGenerationAdapter
+from typevet.adapters.outbound.vllm_scoring import (
+    ChatContentFraming,
+    VllmCandidateScoringAdapter,
+)
+
+__all__ = [
+    "AsyncFakeGenerationAdapter",
+    "AsyncLlamaCppGenerationAdapter",
+    "AsyncVllmGenerationAdapter",
+    "ChatContentFraming",
+    "FakeGenerationAdapter",
+    "LlamaCppCandidateScoringAdapter",
+    "LlamaCppGenerationAdapter",
+    "VllmCandidateScoringAdapter",
+    "VllmGenerationAdapter",
+]

typevet/adapters/outbound/async_fake.py

@@ -0,0 +1,123 @@
+"""Offline async fake generation adapter for unit and contract tests.
+
+Examples:
+    ```python
+    from typevet.adapters.outbound.async_fake import AsyncFakeGenerationAdapter
+    from typevet.domain.models import GenerationRequest
+
+    import asyncio
+
+    asyncio.run(
+        AsyncFakeGenerationAdapter(value={"answer": 1}).generate(
+            GenerationRequest(
+                prompt="n",
+                schema={
+                    "type": "object",
+                    "properties": {"answer": {"type": "integer"}},
+                    "required": ["answer"],
+                    "additionalProperties": False,
+                },
+                model="fake",
+            )
+        )
+    )
+    ```
+
+See Also:
+    - [typevet.adapters.outbound.generation_finite][]: Non-finite float guard
+    - [typevet.adapters.outbound.fake][]: Sync fake
+    - [typevet.adapters.outbound.async_llama_cpp][]: Live llama.cpp adapter
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import jsonschema
+
+from typevet.adapters.outbound.generation_finite import reject_non_finite_numbers
+from typevet.domain.errors import GenerationError, SchemaValidationError
+from typevet.domain.models import GenerationRequest, GenerationResult
+
+AsyncResponder = Callable[[GenerationRequest], Mapping[str, Any]]
+
+
+class AsyncFakeGenerationAdapter:
+    """Return a fixed or callable mapping and validate it against the schema.
+
+    The fake itself does not read ``request.media``; a responder
+    receives the full request.
+
+    Attributes:
+        _value (Mapping[str, Any] | None): Fixed mapping when set.
+        _responder (AsyncResponder | None): Callable producer when set.
+        _fail (Exception | None): Exception raised instead of a value.
+
+    Examples:
+        ```python
+        from typevet.adapters.outbound.async_fake import AsyncFakeGenerationAdapter
+
+        AsyncFakeGenerationAdapter(value={"answer": 1})
+        ```
+    """
+
+    def __init__(
+        self,
+        value: Mapping[str, Any] | None = None,
+        *,
+        responder: AsyncResponder | None = None,
+        fail: Exception | None = None,
+    ) -> None:
+        """Configure the fake.
+
+        Args:
+            value: Fixed mapping returned for every call (validated).
+            responder: Optional callable that builds the mapping from the request.
+            fail: When set, ``generate`` raises this exception instead.
+
+        Raises:
+            ValueError: When value, responder and fail are all omitted.
+        """
+        if value is None and responder is None and fail is None:
+            msg = "provide value, responder, or fail"
+            raise ValueError(msg)
+        self._value = value
+        self._responder = responder
+        self._fail = fail
+
+    async def generate(self, request: GenerationRequest) -> GenerationResult:
+        """Return a validated mapping or raise the configured failure.
+
+        Args:
+            request: Typed generation request.
+
+        Returns:
+            GenerationResult with the fake value.
+
+        Raises:
+            Exception: The configured ``fail`` value when set.
+            GenerationError: When the fake has no value source.
+            SchemaValidationError: When the fake value is non-finite or fails schema.
+        """
+        if self._fail is not None:
+            raise self._fail
+        if self._responder is not None:
+            raw: Mapping[str, Any] = self._responder(request)
+        elif self._value is not None:
+            raw = self._value
+        else:
+            msg = "fake has no value"
+            raise GenerationError(msg)
+
+        schema_obj = dict(request.schema)
+        instance = dict(raw)
+        reject_non_finite_numbers(instance)
+        try:
+            jsonschema.validate(instance=instance, schema=schema_obj)
+        except jsonschema.ValidationError as exc:
+            raise SchemaValidationError(
+                f"fake output failed schema: {exc.message}",
+                payload=raw,
+            ) from exc
+        return GenerationResult(value=instance, model=request.model, raw_text=None)