typevet 0.1.0.dev1__py3-none-any.whl

typevet/__init__.py

@@ -0,0 +1,67 @@
+"""typevet: type-safe structured generation under hexagonal architecture.
+
+Examples:
+    ```python
+    from typevet import GenerationRequest, GenerationResult
+    from typevet.adapters.outbound import FakeGenerationAdapter
+
+    schema = {
+        "type": "object",
+        "properties": {"ok": {"type": "boolean"}},
+        "required": ["ok"],
+        "additionalProperties": False,
+    }
+    port = FakeGenerationAdapter(value={"ok": True})
+    result = port.generate(
+        GenerationRequest(prompt="Say ok.", schema=schema, model="fake")
+    )
+    assert result.value["ok"] is True
+    ```
+
+See Also:
+    - [typevet._version][]: Resolves ``__version__`` from distribution metadata
+    - [typevet.domain][]: Request, result and error types
+    - [typevet.ports][]: GenerationPort protocol
+    - [typevet.adapters.outbound][]: llama.cpp and fake adapters
+    - [typevet.runtime][]: Source of the ``decide_categorical`` re-export
+
+Attributes:
+    BackendHttpError (type): llama.cpp HTTP error status with body snippet.
+    GenerationError (type): Base failure for a generation call.
+    TransportError (type): HTTP client failure before a response.
+    AsyncGenerationPort (type): Structural protocol for async typed generation.
+    GenerationPort (type): Structural protocol for typed generation.
+    GenerationRequest (type): Prompt, schema and model ask.
+    GenerationResult (type): Validated structured value.
+    SchemaValidationError (type): Output failed the requested schema.
+    decide_categorical (callable): M1 categorical decision via scoring port;
+        re-exported from ``typevet.runtime.categorical``.
+    __version__ (str): Installed distribution version; matches
+        ``importlib.metadata.version("typevet")`` when the package is on
+        ``PYTHONPATH``. Exported in ``__all__``.
+"""
+
+from typevet._version import __version__
+from typevet.domain.errors import (
+    BackendHttpError,
+    GenerationError,
+    SchemaValidationError,
+    TransportError,
+)
+from typevet.domain.models import GenerationRequest, GenerationResult
+from typevet.ports.async_generation import AsyncGenerationPort
+from typevet.ports.generation import GenerationPort
+from typevet.runtime.categorical import decide_categorical
+
+__all__ = [
+    "AsyncGenerationPort",
+    "BackendHttpError",
+    "GenerationError",
+    "GenerationPort",
+    "GenerationRequest",
+    "GenerationResult",
+    "SchemaValidationError",
+    "TransportError",
+    "__version__",
+    "decide_categorical",
+]

typevet/_version.py

@@ -0,0 +1,43 @@
+"""Resolve the package version from distribution metadata.
+
+When the wheel or sdist is installed, ``__version__`` comes from
+``importlib.metadata``. In editable checkouts without metadata, it falls back
+to ``[project].version`` in ``pyproject.toml``.
+
+Examples:
+    ```python
+    import typevet
+    from importlib.metadata import version
+
+    assert typevet.__version__ == version("typevet")
+    ```
+
+See Also:
+    - [typevet][]: Re-exports ``__version__`` in ``__all__``
+"""
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+__all__ = ["__version__"]
+
+
+def _read_pyproject_version() -> str:
+    root = Path(__file__).resolve().parents[2]
+    data = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    project_version = data["project"]["version"]
+    if not isinstance(project_version, str):
+        msg = "pyproject [project].version must be a string"
+        raise TypeError(msg)
+    return project_version
+
+
+def _package_version() -> str:
+    try:
+        return version("typevet")
+    except PackageNotFoundError:
+        return _read_pyproject_version()
+
+
+__version__ = _package_version()

