devcopilot 0.2.0__py3-none-any.whl

core/openai_responses/tools.py

@@ -0,0 +1,374 @@
+"""Tool conversion helpers for the OpenAI Responses adapter."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .errors import ResponsesConversionError
+from .ids import new_call_id
+
+_MAX_ANTHROPIC_TOOL_NAME_LEN = 64
+_NAMESPACE_TOOL_SEPARATOR = "__"
+_UNSUPPORTED_PASSIVE_TOOL_TYPES = frozenset(
+    {"web_search", "image_generation", "tool_search"}
+)
+_INVALID_TOOL_NAME_CHARS = re.compile(r"[^A-Za-z0-9_-]+")
+
+
+@dataclass(frozen=True, slots=True)
+class ResponsesToolIdentity:
+    kind: Literal["function", "custom"]
+    name: str
+    namespace: str | None = None
+
+
+def convert_tools(value: Any) -> list[dict[str, Any]] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        raise ResponsesConversionError("Responses tools must be a list")
+
+    tools: list[dict[str, Any]] = []
+    for tool in value:
+        if not isinstance(tool, dict):
+            raise ResponsesConversionError(
+                f"Unsupported Responses tool: {type(tool).__name__}"
+            )
+        tool_type = tool.get("type")
+        if tool_type == "function":
+            tools.append(_convert_function_tool(tool, namespace=None))
+            continue
+        if tool_type == "custom":
+            tools.append(_convert_custom_tool(tool, namespace=None))
+            continue
+        if tool_type == "namespace":
+            tools.extend(_convert_namespace_tool(tool))
+            continue
+        if tool_type in _UNSUPPORTED_PASSIVE_TOOL_TYPES:
+            continue
+        if tool_type != "function":
+            raise ResponsesConversionError(
+                f"Unsupported Responses tool type: {tool_type!r}"
+            )
+    return tools
+
+
+def convert_tool_choice(value: Any) -> dict[str, Any] | None:
+    if value is None or value == "auto":
+        return None
+    if value == "none":
+        return None
+    if value == "required":
+        return {"type": "any"}
+    if isinstance(value, dict):
+        choice_type = value.get("type")
+        if choice_type == "function":
+            namespace = optional_str(value.get("namespace"))
+            name = required_str(value.get("name"), "tool_choice.name")
+            return {
+                "type": "tool",
+                "name": responses_tool_name_to_anthropic_name(
+                    name, namespace=namespace
+                ),
+            }
+        if choice_type == "custom":
+            source = _custom_source(value)
+            namespace = optional_str(source.get("namespace")) or optional_str(
+                value.get("namespace")
+            )
+            name = required_str(source.get("name"), "tool_choice.name")
+            return {
+                "type": "tool",
+                "name": responses_tool_name_to_anthropic_name(
+                    name, namespace=namespace
+                ),
+            }
+        if choice_type == "tool":
+            namespace = optional_str(value.get("namespace"))
+            name = optional_str(value.get("name"))
+            if name:
+                return {
+                    "type": "tool",
+                    "name": responses_tool_name_to_anthropic_name(
+                        name, namespace=namespace
+                    ),
+                }
+            return dict(value)
+        if choice_type in {"auto", "any"}:
+            return dict(value)
+    raise ResponsesConversionError(f"Unsupported Responses tool_choice: {value!r}")
+
+
+def responses_tool_name_to_anthropic_name(
+    name: str, *, namespace: str | None = None
+) -> str:
+    """Return a deterministic Anthropic tool name for a Responses tool identity."""
+
+    if not namespace:
+        return name
+    combined = (
+        f"{_tool_name_part(namespace)}"
+        f"{_NAMESPACE_TOOL_SEPARATOR}"
+        f"{_tool_name_part(name)}"
+    )
+    if len(combined) <= _MAX_ANTHROPIC_TOOL_NAME_LEN:
+        return combined
+    digest = hashlib.sha1(combined.encode("utf-8")).hexdigest()[:8]
+    prefix_len = _MAX_ANTHROPIC_TOOL_NAME_LEN - len(digest) - 1
+    return f"{combined[:prefix_len]}_{digest}"
+
+
+def responses_tool_identity_from_anthropic_name(
+    request: Mapping[str, Any], anthropic_name: str
+) -> ResponsesToolIdentity:
+    """Return the Responses namespace/name represented by an Anthropic tool name."""
+
+    tools = request.get("tools")
+    if not isinstance(tools, list):
+        return ResponsesToolIdentity(kind="function", name=anthropic_name)
+    for tool in tools:
+        if not isinstance(tool, dict):
+            continue
+        tool_type = tool.get("type")
+        if tool_type == "function":
+            source = tool.get("function")
+            function = source if isinstance(source, dict) else tool
+            if (name := optional_str(function.get("name"))) and (
+                responses_tool_name_to_anthropic_name(name) == anthropic_name
+            ):
+                return ResponsesToolIdentity(kind="function", name=name)
+            continue
+        if tool_type == "custom":
+            source = _custom_source(tool)
+            if (name := optional_str(source.get("name"))) and (
+                responses_tool_name_to_anthropic_name(name) == anthropic_name
+            ):
+                return ResponsesToolIdentity(kind="custom", name=name)
+            continue
+        if tool_type != "namespace":
+            continue
+        namespace = optional_str(tool.get("name"))
+        nested_tools = tool.get("tools")
+        if not namespace or not isinstance(nested_tools, list):
+            continue
+        for nested_tool in nested_tools:
+            if not isinstance(nested_tool, dict):
+                continue
+            nested_tool_type = nested_tool.get("type")
+            if nested_tool_type == "function":
+                source = nested_tool.get("function")
+                function = source if isinstance(source, dict) else nested_tool
+                if (name := optional_str(function.get("name"))) and (
+                    responses_tool_name_to_anthropic_name(name, namespace=namespace)
+                    == anthropic_name
+                ):
+                    return ResponsesToolIdentity(
+                        kind="function", name=name, namespace=namespace
+                    )
+                continue
+            if nested_tool_type == "custom":
+                source = _custom_source(nested_tool)
+                if (name := optional_str(source.get("name"))) and (
+                    responses_tool_name_to_anthropic_name(name, namespace=namespace)
+                    == anthropic_name
+                ):
+                    return ResponsesToolIdentity(
+                        kind="custom", name=name, namespace=namespace
+                    )
+    return ResponsesToolIdentity(kind="function", name=anthropic_name)
+
+
+def parse_arguments(value: Any) -> dict[str, Any]:
+    if value is None or value == "":
+        return {}
+    if isinstance(value, dict):
+        return value
+    if not isinstance(value, str):
+        raise ResponsesConversionError("Responses function_call arguments must be JSON")
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise ResponsesConversionError(
+            f"Responses function_call arguments are invalid JSON: {exc.msg}"
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise ResponsesConversionError(
+            "Responses function_call arguments must decode to an object"
+        )
+    return parsed
+
+
+def custom_tool_input_to_anthropic(value: Any) -> dict[str, str]:
+    return {"input": custom_tool_input_text(value)}
+
+
+def custom_tool_input_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return _json_dumps(value)
+
+
+def custom_tool_input_text_from_anthropic(value: Any) -> str:
+    if isinstance(value, Mapping):
+        raw_input = value.get("input")
+        if isinstance(raw_input, str):
+            return raw_input
+        if raw_input is not None:
+            return custom_tool_input_text(raw_input)
+        if not value:
+            return ""
+        return _json_dumps(value)
+    return custom_tool_input_text(value)
+
+
+def custom_tool_input_text_from_arguments(arguments: str) -> str:
+    if not arguments:
+        return ""
+    try:
+        parsed = json.loads(arguments)
+    except json.JSONDecodeError:
+        return arguments
+    return custom_tool_input_text_from_anthropic(parsed)
+
+
+def call_id_from_item(item: Mapping[str, Any]) -> str:
+    for key in ("call_id", "id"):
+        if value := optional_str(item.get(key)):
+            return value
+    return new_call_id()
+
+
+def required_str(value: Any, field_name: str) -> str:
+    if isinstance(value, str) and value:
+        return value
+    raise ResponsesConversionError(
+        f"Responses field {field_name} must be a non-empty string"
+    )
+
+
+def optional_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _convert_namespace_tool(tool: Mapping[str, Any]) -> list[dict[str, Any]]:
+    namespace = required_str(tool.get("name"), "tool.namespace.name")
+    nested_tools = tool.get("tools")
+    if not isinstance(nested_tools, list):
+        raise ResponsesConversionError(
+            f"Responses namespace tool {namespace!r} tools must be a list"
+        )
+
+    converted_tools: list[dict[str, Any]] = []
+    for nested_tool in nested_tools:
+        if not isinstance(nested_tool, dict):
+            raise ResponsesConversionError(
+                f"Unsupported Responses namespace tool: {type(nested_tool).__name__}"
+            )
+        nested_tool_type = nested_tool.get("type")
+        if nested_tool_type == "function":
+            converted_tools.append(
+                _convert_function_tool(nested_tool, namespace=namespace)
+            )
+            continue
+        if nested_tool_type == "custom":
+            converted_tools.append(
+                _convert_custom_tool(nested_tool, namespace=namespace)
+            )
+            continue
+        raise ResponsesConversionError(
+            f"Unsupported Responses namespace tool type: {nested_tool_type!r}"
+        )
+    return converted_tools
+
+
+def _convert_function_tool(
+    tool: Mapping[str, Any], *, namespace: str | None
+) -> dict[str, Any]:
+    function = tool.get("function")
+    source = function if isinstance(function, dict) else tool
+    name = required_str(source.get("name"), "tool.name")
+    schema = source.get("parameters")
+    if schema is None:
+        schema = {"type": "object", "properties": {}}
+    if not isinstance(schema, dict):
+        raise ResponsesConversionError(
+            f"Responses tool {name!r} parameters must be an object"
+        )
+    converted: dict[str, Any] = {
+        "name": responses_tool_name_to_anthropic_name(name, namespace=namespace),
+        "input_schema": schema,
+    }
+    if description := optional_str(source.get("description")):
+        converted["description"] = description
+    return converted
+
+
+def _convert_custom_tool(
+    tool: Mapping[str, Any], *, namespace: str | None
+) -> dict[str, Any]:
+    source = _custom_source(tool)
+    name = required_str(source.get("name"), "tool.name")
+    converted: dict[str, Any] = {
+        "name": responses_tool_name_to_anthropic_name(name, namespace=namespace),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "input": {
+                    "type": "string",
+                    "description": "Free-form input for the custom tool.",
+                }
+            },
+            "required": ["input"],
+        },
+    }
+    if description := _custom_tool_description(source):
+        converted["description"] = description
+    return converted
+
+
+def _custom_source(tool: Mapping[str, Any]) -> Mapping[str, Any]:
+    custom = tool.get("custom")
+    return custom if isinstance(custom, Mapping) else tool
+
+
+def _custom_tool_description(source: Mapping[str, Any]) -> str | None:
+    parts: list[str] = []
+    if description := optional_str(source.get("description")):
+        parts.append(description)
+    format_value = source.get("format")
+    if isinstance(format_value, Mapping):
+        format_type = optional_str(format_value.get("type"))
+        if format_type == "text":
+            parts.append("Custom tool input format: unconstrained text.")
+        elif format_type == "grammar":
+            syntax = optional_str(format_value.get("syntax"))
+            definition = optional_str(format_value.get("definition"))
+            guidance = "Custom tool input format: grammar"
+            if syntax:
+                guidance = f"{guidance} ({syntax})"
+            guidance = f"{guidance}: {definition}" if definition else f"{guidance}."
+            parts.append(guidance)
+        elif format_type:
+            parts.append(f"Custom tool input format: {format_type}.")
+        else:
+            parts.append(f"Custom tool input format: {_json_dumps(format_value)}")
+    return "\n\n".join(parts) if parts else None
+
+
+def _tool_name_part(value: str) -> str:
+    normalized = _INVALID_TOOL_NAME_CHARS.sub("_", value).strip("_")
+    return normalized or "tool"
+
+
+def _json_dumps(value: Any) -> str:
+    try:
+        return json.dumps(value)
+    except TypeError:
+        return str(value)

core/openai_responses/usage.py

@@ -0,0 +1,37 @@
+"""Usage helpers for OpenAI Responses payloads."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+_DISALLOWED_SPECIAL: tuple[str, ...] = ()
+
+
+class _TokenEncoder(Protocol):
+    def encode(
+        self, text: str, *, disallowed_special: tuple[str, ...]
+    ) -> list[int]: ...
+
+
+def _load_encoder() -> _TokenEncoder | None:
+    try:
+        import tiktoken
+    except ImportError:
+        return None
+
+    try:
+        return tiktoken.get_encoding("cl100k_base")
+    except ValueError:
+        return None
+
+
+_ENCODER = _load_encoder()
+
+
+def estimate_text_tokens(text: str) -> int:
+    """Return a best-effort token estimate for Responses usage details."""
+    if not text:
+        return 0
+    if _ENCODER is not None:
+        return len(_ENCODER.encode(text, disallowed_special=_DISALLOWED_SPECIAL))
+    return max(1, len(text) // 4)

core/rate_limit.py

@@ -0,0 +1,60 @@
+"""Shared strict sliding-window rate limiting primitives."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import deque
+
+
+class StrictSlidingWindowLimiter:
+    """Strict sliding window limiter.
+
+    Guarantees: at most ``rate_limit`` acquisitions in any interval of length
+    ``rate_window`` (seconds).
+
+    Implemented as an async context manager so call sites can do::
+
+        async with limiter:
+            ...
+    """
+
+    def __init__(self, rate_limit: int, rate_window: float) -> None:
+        if rate_limit <= 0:
+            raise ValueError("rate_limit must be > 0")
+        if rate_window <= 0:
+            raise ValueError("rate_window must be > 0")
+
+        self._rate_limit = int(rate_limit)
+        self._rate_window = float(rate_window)
+        self._times: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        while True:
+            wait_time = 0.0
+            async with self._lock:
+                now = time.monotonic()
+                cutoff = now - self._rate_window
+
+                while self._times and self._times[0] <= cutoff:
+                    self._times.popleft()
+
+                if len(self._times) < self._rate_limit:
+                    self._times.append(now)
+                    return
+
+                oldest = self._times[0]
+                wait_time = max(0.0, (oldest + self._rate_window) - now)
+
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+            else:
+                await asyncio.sleep(0)
+
+    async def __aenter__(self) -> StrictSlidingWindowLimiter:
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        return False

core/trace.py

@@ -0,0 +1,216 @@
+"""Structured TRACE events for end-to-end request / CLI / provider logging.
+
+Emitted lines are merged into JSON log rows by ``config.logging_config``.
+Conversation and Claude Code prompts are logged verbatim unless values live under
+sanitized credential keys (e.g. ``api_key``, ``authorization``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, AsyncIterator, Mapping
+from typing import Any
+
+from loguru import logger
+
+TRACE_PAYLOAD_BINDING = "trace_payload"
+
+_SECRET_VALUE_KEYS = frozenset(
+    k.lower()
+    for k in (
+        "authorization",
+        "x-api-key",
+        "anthropic-auth-token",
+        "api_key",
+        "password",
+        "secret",
+        "token",
+        "bearer_token",
+        "openapi_token",
+        "nvidia-api-key",
+    )
+)
+
+
+def _sanitize_trace_value(obj: Any) -> Any:
+    """Recursively copy JSON-like structures redacting credential-shaped keys."""
+    if isinstance(obj, Mapping):
+        out: dict[str, Any] = {}
+        for k, v in obj.items():
+            if str(k).lower() in _SECRET_VALUE_KEYS:
+                out[str(k)] = "<redacted>"
+            else:
+                out[str(k)] = _sanitize_trace_value(v)
+        return out
+    if isinstance(obj, tuple | list):
+        return [_sanitize_trace_value(x) for x in obj]
+    return obj
+
+
+def trace_event(*, stage: str, event: str, source: str, **fields: Any) -> None:
+    """Emit one structured TRACE row (merged into JSON by the log sink)."""
+    payload = _sanitize_trace_value(
+        {
+            "stage": stage,
+            "event": event,
+            "source": source,
+            **fields,
+        },
+    )
+    logger.bind(trace_payload=payload).info("TRACE {}", event)
+
+
+def api_messages_request_snapshot(req: Any) -> dict[str, Any]:
+    """Return a sanitized snapshot of an Anthropic ``MessagesRequest``-like body."""
+    if hasattr(req, "model_dump"):
+        data = req.model_dump(mode="python")
+    elif isinstance(req, Mapping):
+        data = dict(req)
+    else:
+        data = {}
+
+    snapshot: dict[str, Any] = {}
+    for key in (
+        "model",
+        "messages",
+        "system",
+        "tools",
+        "tool_choice",
+        "max_tokens",
+        "thinking",
+        "temperature",
+        "top_p",
+        "top_k",
+        "stop_sequences",
+        "metadata",
+        "stream",
+        "thinking_enabled",
+    ):
+        if key in data and data[key] is not None:
+            snapshot[key] = data[key]
+    return _sanitize_trace_value(snapshot)
+
+
+def extract_claude_session_id_from_headers(headers: Mapping[str, str]) -> str | None:
+    """Best-effort session id forwarded by Claude Code / SDK via HTTP."""
+    lowered = {str(k).lower(): v for k, v in headers.items() if isinstance(v, str)}
+    for key in (
+        "anthropic-session-id",
+        "x-anthropic-session-id",
+        "claude-session-id",
+        "x-claude-session-id",
+    ):
+        candidate = lowered.get(key)
+        if candidate:
+            return candidate
+    return None
+
+
+async def traced_async_stream(
+    agen: AsyncIterator[str],
+    *,
+    stage: str,
+    source: str,
+    complete_event: str,
+    interrupted_event: str,
+    chunk_event: str | None = None,
+    chunk_interval: int = 250,
+    extra: Mapping[str, Any] | None = None,
+) -> AsyncGenerator[str]:
+    """Emit TRACE rows when a text stream completes, fails, cancels, or periodically."""
+    common = dict(extra or {})
+    count = 0
+    nbytes = 0
+    interrupted = False
+    try:
+        async for chunk in agen:
+            count += 1
+            nbytes += len(chunk.encode("utf-8", errors="replace"))
+            if chunk_event and chunk_interval > 0 and count % chunk_interval == 0:
+                trace_event(
+                    stage=stage,
+                    event=chunk_event,
+                    source=source,
+                    stream_chunks_so_far=count,
+                    stream_bytes_so_far=nbytes,
+                    **common,
+                )
+            yield chunk
+    except GeneratorExit:
+        raise
+    except asyncio.CancelledError:
+        interrupted = True
+        trace_event(
+            stage=stage,
+            event=interrupted_event,
+            source=source,
+            stream_chunks=count,
+            stream_bytes=nbytes,
+            outcome="cancelled",
+            **common,
+        )
+        raise
+    except BaseExceptionGroup as grp:
+        interrupted = True
+        trace_event(
+            stage=stage,
+            event=interrupted_event,
+            source=source,
+            stream_chunks=count,
+            stream_bytes=nbytes,
+            outcome="exception_group",
+            note=str(grp),
+            **common,
+        )
+        raise
+    except Exception as exc:
+        interrupted = True
+        trace_event(
+            stage=stage,
+            event=interrupted_event,
+            source=source,
+            stream_chunks=count,
+            stream_bytes=nbytes,
+            outcome="error",
+            exc_type=type(exc).__name__,
+            **common,
+        )
+        raise
+
+    if not interrupted:
+        trace_event(
+            stage=stage,
+            event=complete_event,
+            source=source,
+            stream_chunks=count,
+            stream_bytes=nbytes,
+            outcome="ok",
+            **common,
+        )
+
+
+def provider_chat_body_snapshot(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Sanitized OpenAI-compat chat body subset for traces (conversation text verbatim)."""
+    keys = ("model", "messages", "tools", "tool_choice", "temperature", "max_tokens")
+    snap = {k: body[k] for k in keys if k in body and body[k] is not None}
+    return _sanitize_trace_value(snap)
+
+
+def provider_native_messages_body_snapshot(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Sanitized Anthropic Messages API body subset for traces."""
+    keys = (
+        "model",
+        "messages",
+        "system",
+        "tools",
+        "tool_choice",
+        "max_tokens",
+        "thinking",
+        "metadata",
+        "temperature",
+        "top_p",
+        "top_k",
+        "stop_sequences",
+    )
+    snap = {k: body[k] for k in keys if k in body and body[k] is not None}
+    return _sanitize_trace_value(snap)