withlore 0.2.0a14__py3-none-any.whl

withlore/__init__.py

@@ -0,0 +1,67 @@
+"""Lore tracing for Python AI applications."""
+
+from . import qa as qa
+from ._capture import DROP, CaptureMode
+from ._config import LoreConfig
+from ._evals import (
+    Case,
+    Dataset,
+    EvalItem,
+    EvalResult,
+    EvalScore,
+    Score,
+    ScorerContext,
+    evaluate,
+    evaluate_async,
+    exact_match,
+    llm_judge,
+)
+from ._runtime import (
+    diagnostics,
+    flush,
+    init,
+    instrument,
+    shutdown,
+    span,
+    trace,
+)
+from ._terminal import print_eval_report
+from ._version import __version__ as __version__
+from .client import Client, LoreError
+
+__all__ = [
+    "AssetRef",
+    "CaptureClient",
+    "CapturePolicy",
+    "DeliveryReceipt",
+    "FileSink",
+    "Image",
+    "Text",
+    "DROP",
+    "CaptureMode",
+    "Client",
+    "LoreError",
+    "Case",
+    "Dataset",
+    "EvalItem",
+    "EvalResult",
+    "EvalScore",
+    "LoreConfig",
+    "Score",
+    "ScorerContext",
+    "diagnostics",
+    "evaluate",
+    "evaluate_async",
+    "exact_match",
+    "flush",
+    "init",
+    "instrument",
+    "llm_judge",
+    "print_eval_report",
+    "qa",
+    "shutdown",
+    "span",
+    "trace",
+]
+
+from .capture import AssetRef, CaptureClient, CapturePolicy, DeliveryReceipt, FileSink, Image, Text

withlore/_capture.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import dataclasses
+import enum
+import json
+import re
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+
+class CaptureMode(str, enum.Enum):
+    FULL = "full"
+    METADATA_ONLY = "metadata_only"
+
+
+class _DropValue:
+    pass
+
+
+DROP = _DropValue()
+Redactor = Callable[[str, Any], Any | _DropValue]
+
+_SECRET_KEY = re.compile(
+    r"(?:^|[._-])(?:api[-_]?key|authorization|cookie|credential|password|secret|"
+    r"access[-_]?token|refresh[-_]?token|id[-_]?token)(?:$|[._-])",
+    re.IGNORECASE,
+)
+
+
+def _sanitize(value: Any, *, redactor: Redactor | None = None, key: str = "") -> Any:
+    """Convert a value to JSON-safe data while removing obvious secrets."""
+
+    if value is DROP:
+        return DROP
+
+    if key and _SECRET_KEY.search(key):
+        return "[REDACTED]"
+
+    if redactor is not None:
+        value = redactor(key, value)
+        if value is DROP:
+            return DROP
+
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+
+    if isinstance(value, bytes):
+        return {"type": "bytes", "size": len(value)}
+
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        value = dataclasses.asdict(value)
+
+    if isinstance(value, Mapping):
+        result: dict[str, Any] = {}
+        for raw_key, item in value.items():
+            item_key = str(raw_key)
+            safe_key = sanitize(item_key, redactor=redactor, key="attribute.key")
+            if not isinstance(safe_key, str):
+                continue
+            sanitized = sanitize(item, redactor=redactor, key=item_key)
+            if sanitized is not DROP:
+                result[safe_key] = sanitized
+        return result
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [
+            sanitized
+            for item in value
+            if (sanitized := sanitize(item, redactor=redactor, key=key)) is not DROP
+        ]
+
+    if hasattr(value, "model_dump"):
+        return sanitize(value.model_dump(mode="json"), redactor=redactor, key=key)
+
+    if hasattr(value, "to_dict"):
+        return sanitize(value.to_dict(), redactor=redactor, key=key)
+
+    return sanitize(repr(value), redactor=redactor, key=key)
+
+
+def sanitize(value: Any, *, redactor: Redactor | None = None, key: str = "") -> Any:
+    """Fail closed when a redactor or custom value cannot be safely serialized.
+
+    Named secret fields are removed automatically. Detecting arbitrary sensitive
+    text requires an application redactor; no general PII detection is implied.
+    """
+    try:
+        return _sanitize(value, redactor=redactor, key=key)
+    except Exception:
+        return DROP
+
+
+def encode(value: Any, *, redactor: Redactor | None = None, limit: int) -> tuple[str, bool]:
+    sanitized = sanitize(value, redactor=redactor)
+    if sanitized is DROP:
+        sanitized = "[REDACTED]"
+    encoded = json.dumps(sanitized, separators=(",", ":"), ensure_ascii=False, default=repr)
+    encoded_bytes = encoded.encode("utf-8", errors="replace")
+    encoded = encoded_bytes.decode("utf-8")
+    if len(encoded_bytes) <= limit:
+        return encoded, False
+
+    marker = "...[truncated]"
+    preview = encoded_bytes[:limit].decode("utf-8", errors="ignore")
+    while preview:
+        truncated_value = json.dumps(preview + marker, ensure_ascii=False)
+        if len(truncated_value.encode("utf-8")) <= limit:
+            return truncated_value, True
+        preview = preview[:-1]
+    return json.dumps(marker[: max(0, limit - 2)]), True

