responsible-request 0.4.0__py3-none-any.whl

responsible_request/logging.py

@@ -0,0 +1,183 @@
+"""Loguru-based logging: quiet console output plus structured per-request records.
+
+Per-request records are emitted at loguru's ``TRACE`` level with the record attached as
+``extra["rr_record"]`` (run manifests as ``extra["rr_run"]``), so they never show up in a normal
+console handler but can be picked up by any sink that filters for them (the JSONL and SQLite
+sinks below do exactly that).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sqlite3
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from .config import LogConfig
+from .logfiles import loguru_compression, strip_compression
+from .records import JSON_FIELDS, record_columns
+from .runs import RUN_COLUMNS, RUN_JSON_FIELDS
+
+PACKAGE = "responsible_request"
+
+_lock = threading.Lock()
+_sinks: dict[tuple[str, str], int] = {}  # (kind, resolved path) -> loguru handler id
+_console_handler: int | None = None
+
+
+def _is_record(record: Any) -> bool:
+    return "rr_record" in record["extra"]
+
+
+def _is_run(record: Any) -> bool:
+    return "rr_run" in record["extra"]
+
+
+def _is_structured(record: Any) -> bool:
+    return _is_record(record) or _is_run(record)
+
+
+def _is_console_message(record: Any) -> bool:
+    return not _is_structured(record)
+
+
+def runs_path(jsonl: str | Path) -> Path:
+    """Where run manifests go for a JSONL log: ``requests.jsonl`` -> ``requests.runs.jsonl``."""
+    path = strip_compression(Path(jsonl))
+    return path.with_name(f"{path.stem}.runs{path.suffix or '.jsonl'}")
+
+
+def _ensure_table(
+    conn: sqlite3.Connection, table: str, columns: tuple[str, ...] | list[str]
+) -> None:
+    cols = ", ".join(f'"{c}"' for c in columns)
+    conn.execute(f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
+    existing = {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
+    for col in columns:
+        if col not in existing:  # schema grew in a newer version
+            conn.execute(f'ALTER TABLE {table} ADD COLUMN "{col}"')
+
+
+class SQLiteSink:
+    """Loguru sink that inserts request records into a ``requests`` table and run manifests
+    into a ``runs`` table."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self._conn: sqlite3.Connection | None = None
+        self._columns = record_columns()
+
+    def _connect(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(self.path, check_same_thread=False)
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA synchronous=NORMAL")
+            _ensure_table(conn, "requests", self._columns)
+            _ensure_table(conn, "runs", RUN_COLUMNS)
+            conn.execute("CREATE INDEX IF NOT EXISTS requests_cache_key ON requests(cache_key)")
+            conn.commit()
+            self._conn = conn
+        return self._conn
+
+    def write(self, message: Any) -> None:
+        extra = message.record["extra"]
+        if "rr_run" in extra:
+            self._insert("runs", extra["rr_run"], RUN_COLUMNS, RUN_JSON_FIELDS)
+        else:
+            self._insert("requests", extra["rr_record"], self._columns, JSON_FIELDS)
+
+    def _insert(
+        self,
+        table: str,
+        data: dict[str, Any],
+        columns: tuple[str, ...] | list[str],
+        json_fields: tuple[str, ...],
+    ) -> None:
+        row = {
+            k: (json.dumps(v, default=str) if k in json_fields and v is not None else v)
+            for k, v in data.items()
+            if k in columns
+        }
+        conn = self._connect()
+        cols = ", ".join(f'"{c}"' for c in row)
+        marks = ", ".join("?" for _ in row)
+        conn.execute(f"INSERT INTO {table} ({cols}) VALUES ({marks})", list(row.values()))
+        conn.commit()
+
+    def stop(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+
+def setup_logging(config: LogConfig | None = None) -> None:
+    """Enable this package's log output and add the sinks requested in ``config``.
+
+    Safe to call repeatedly: a file or database is only attached once per process.
+    """
+    global _console_handler
+    config = config or LogConfig()
+    logger.enable(PACKAGE)
+    with _lock:
+        if config.console_level is not None and _console_handler is None:
+            with contextlib.suppress(ValueError):
+                logger.remove(0)  # loguru's default stderr handler, if still present
+            _console_handler = logger.add(
+                sys.stderr, level=config.console_level, filter=_is_console_message
+            )
+        if config.jsonl is not None:
+            key = ("jsonl", str(Path(config.jsonl).resolve()))
+            if key not in _sinks:
+                _sinks[key] = logger.add(
+                    config.jsonl,
+                    level="TRACE",
+                    filter=_is_record,
+                    format="{extra[rr_json]}",
+                    rotation=config.rotation,
+                    compression=loguru_compression(config.compression),
+                    enqueue=True,
+                )
+            runs = runs_path(config.jsonl)
+            key = ("jsonl", str(runs.resolve()))
+            if key not in _sinks:
+                _sinks[key] = logger.add(
+                    runs,
+                    level="TRACE",
+                    filter=_is_run,
+                    format="{extra[rr_json]}",
+                    enqueue=True,
+                )
+        if config.sqlite is not None:
+            key = ("sqlite", str(Path(config.sqlite).resolve()))
+            if key not in _sinks:
+                _sinks[key] = logger.add(
+                    SQLiteSink(config.sqlite),
+                    level="TRACE",
+                    filter=_is_structured,
+                    format="{message}",
+                    enqueue=True,
+                )
+
+
+def remove_sinks() -> None:
+    """Detach all JSONL/SQLite sinks added by :func:`setup_logging` (flushes pending writes)."""
+    with _lock:
+        for handler_id in _sinks.values():
+            logger.remove(handler_id)
+        _sinks.clear()
+
+
+def emit_record(data: dict[str, Any]) -> None:
+    logger.bind(rr_record=data, rr_json=json.dumps(data, default=str)).trace(
+        "request {} {} {} -> {}",
+        data.get("request_id"),
+        data.get("model") or "",
+        data.get("path"),
+        data.get("status_code"),
+    )

responsible_request/providers.py

@@ -0,0 +1,105 @@
+"""Extract provider-specific response metadata into the generic record fields.
+
+An extractor is called once per finished request with the record, the response headers and the
+parsed response body (the JSON body, the merged summary of a stream, or None if the body was not
+captured). It fills generic fields (``provider``, ``cost_usd``, ``gateway_request_id``,
+``upstream_duration_ms``, ...) and puts anything else into ``record.provider_meta``.
+
+All default extractors run on every response. Each one only fills fields when the headers or keys
+it knows are present, so no provider has to be configured. Add your own with
+``rr.AsyncOpenAI(extractors=[...])``::
+
+    def my_gateway(record, headers, body):
+        if "x-my-queue-ms" in headers:
+            rr.providers.meta(record, "my_gateway")["queue_ms"] = float(headers["x-my-queue-ms"])
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .records import RequestRecord
+
+Extractor = Callable[[RequestRecord, Mapping[str, str], "dict[str, Any] | None"], None]
+
+
+def meta(record: RequestRecord, namespace: str) -> dict[str, Any]:
+    """The ``provider_meta[namespace]`` dict of ``record``, created if missing."""
+    if record.provider_meta is None:
+        record.provider_meta = {}
+    section: dict[str, Any] = record.provider_meta.setdefault(namespace, {})
+    return section
+
+
+def _float(value: Any) -> float | None:
+    if value is None or isinstance(value, bool):
+        return None
+    with contextlib.suppress(TypeError, ValueError):
+        return float(value)
+    return None
+
+
+def openai_compat(
+    record: RequestRecord, headers: Mapping[str, str], body: dict[str, Any] | None
+) -> None:
+    """Request id headers of OpenAI and most OpenAI-compatible APIs."""
+    for name in ("x-request-id", "request-id"):
+        value = headers.get(name)
+        if value and record.gateway_request_id is None:
+            record.gateway_request_id = value
+    duration = _float(headers.get("openai-processing-ms"))
+    if duration is not None:
+        record.upstream_duration_ms = duration
+
+
+_LITELLM_PREFIX = "x-litellm-"
+
+
+def litellm(record: RequestRecord, headers: Mapping[str, str], body: dict[str, Any] | None) -> None:
+    """LiteLLM proxy headers: call id, duration, cost; all other ``x-litellm-*`` headers go to
+    ``provider_meta["litellm"]``."""
+    found = {
+        k.lower()[len(_LITELLM_PREFIX) :]: v
+        for k, v in headers.items()
+        if k.lower().startswith(_LITELLM_PREFIX)
+    }
+    if not found:
+        return
+    if found.get("call-id"):
+        record.gateway_request_id = found.pop("call-id")
+    duration = _float(found.pop("response-duration-ms", None))
+    if duration is not None:
+        record.upstream_duration_ms = duration
+    cost = _float(found.pop("response-cost", None))
+    if cost is not None:
+        record.cost_usd = cost
+    if found:
+        meta(record, "litellm").update({k.replace("-", "_"): v for k, v in found.items()})
+
+
+def openrouter(
+    record: RequestRecord, headers: Mapping[str, str], body: dict[str, Any] | None
+) -> None:
+    """OpenRouter and similar routers: upstream ``provider`` and ``usage.cost`` in the body."""
+    if not isinstance(body, dict):
+        return
+    if isinstance(body.get("provider"), str):
+        record.provider = body["provider"]
+    usage = body.get("usage")
+    if isinstance(usage, dict):
+        cost = _float(usage.get("cost"))
+        if cost is not None:
+            record.cost_usd = cost
+        extra = {k: usage[k] for k in ("is_byok", "cost_details") if usage.get(k) is not None}
+        if extra:
+            meta(record, "openrouter").update(extra)
+    choices = body.get("choices")
+    if isinstance(choices, list) and choices and isinstance(choices[0], dict):
+        native = choices[0].get("native_finish_reason")
+        if native is not None:
+            meta(record, "openrouter")["native_finish_reason"] = native
+
+
+DEFAULT_EXTRACTORS: tuple[Extractor, ...] = (openai_compat, litellm, openrouter)

responsible_request/records.py

@@ -0,0 +1,265 @@
+"""The per-request record and helpers to fill it from HTTP requests and responses."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from .config import LogConfig
+
+_tags: ContextVar[dict[str, Any] | None] = ContextVar("rr_tags", default=None)
+
+
+@contextmanager
+def tags(**values: Any) -> Iterator[None]:
+    """Attach ``values`` to the ``tags`` field of every request record created inside the block.
+
+    Example::
+
+        with rr.tags(experiment="baseline", item=17):
+            await client.chat.completions.create(...)
+    """
+    token = _tags.set({**(_tags.get() or {}), **values})
+    try:
+        yield
+    finally:
+        _tags.reset(token)
+
+
+def current_tags() -> dict[str, Any]:
+    return dict(_tags.get() or {})
+
+
+# Which record fields belong to which toggleable group. Fields not listed are core fields.
+GROUP_FIELDS: dict[str, tuple[str, ...]] = {
+    "timing": ("sent_at", "first_byte_at", "finished_at", "wait_s", "ttfb_s", "latency_s"),
+    "usage": (
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "cached_tokens",
+        "reasoning_tokens",
+        "cost_usd",
+    ),
+    "throttle": ("rpm", "state", "baseline", "load_ratio", "in_flight"),
+    "response_meta": (
+        "response_id",
+        "response_model",
+        "finish_reason",
+        "system_fingerprint",
+        "provider",
+        "gateway_request_id",
+        "upstream_duration_ms",
+        "provider_meta",
+    ),
+    "params": ("params",),
+    "request_body": ("request_body",),
+    "response_body": ("response_body",),
+}
+
+JSON_FIELDS = ("params", "request_body", "response_body", "tags", "provider_meta")
+
+
+def utc_iso(ts: float | None) -> str | None:
+    if ts is None:
+        return None
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat(timespec="milliseconds")
+
+
+@dataclass
+class RequestRecord:
+    """Everything recorded about one HTTP request (one attempt, SDK retries are separate)."""
+
+    request_id: str
+    timestamp: str | None  # when the request was issued (queued), UTC ISO 8601
+    method: str
+    path: str
+    model: str | None = None
+    stream: bool = False
+    attempt: int = 0
+    status_code: int | None = None
+    error: str | None = None
+    tags: dict[str, Any] = field(default_factory=dict)
+    cache_key: str | None = None  # hash of URL, JSON body and key tags (see CacheConfig)
+    cache_hit: bool = False  # served from the cache, not sent to the server
+    run_id: str | None = None  # links the record to its run manifest (see RunConfig)
+
+    # timing
+    sent_at: str | None = None
+    first_byte_at: str | None = None
+    finished_at: str | None = None
+    wait_s: float | None = None  # time spent waiting for the rate limiter
+    ttfb_s: float | None = None  # time to first response byte (≈ TTFT when streaming)
+    latency_s: float | None = None  # sent -> response fully received
+
+    # usage
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    cached_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    cost_usd: float | None = None  # reported by the provider or computed from CostConfig.prices
+
+    # throttle (state after this observation was processed)
+    rpm: float | None = None  # rate at which this request was sent
+    state: str | None = None
+    baseline: float | None = None
+    load_ratio: float | None = None
+    in_flight: int | None = None
+
+    # response metadata
+    response_id: str | None = None
+    response_model: str | None = None
+    finish_reason: str | None = None
+    system_fingerprint: str | None = None
+    provider: str | None = None  # upstream provider that served the request (e.g. via OpenRouter)
+    gateway_request_id: str | None = None  # request/call id assigned by the gateway or API
+    upstream_duration_ms: float | None = None  # processing time reported by the gateway
+    provider_meta: dict[str, Any] | None = None  # anything else extractors found
+
+    params: dict[str, Any] | None = None
+    request_body: Any = None
+    response_body: Any = None
+
+    def to_dict(self, config: LogConfig | None = None) -> dict[str, Any]:
+        data = asdict(self)
+        if config is not None:
+            for group, names in GROUP_FIELDS.items():
+                if not config.enabled(group):
+                    for name in names:
+                        data.pop(name, None)
+        return data
+
+
+def record_columns() -> list[str]:
+    return list(RequestRecord.__dataclass_fields__)
+
+
+# --------------------------------------------------------------------------- request parsing
+
+_BODY_KEYS = {"messages", "input", "prompt"}
+
+
+@dataclass
+class RequestInfo:
+    """What we could learn from an outgoing request body."""
+
+    model: str | None = None
+    stream: bool = False
+    uses_server_tools: bool = False
+    body: Any = None  # parsed JSON body (None for non-JSON bodies)
+
+    @property
+    def params(self) -> dict[str, Any] | None:
+        if not isinstance(self.body, dict):
+            return None
+        return {k: v for k, v in self.body.items() if k not in _BODY_KEYS}
+
+
+def parse_request_body(content: bytes, content_type: str | None) -> RequestInfo:
+    if not content or "json" not in (content_type or ""):
+        return RequestInfo()
+    try:
+        body = json.loads(content)
+    except ValueError:
+        return RequestInfo()
+    if not isinstance(body, dict):
+        return RequestInfo(body=body)
+    tools = body.get("tools") or []
+    server_tools = any(
+        isinstance(t, dict) and t.get("type") not in (None, "function", "custom") for t in tools
+    )
+    return RequestInfo(
+        model=body.get("model") if isinstance(body.get("model"), str) else None,
+        stream=bool(body.get("stream")),
+        uses_server_tools=server_tools,
+        body=body,
+    )
+
+
+# --------------------------------------------------------------------------- response parsing
+
+
+def apply_usage(record: RequestRecord, usage: Any) -> None:
+    if not isinstance(usage, dict):
+        return
+    record.prompt_tokens = usage.get("prompt_tokens", usage.get("input_tokens"))
+    record.completion_tokens = usage.get("completion_tokens", usage.get("output_tokens"))
+    record.total_tokens = usage.get("total_tokens")
+    prompt_details = usage.get("prompt_tokens_details") or usage.get("input_tokens_details") or {}
+    completion_details = (
+        usage.get("completion_tokens_details") or usage.get("output_tokens_details") or {}
+    )
+    if isinstance(prompt_details, dict):
+        record.cached_tokens = prompt_details.get("cached_tokens")
+    if isinstance(completion_details, dict):
+        record.reasoning_tokens = completion_details.get("reasoning_tokens")
+
+
+def apply_json_response(record: RequestRecord, body: Any) -> None:
+    if not isinstance(body, dict):
+        return
+    record.response_id = body.get("id") if isinstance(body.get("id"), str) else None
+    record.response_model = body.get("model") if isinstance(body.get("model"), str) else None
+    choices = body.get("choices")
+    if isinstance(choices, list) and choices and isinstance(choices[0], dict):
+        record.finish_reason = choices[0].get("finish_reason")
+    if isinstance(body.get("system_fingerprint"), str):
+        record.system_fingerprint = body["system_fingerprint"]
+    apply_usage(record, body.get("usage"))
+
+
+def parse_sse(text: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Parse an OpenAI-style SSE stream into its JSON events and a merged response summary."""
+    events: list[dict[str, Any]] = []
+    for line in text.splitlines():
+        if not line.startswith("data:"):
+            continue
+        data = line[5:].strip()
+        if not data or data == "[DONE]":
+            continue
+        try:
+            event = json.loads(data)
+        except ValueError:
+            continue
+        if isinstance(event, dict):
+            events.append(event)
+
+    summary: dict[str, Any] = {}
+    content: list[str] = []
+    reasoning: list[str] = []
+    for event in events:
+        for key in ("id", "model", "provider", "system_fingerprint"):
+            if isinstance(event.get(key), str):
+                summary[key] = event[key]
+        if event.get("usage"):
+            summary["usage"] = event["usage"]
+        choices = event.get("choices")
+        if isinstance(choices, list) and choices and isinstance(choices[0], dict):
+            choice = choices[0]
+            if choice.get("finish_reason"):
+                summary["finish_reason"] = choice["finish_reason"]
+            delta = choice.get("delta") or {}
+            if isinstance(delta, dict):
+                if isinstance(delta.get("content"), str):
+                    content.append(delta["content"])
+                for key in ("reasoning_content", "reasoning"):
+                    if isinstance(delta.get(key), str):
+                        reasoning.append(delta[key])
+    summary["content"] = "".join(content)
+    if reasoning:
+        summary["reasoning"] = "".join(reasoning)
+    return events, summary
+
+
+def apply_sse_response(record: RequestRecord, summary: dict[str, Any]) -> None:
+    record.response_id = summary.get("id")
+    record.response_model = summary.get("model")
+    record.finish_reason = summary.get("finish_reason")
+    record.system_fingerprint = summary.get("system_fingerprint")
+    apply_usage(record, summary.get("usage"))

responsible_request/runs.py

@@ -0,0 +1,116 @@
+"""Run manifests: what is needed to reproduce the requests of one client."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import platform
+import socket
+import subprocess
+import sys
+import time
+import uuid
+from collections.abc import Mapping
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from .config import RunConfig
+from .records import utc_iso
+
+RUN_COLUMNS = (
+    "run_id",
+    "name",
+    "started_at",
+    "endpoint",
+    "metadata",
+    "versions",
+    "platform",
+    "hostname",
+    "argv",
+    "cwd",
+    "git",
+    "config",
+)
+RUN_JSON_FIELDS = ("metadata", "versions", "argv", "git", "config")
+
+
+def _version(package: str) -> str | None:
+    try:
+        return version(package)
+    except PackageNotFoundError:
+        return None
+
+
+def _git(cwd: str) -> dict[str, Any] | None:
+    def run(*args: str) -> str:
+        return subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True, timeout=5, check=True
+        ).stdout.strip()
+
+    try:
+        commit = run("rev-parse", "HEAD")
+        dirty = bool(run("status", "--porcelain", "--untracked-files=no"))
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return {"commit": commit, "dirty": dirty}
+
+
+def _default(value: Any) -> Any:
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, (set, frozenset)):
+        return sorted(value, key=repr)
+    return repr(value)
+
+
+def to_jsonable(value: Any) -> Any:
+    """Dataclasses and mappings as plain JSON types (callables and other objects as ``repr``)."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        value = {f.name: getattr(value, f.name) for f in dataclasses.fields(value)}
+    if isinstance(value, Mapping):
+        return {str(k): to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v) for v in value]
+    return json.loads(json.dumps(value, default=_default))
+
+
+class Run:
+    """The run of one client: its ``run_id`` and the manifest written on the first request."""
+
+    def __init__(self, config: RunConfig | None = None, **configs: Any) -> None:
+        self.config = config or RunConfig()
+        self.run_id = uuid.uuid4().hex
+        cwd = os.getcwd()
+        self.manifest: dict[str, Any] = {
+            "run_id": self.run_id,
+            "name": self.config.name,
+            "started_at": utc_iso(time.time()),
+            "endpoint": None,
+            "metadata": to_jsonable(self.config.metadata),
+            "versions": {
+                "responsible_request": _version("responsible-request"),
+                "openai": _version("openai"),
+                "python": platform.python_version(),
+            },
+            "platform": platform.platform(),
+            "hostname": socket.gethostname(),
+            "argv": list(sys.argv),
+            "cwd": cwd,
+            "git": _git(cwd) if self.config.capture_git else None,
+            "config": to_jsonable(configs),
+        }
+        self.emitted = False
+
+    def emit(self, endpoint: str) -> None:
+        """Write the manifest (once), with the scheme and host of the first request."""
+        if self.emitted:
+            return
+        self.emitted = True
+        self.manifest["endpoint"] = endpoint
+        logger.bind(rr_run=self.manifest, rr_json=json.dumps(self.manifest)).trace(
+            "run {} started", self.run_id
+        )