typevet/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Adapters between the domain and the outside world.
+
+Examples:
+    ```python
+    from typevet.adapters.inbound import generate
+    from typevet.adapters.outbound import FakeGenerationAdapter
+    ```
+
+See Also:
+    - [typevet.adapters.inbound][]: Library entry points
+    - [typevet.adapters.outbound][]: Inference backends
+    - [typevet.ports][]: Port protocols
+
+Attributes:
+    None: This package provides organizational structure only.
+"""

typevet/adapters/diagnostics/__init__.py

@@ -0,0 +1,59 @@
+"""Structured stderr diagnostics for generation and HTTP adapters.
+
+Diagnostics are operator signals, not telemetry: no automatic network export.
+Importing this package does not configure structlog.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics import (
+        bind_run_id,
+        configure_from_environ,
+        generation_call_event,
+        http_request_event,
+        new_run_id,
+    )
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.logs][]: Composition-root configuration
+    - [typevet.adapters.diagnostics.redaction][]: Secret and prompt redaction
+
+Attributes:
+    REDACTED (str): Placeholder written over redacted secret values.
+    SECRET_KEYS (frozenset[str]): Field names always masked in diagnostics.
+    LogSettings (type): Frozen log format, level and prompt policy.
+    bind_run_id (function): Bind ``run_id`` on every diagnostic line.
+    configure (function): Apply ``LogSettings`` to stderr structlog.
+    configure_from_environ (function): Load env settings and configure once.
+    diagnostic_model (function): Keep safe model aliases in event fields.
+    generation_call_event (function): Terminal ``generation.call`` context manager.
+    http_request_event (function): Terminal ``http.request`` context manager.
+    load_log_settings (function): Read ``TYPEVET_LOG__*`` variables.
+    new_run_id (function): Create a short hex invocation id.
+"""
+
+from typevet.adapters.diagnostics.fields import diagnostic_model
+from typevet.adapters.diagnostics.generation_events import generation_call_event
+from typevet.adapters.diagnostics.http_events import http_request_event
+from typevet.adapters.diagnostics.logs import (
+    bind_run_id,
+    configure,
+    configure_from_environ,
+    new_run_id,
+)
+from typevet.adapters.diagnostics.redaction import REDACTED, SECRET_KEYS
+from typevet.adapters.diagnostics.settings import LogSettings, load_log_settings
+
+__all__ = [
+    "REDACTED",
+    "SECRET_KEYS",
+    "LogSettings",
+    "bind_run_id",
+    "configure",
+    "configure_from_environ",
+    "diagnostic_model",
+    "generation_call_event",
+    "http_request_event",
+    "load_log_settings",
+    "new_run_id",
+]

typevet/adapters/diagnostics/fields.py

@@ -0,0 +1,108 @@
+"""Filter built-in diagnostic events and bound model identifiers.
+
+Built-in events form a closed set until the reference table lands (#40).
+Importing this module does not configure logging.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.fields import diagnostic_model
+
+    assert diagnostic_model("gemma-4-test") == "gemma-4-test"
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.logs][]: Wires ``filter_event_fields`` into structlog
+    - [typevet.adapters.diagnostics.generation_events][]: ``generation.call`` field set
+    - [typevet.adapters.diagnostics.http_events][]: ``http.request`` field set
+"""
+
+from __future__ import annotations
+
+import re
+from contextvars import ContextVar, Token
+from typing import Any
+
+_RUN_ID: ContextVar[str | None] = ContextVar("typevet_run_id", default=None)
+_MODEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$")
+_EVENT_FIELDS = {
+    "generation.call": frozenset(
+        {
+            "event",
+            "model",
+            "outcome",
+            "error_type",
+            "run_id",
+        }
+    ),
+    "http.request": frozenset(
+        {
+            "event",
+            "method",
+            "path",
+            "model",
+            "status_code",
+            "outcome",
+            "error_type",
+            "run_id",
+        }
+    ),
+}
+
+
+def current_run_id() -> str | None:
+    """Return the bound invocation ``run_id``, if any.
+
+    Returns:
+        The current ``run_id``, or ``None`` when nothing is bound.
+    """
+    return _RUN_ID.get()
+
+
+def set_run_id_context(run_id: str | None) -> Token[str | None]:
+    """Store ``run_id`` in a context variable; returns the reset token.
+
+    Args:
+        run_id: Identifier to attach to subsequent diagnostic lines.
+
+    Returns:
+        Token passed to ``reset_run_id_context`` to restore the prior value.
+    """
+    return _RUN_ID.set(run_id)
+
+
+def reset_run_id_context(token: Token[str | None]) -> None:
+    """Restore the previous ``run_id`` binding."""
+    _RUN_ID.reset(token)
+
+
+def diagnostic_model(model: str | None) -> str | None:
+    """Keep bounded model aliases in diagnostics without changing API values.
+
+    Args:
+        model: Requested or resolved router model alias.
+
+    Returns:
+        The identifier when it matches the safe pattern, else ``None``.
+    """
+    if model is not None and _MODEL.fullmatch(model):
+        return model
+    return None
+
+
+def filter_event_fields(
+    _logger: Any, _method: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Drop unknown keys from built-in events; keep application events intact.
+
+    Prompts, schemas, headers and response bodies never appear in the
+    closed field sets for ``generation.call`` and ``http.request``.
+
+    Returns:
+        The event dict unchanged for unknown events, or filtered to the
+        closed field set for built-in events.
+    """
+    name = event_dict.get("event")
+    fields = _EVENT_FIELDS.get(name) if isinstance(name, str) else None
+    if fields is None:
+        return event_dict
+    return {key: value for key, value in event_dict.items() if key in fields}