withlore/_capture_io.py

@@ -0,0 +1,140 @@
+"""Bounded ordered capture I/O. No backend or agent runtime dependencies."""
+
+from __future__ import annotations
+
+import os
+import queue
+import threading
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any, BinaryIO
+
+
+class DurableIO:
+    """One ordered worker; producer callbacks never wait on filesystem writes."""
+
+    def __init__(
+        self,
+        background: bool = True,
+        maximum_bytes: int = 4_000_000,
+        maximum_operations: int = 4096,
+        close_timeout: float = 10.0,
+    ) -> None:
+        if maximum_bytes < 1 or maximum_operations < 1 or close_timeout <= 0:
+            raise ValueError("Capture I/O limits must be positive")
+        self.background, self.maximum_bytes = background, maximum_bytes
+        self.close_timeout = close_timeout
+        self.pending_bytes = 0
+        self.failure: BaseException | None = None
+        self.lock = threading.RLock()
+        self.queue: queue.Queue[tuple[Callable[[], Any], int] | None] = queue.Queue(
+            maximum_operations
+        )
+        self.closed = False
+        self.thread = threading.Thread(target=self._consume, name="withlore-capture", daemon=True)
+        if background:
+            self.thread.start()
+
+    def check(self) -> None:
+        if self.failure is not None:
+            raise OSError("Capture persistence failed; evidence is incomplete") from None
+
+    def submit(self, action: Callable[[], Any], size: int = 0) -> None:
+        with self.lock:
+            self.check()
+            if self.closed:
+                raise OSError("Capture writer is closed")
+            if size < 0 or self.pending_bytes + size > self.maximum_bytes:
+                raise OSError("Capture backlog byte limit exceeded")
+            if not self.background:
+                action()
+                return
+            self.pending_bytes += size
+            try:
+                self.queue.put_nowait((action, size))
+            except queue.Full:
+                self.pending_bytes -= size
+                raise OSError("Capture backlog operation limit exceeded") from None
+
+    def _consume(self) -> None:
+        while True:
+            item = self.queue.get()
+            try:
+                if item is None:
+                    return
+                action, size = item
+                try:
+                    action()
+                except BaseException as error:
+                    self.failure = error
+                finally:
+                    with self.lock:
+                        self.pending_bytes -= size
+            finally:
+                self.queue.task_done()
+
+    def write(self, stream: BinaryIO, data: bytes) -> None:
+        owned = bytes(data)
+        self.submit(lambda: stream.write(owned), len(owned))
+
+    def append(self, path: Path, data: bytes) -> None:
+        owned = bytes(data)
+
+        def action() -> None:
+            with path.open("ab") as stream:
+                stream.write(owned)
+                stream.flush()
+                os.fsync(stream.fileno())
+
+        self.submit(action, len(owned))
+
+    def flush(
+        self,
+        streams: Iterable[BinaryIO] = (),
+        *,
+        durable: bool = False,
+        checkpoint: Callable[[], None] = lambda: None,
+    ) -> None:
+        handles = tuple(streams)
+
+        def action() -> None:
+            for stream in handles:
+                stream.flush()
+                if durable:
+                    os.fsync(stream.fileno())
+            checkpoint()
+
+        self.submit(action)
+
+    def drain(self, timeout: float | None = None) -> None:
+        deadline = time.monotonic() + (self.close_timeout if timeout is None else timeout)
+        if self.background:
+            with self.queue.all_tasks_done:
+                while self.queue.unfinished_tasks:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        raise TimeoutError("Capture drain deadline exceeded")
+                    self.queue.all_tasks_done.wait(remaining)
+        self.check()
+
+    def close(self, timeout: float | None = None) -> None:
+        duration = self.close_timeout if timeout is None else timeout
+        deadline = time.monotonic() + duration
+        if self.closed:
+            self.check()
+            return
+        try:
+            self.drain(duration)
+        finally:
+            with self.lock:
+                self.closed = True
+            if self.background:
+                try:
+                    self.queue.put(None, timeout=max(0, deadline - time.monotonic()))
+                except queue.Full:
+                    raise TimeoutError("Capture close deadline exceeded") from None
+                self.thread.join(max(0, deadline - time.monotonic()))
+                if self.thread.is_alive():
+                    raise TimeoutError("Capture close deadline exceeded")
+        self.check()

