typevet 0.1.0.dev1__py3-none-any.whl

typevet/adapters/diagnostics/settings.py

@@ -0,0 +1,77 @@
+"""Environment-backed log settings for the composition root.
+
+Diagnostics are operator signals on stderr, not telemetry and not remote export.
+Importing this module does not configure structlog.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.settings import load_log_settings
+
+    settings = load_log_settings({"TYPEVET_LOG__LEVEL": "debug"})
+    assert settings.level == "debug"
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.logs][]: Applies these settings to structlog
+    - [typevet.adapters.diagnostics.redaction][]: Honors ``log_prompts`` when masking
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+_VALID_FORMATS = frozenset({"auto", "json", "console"})
+_VALID_LEVELS = frozenset({"debug", "info", "warning", "error", "critical"})
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+@dataclass(frozen=True, slots=True)
+class LogSettings:
+    """How diagnostic lines are rendered and which severities are kept.
+
+    Attributes:
+        format (str): ``auto``, ``json`` or ``console``. Default ``auto``.
+        level (str): ``debug`` through ``critical``. Default ``info``.
+        log_prompts (bool): When false, prompt-like fields are stripped from output.
+
+    Examples:
+        ```python
+        from typevet.adapters.diagnostics.settings import LogSettings
+
+        LogSettings(format="json", level="debug", log_prompts=True)
+        ```
+    """
+
+    format: str = "auto"
+    level: str = "info"
+    log_prompts: bool = False
+
+
+def load_log_settings(
+    environ: Mapping[str, str] | None = None,
+) -> LogSettings:
+    """Read ``TYPEVET_LOG__*`` variables for the composition root.
+
+    Args:
+        environ: Mapping to read. Defaults to ``os.environ``.
+
+    Returns:
+        Frozen settings with defaults for missing keys.
+
+    Raises:
+        ValueError: When format or level is not an allowed value.
+    """
+    source = os.environ if environ is None else environ
+    fmt = source.get("TYPEVET_LOG__FORMAT", "auto").strip().lower()
+    level = source.get("TYPEVET_LOG__LEVEL", "info").strip().lower()
+    log_prompts_raw = source.get("TYPEVET_LOG__LOG_PROMPTS", "").strip().lower()
+    if fmt not in _VALID_FORMATS:
+        msg = f"TYPEVET_LOG__FORMAT must be one of {sorted(_VALID_FORMATS)}"
+        raise ValueError(msg)
+    if level not in _VALID_LEVELS:
+        msg = f"TYPEVET_LOG__LEVEL must be one of {sorted(_VALID_LEVELS)}"
+        raise ValueError(msg)
+    log_prompts = log_prompts_raw in _TRUTHY
+    return LogSettings(format=fmt, level=level, log_prompts=log_prompts)

typevet/adapters/inbound/__init__.py

@@ -0,0 +1,65 @@
+"""Inbound adapters (library entry points).
+
+Examples:
+    ```python
+    from typevet.adapters.inbound import generate
+    from typevet.testing import StaticGenerationFake
+
+    result = generate(
+        StaticGenerationFake({"ok": True}),
+        prompt="hi",
+        schema={"type": "object", "additionalProperties": False},
+        model="fake",
+    )
+    ```
+
+See Also:
+    - [typevet.adapters.inbound.api][]: ``generate`` helper
+    - [typevet.adapters.inbound.helpers][]: ``run_sync`` helper
+    - [typevet.adapters.inbound.settings][]: ``TYPEVET_LLAMA__*`` composition root
+    - [typevet.adapters.inbound.backend_settings][]: ``TYPEVET_BACKEND`` selection
+    - [typevet.ports.generation][]: GenerationPort
+
+Attributes:
+    generate (function): Build a request and invoke a generation port.
+    run_sync (function): Run an async generation coroutine from sync code.
+    LlamaSettings (type): llama.cpp connection settings for composition roots.
+    load_llama_settings (function): Read ``TYPEVET_LLAMA__*`` from the environment.
+    llama_cpp_adapter (function): Build ``LlamaCppGenerationAdapter`` from settings.
+    VllmSettings (type): vLLM connection settings; ``api_key`` is not in ``repr``.
+    load_backend (function): Read ``TYPEVET_BACKEND``.
+    load_vllm_settings (function): Read ``TYPEVET_VLLM__*`` from the environment.
+    vllm_http_client (function): Build the shared vLLM ``httpx.Client``.
+    generation_adapter (function): Build the adapter ``TYPEVET_BACKEND`` selects.
+    async_vllm_generation_adapter (function): Build the async vLLM adapter.
+"""
+
+from typevet.adapters.inbound.api import generate
+from typevet.adapters.inbound.backend_settings import (
+    VllmSettings,
+    async_vllm_generation_adapter,
+    generation_adapter,
+    load_backend,
+    load_vllm_settings,
+    vllm_http_client,
+)
+from typevet.adapters.inbound.helpers import run_sync
+from typevet.adapters.inbound.settings import (
+    LlamaSettings,
+    llama_cpp_adapter,
+    load_llama_settings,
+)
+
+__all__ = [
+    "LlamaSettings",
+    "VllmSettings",
+    "async_vllm_generation_adapter",
+    "generate",
+    "generation_adapter",
+    "llama_cpp_adapter",
+    "load_backend",
+    "load_llama_settings",
+    "load_vllm_settings",
+    "run_sync",
+    "vllm_http_client",
+]

typevet/adapters/inbound/api.py

@@ -0,0 +1,61 @@
+"""Library entry: call a generation port with a typed request.
+
+Examples:
+    ```python
+    from typevet.adapters.inbound.api import generate
+    from typevet.testing import StaticGenerationFake
+
+    generate(
+        StaticGenerationFake({"n": 1}),
+        prompt="n",
+        schema={
+            "type": "object",
+            "properties": {"n": {"type": "integer"}},
+            "required": ["n"],
+            "additionalProperties": False,
+        },
+        model="fake",
+    )
+    ```
+
+See Also:
+    - [typevet.domain.media][]: ImageInput and the media marker
+    - [typevet.domain.models][]: GenerationRequest
+    - [typevet.ports.generation][]: GenerationPort
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from typevet.domain.models import GenerationRequest, GenerationResult
+from typevet.ports.generation import GenerationPort
+
+if TYPE_CHECKING:
+    from typevet.domain.media import ImageInput
+
+
+def generate(
+    port: GenerationPort,
+    *,
+    prompt: str,
+    schema: Mapping[str, Any],
+    model: str,
+    media: tuple[ImageInput, ...] = (),
+) -> GenerationResult:
+    """Build a request and invoke the generation port.
+
+    Args:
+        port: Outbound adapter that implements ``GenerationPort``.
+        prompt: Natural-language instruction.
+        schema: JSON Schema object as a mapping.
+        model: Backend model id or alias.
+        media: Images the prompt marks, one ``MEDIA_MARKER`` each, in
+            marker order. Empty for a text ask.
+
+    Returns:
+        Validated generation result from the port.
+    """
+    request = GenerationRequest(prompt=prompt, schema=schema, model=model, media=media)
+    return port.generate(request)