typevet/adapters/diagnostics/generation_events.py

@@ -0,0 +1,75 @@
+"""Emit one terminal generation diagnostic per logical call when configured.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.generation_events import generation_call_event
+
+    with generation_call_event(model="fake") as event:
+        event.outcome = "success"
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.fields][]: ``run_id`` and model field helpers
+    - [typevet.adapters.diagnostics.logs][]: Configures structlog before events emit
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+
+import structlog
+
+from typevet.adapters.diagnostics.fields import current_run_id, diagnostic_model
+
+
+@dataclass
+class GenerationCallEvent:
+    """Terminal generation metadata without prompt or schema payloads.
+
+    Attributes:
+        outcome (str): ``success`` or ``error`` after the adapter finishes.
+
+    Examples:
+        ```python
+        from typevet.adapters.diagnostics.generation_events import GenerationCallEvent
+
+        event = GenerationCallEvent(outcome="success")
+        assert event.outcome == "success"
+        ```
+    """
+
+    outcome: str = "error"
+
+
+@contextmanager
+def generation_call_event(*, model: str) -> Iterator[GenerationCallEvent]:
+    """Yield terminal metadata and emit ``generation.call`` when configured.
+
+    Args:
+        model: Router model alias for the call.
+
+    Yields:
+        Event state the adapter updates before the block exits.
+
+    Raises:
+        BaseException: Re-raises any exception from the wrapped block after
+            recording ``error_type`` on the terminal event.
+    """
+    event = GenerationCallEvent()
+    failure: BaseException | None = None
+    try:
+        yield event
+    except BaseException as exc:
+        failure = exc
+        raise
+    finally:
+        if structlog.is_configured():
+            structlog.get_logger().debug(
+                "generation.call",
+                model=diagnostic_model(model),
+                outcome=event.outcome,
+                error_type=None if failure is None else type(failure).__name__,
+                run_id=current_run_id(),
+            )

typevet/adapters/diagnostics/http_events.py

@@ -0,0 +1,91 @@
+"""Emit one terminal HTTP diagnostic per logical request when logging is configured.
+
+Unconfigured library calls stay silent. This module never opens a network sink;
+it only writes through the configured stderr renderer.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.http_events import http_request_event
+
+    with http_request_event(model="fake", path="v1/chat/completions") as event:
+        event.status_code = 200
+        event.outcome = "success"
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.fields][]: ``run_id`` and model field helpers
+    - [typevet.adapters.diagnostics.logs][]: Configures structlog before events emit
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+
+import structlog
+
+from typevet.adapters.diagnostics.fields import current_run_id, diagnostic_model
+
+
+@dataclass
+class HttpRequestEvent:
+    """Terminal HTTP metadata without prompts, schemas or response bodies.
+
+    Attributes:
+        status_code (int | None): HTTP status when the adapter knows it.
+        outcome (str): ``success`` or ``error`` after the request completes.
+
+    Examples:
+        ```python
+        from typevet.adapters.diagnostics.http_events import HttpRequestEvent
+
+        event = HttpRequestEvent(status_code=200, outcome="success")
+        assert event.status_code == 200
+        ```
+    """
+
+    status_code: int | None = None
+    outcome: str = "error"
+
+
+@contextmanager
+def http_request_event(
+    *,
+    model: str,
+    method: str = "POST",
+    path: str = "v1/chat/completions",
+) -> Iterator[HttpRequestEvent]:
+    """Yield mutable terminal metadata and emit ``http.request`` when configured.
+
+    Args:
+        model: Router model alias for the call.
+        method: HTTP method (for example ``POST``).
+        path: Path relative to the adapter base URL.
+
+    Yields:
+        Event state the adapter updates before the block exits.
+
+    Raises:
+        BaseException: Re-raises any exception from the wrapped block after
+            recording ``error_type`` on the terminal event.
+    """
+    event = HttpRequestEvent()
+    failure: BaseException | None = None
+    try:
+        yield event
+    except BaseException as exc:
+        failure = exc
+        raise
+    finally:
+        if structlog.is_configured():
+            structlog.get_logger().debug(
+                "http.request",
+                method=method,
+                path=path,
+                model=diagnostic_model(model),
+                status_code=event.status_code,
+                outcome=event.outcome,
+                error_type=None if failure is None else type(failure).__name__,
+                run_id=current_run_id(),
+            )