withlore/_config.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+from ._capture import CaptureMode, Redactor
+
+DEFAULT_ENDPOINT = "https://lore-labs.ai/api/v1/traces"
+
+
+def _endpoint(value: str | None, project_id: str | None) -> str:
+    endpoint = (value or os.getenv("LORE_ENDPOINT") or DEFAULT_ENDPOINT).rstrip("/")
+    if project_id:
+        suffix = f"/v2/projects/{quote(project_id, safe='')}/traces"
+        if endpoint.endswith(suffix):
+            return endpoint
+        if endpoint.endswith("/v1/traces"):
+            endpoint = endpoint.removesuffix("/v1/traces")
+        return f"{endpoint}{suffix}"
+    if endpoint.endswith("/v1/traces"):
+        return endpoint
+    return f"{endpoint}/v1/traces"
+
+
+@dataclass(frozen=True, slots=True)
+class LoreConfig:
+    api_key: str = field(repr=False)
+    endpoint: str = DEFAULT_ENDPOINT
+    project_id: str | None = None
+    environment: str = "development"
+    capture_mode: CaptureMode = CaptureMode.METADATA_ONLY
+    redactor: Redactor | None = field(default=None, compare=False, repr=False)
+    instrumentations: tuple[str, ...] = ("auto",)
+    max_value_bytes: int = 256 * 1024
+    max_queue_size: int = 2_048
+    max_export_batch_size: int = 128
+    schedule_delay_millis: int = 5_000
+    export_timeout_millis: int = 10_000
+
+    @classmethod
+    def load(
+        cls,
+        *,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        project_id: str | None = None,
+        environment: str | None = None,
+        capture_content: bool = False,
+        redactor: Redactor | None = None,
+        instrumentations: str | Iterable[str] = "auto",
+    ) -> LoreConfig:
+        resolved_key = (api_key or os.getenv("LORE_API_KEY") or "").strip()
+        if not resolved_key:
+            raise ValueError("Lore API key is required; pass api_key or set LORE_API_KEY")
+
+        resolved_environment = (
+            environment or os.getenv("LORE_ENVIRONMENT") or "development"
+        ).strip()
+        if not resolved_environment:
+            raise ValueError("Lore environment cannot be empty")
+
+        resolved_project_id = (project_id or os.getenv("LORE_PROJECT_ID") or "").strip() or None
+        if resolved_project_id and "/" in resolved_project_id:
+            raise ValueError("Lore project ID cannot contain a slash")
+
+        selected = (
+            (instrumentations,) if isinstance(instrumentations, str) else tuple(instrumentations)
+        )
+
+        return cls(
+            api_key=resolved_key,
+            endpoint=_endpoint(endpoint, resolved_project_id),
+            project_id=resolved_project_id,
+            environment=resolved_environment,
+            capture_mode=CaptureMode.FULL if capture_content else CaptureMode.METADATA_ONLY,
+            redactor=redactor,
+            instrumentations=selected,
+        )