typevet/adapters/diagnostics/logs.py

@@ -0,0 +1,116 @@
+"""Configure stderr structlog diagnostics at the composition root.
+
+Logs are diagnostics, not telemetry: no automatic network export. Library
+imports stay silent until ``configure`` or ``configure_from_environ`` runs.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.logs import (
+        bind_run_id,
+        configure_from_environ,
+        new_run_id,
+    )
+
+    configure_from_environ()
+    bind_run_id(new_run_id())
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.http_events][]: HTTP terminal events
+    - [typevet.adapters.diagnostics.generation_events][]: Generation events
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import uuid
+from typing import Any
+
+import structlog
+from structlog.tracebacks import ExceptionDictTransformer
+
+from typevet.adapters.diagnostics.fields import filter_event_fields, set_run_id_context
+from typevet.adapters.diagnostics.redaction import make_redact_processor
+from typevet.adapters.diagnostics.settings import LogSettings, load_log_settings
+
+LEVELS = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+}
+_DICT_TRACEBACKS = structlog.processors.ExceptionRenderer(
+    ExceptionDictTransformer(show_locals=False)
+)
+
+
+def wants_json(settings: LogSettings, stream: Any) -> bool:
+    """Return true when lines should render as JSON objects.
+
+    Returns:
+        ``True`` when JSON rendering is selected explicitly or inferred from
+        a non-TTY stream under ``auto`` format.
+    """
+    if settings.format != "auto":
+        return settings.format == "json"
+    return not (hasattr(stream, "isatty") and stream.isatty())
+
+
+def configure(settings: LogSettings, stream: Any = None) -> None:
+    """Send structured diagnostics to stderr with redaction and field filters.
+
+    Args:
+        settings: Format, level and prompt logging policy.
+        stream: Output stream; defaults to ``sys.stderr``.
+    """
+    target = sys.stderr if stream is None else stream
+    redact = make_redact_processor(log_prompts=settings.log_prompts)
+    processors: list[Any] = [
+        structlog.contextvars.merge_contextvars,
+        filter_event_fields,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+    ]
+    if wants_json(settings, target):
+        processors += [_DICT_TRACEBACKS, redact, structlog.processors.JSONRenderer()]
+    else:
+        processors += [
+            redact,
+            structlog.dev.ConsoleRenderer(
+                exception_formatter=structlog.dev.plain_traceback
+            ),
+        ]
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(LEVELS[settings.level]),
+        logger_factory=structlog.PrintLoggerFactory(target),
+        cache_logger_on_first_use=False,
+    )
+
+
+def configure_from_environ(stream: Any = None) -> LogSettings:
+    """Load ``TYPEVET_LOG__*`` settings and configure stderr diagnostics once.
+
+    Returns:
+        The settings that were applied.
+    """
+    settings = load_log_settings()
+    configure(settings, stream=stream)
+    return settings
+
+
+def new_run_id() -> str:
+    """Return a short hex id that joins lines for one invocation.
+
+    Returns:
+        Twelve lowercase hex characters from a random UUID.
+    """
+    return uuid.uuid4().hex[:12]
+
+
+def bind_run_id(run_id: str) -> None:
+    """Bind ``run_id`` on every line until the context is cleared or replaced."""
+    structlog.contextvars.bind_contextvars(run_id=run_id)
+    set_run_id_context(run_id)

typevet/adapters/diagnostics/redaction.py

@@ -0,0 +1,94 @@
+"""Redact secrets and optional prompt content before stderr rendering.
+
+Examples:
+    ```python
+    from typevet.adapters.diagnostics.redaction import REDACTED, redact
+
+    assert redact(None, "info", {"api_key": "k"})["api_key"] == REDACTED
+    ```
+
+See Also:
+    - [typevet.adapters.diagnostics.logs][]: Installs the redact processor on configure
+    - [typevet.adapters.diagnostics.settings][]: ``log_prompts`` policy for prompt keys
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+REDACTED = "***"
+SECRET_KEYS = frozenset(
+    {
+        "api_key",
+        "authorization",
+        "password",
+        "private_key",
+        "private_key_pem",
+        "token",
+    }
+)
+PROMPT_KEYS = frozenset(
+    {
+        "content",
+        "messages",
+        "prompt",
+        "raw_text",
+        "system",
+        "user",
+    }
+)
+_SCALARS = (bool, int, float)
+_EXC_INFO = "exc_info"
+
+
+def _is_pem(value: str) -> bool:
+    return "-----BEGIN" in value
+
+
+def _redact_pair(key: Any, value: Any, *, log_prompts: bool) -> Any:
+    if isinstance(key, str):
+        lowered = key.lower()
+        if lowered in {k.lower() for k in SECRET_KEYS}:
+            return REDACTED
+        if not log_prompts and lowered in {k.lower() for k in PROMPT_KEYS}:
+            return REDACTED
+    return _mask(value, log_prompts=log_prompts)
+
+
+def _mask(value: Any, *, log_prompts: bool) -> Any:
+    if isinstance(value, str):
+        return REDACTED if _is_pem(value) else value
+    if value is None or isinstance(value, _SCALARS):
+        return value
+    if isinstance(value, dict):
+        return {
+            k: _redact_pair(k, v, log_prompts=log_prompts) for k, v in value.items()
+        }
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_mask(item, log_prompts=log_prompts) for item in value]
+    return type(value).__name__
+
+
+def make_redact_processor(
+    *, log_prompts: bool
+) -> Callable[[Any, str, dict[str, Any]], dict[str, Any]]:
+    """Build a structlog processor that masks secrets and optional prompts.
+
+    Args:
+        log_prompts: When false, prompt-like field names and long strings
+            are replaced with ``REDACTED``.
+
+    Returns:
+        A structlog-compatible processor callable.
+    """
+
+    def _redact_event(
+        _logger: Any, _method: str, event_dict: dict[str, Any]
+    ) -> dict[str, Any]:
+        return {
+            k: v if k == _EXC_INFO else _redact_pair(k, v, log_prompts=log_prompts)
+            for k, v in event_dict.items()
+        }
+
+    return _redact_event