iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/llm/openai_timestamps.py

@@ -0,0 +1,57 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Timestamp helpers for OpenAI-compatible chat-completion payloads."""
+
+from __future__ import annotations
+
+from copy import copy
+from datetime import UTC, datetime
+from typing import Any
+
+_MILLISECOND_TIMESTAMP_MIN = 1_000_000_000_000
+_MILLISECOND_TIMESTAMP_MAX = 10_000_000_000_000
+
+
+def normalize_openai_created_timestamp(value: Any) -> Any:
+    """Return seconds for OpenAI-compatible ``created`` timestamps.
+
+    The OpenAI Chat Completions schema uses Unix seconds, but some compatible
+    providers return Unix milliseconds.  Limit conversion to current 13-digit
+    integer timestamps so ordinary 10-digit OpenAI seconds stay byte-for-byte
+    on the fast path.
+    """
+    if (
+        isinstance(value, int)
+        and not isinstance(value, bool)
+        and _MILLISECOND_TIMESTAMP_MIN <= value < _MILLISECOND_TIMESTAMP_MAX
+    ):
+        return value / 1000
+    return value
+
+
+def openai_created_at_iso(value: Any) -> str:
+    """Format an OpenAI-compatible ``created`` value as an ISO timestamp."""
+    created = normalize_openai_created_timestamp(value)
+    return datetime.fromtimestamp(created, tz=UTC).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def normalize_openai_created_payload(payload: Any) -> Any:
+    """Return a payload copy with normalized ``created`` when needed.
+
+    Chrys reads ``payload.created`` internally, so it normalizes
+    only the copied value that reaches the parser.  The original SDK object is
+    left untouched for callers that still need to inspect the raw provider
+    payload.
+    """
+    created = payload.created
+    normalized = normalize_openai_created_timestamp(created)
+    if normalized == created:
+        return payload
+
+    model_copy = getattr(payload, "model_copy", None)
+    if callable(model_copy):
+        return model_copy(update={"created": normalized})
+
+    cloned = copy(payload)
+    cloned.created = normalized
+    return cloned

chrys/service/llm/providers.py

@@ -0,0 +1,107 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""What Chrys knows about each provider id, as data.
+
+The client factory reads its credentials and endpoint fallbacks from this
+table, the Chat Completions clients take their output-cap parameter from it,
+and the Models screen labels its form from it. It imports no provider SDK:
+labelling a form must not load one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, Literal
+
+from chrys.service.profiles.models.schema import API_STYLE_CHAT_COMPLETIONS, API_STYLE_RESPONSES
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+type SdkFamily = Literal["openai", "anthropic"]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderSpec:
+    """One provider id's SDK, credentials, endpoint and wire-dialect facts."""
+
+    label: str
+    """Provider name in configuration errors."""
+    sdk: SdkFamily
+    """Which provider SDK carries the requests."""
+    api_key_env: str
+    """Environment variable consulted when the profile carries no API key."""
+    base_url_env: str
+    """Environment variable consulted when the profile carries no base URL."""
+    default_base_url: str
+    """The endpoint used when neither the profile nor the environment names one."""
+    native_sdk: bool
+    """The SDK is the provider's own and applies the default endpoint itself.
+
+    The client factory then leaves the base URL to the SDK instead of passing
+    ``default_base_url``.
+    """
+    api_styles: frozenset[str] | None
+    """Wire APIs the provider speaks; None when it ignores ``api_style``."""
+    chat_completions_max_output_param: str | None
+    """Chat Completions parameter that carries the output-token cap."""
+
+
+_BOTH_API_STYLES: Final = frozenset({API_STYLE_CHAT_COMPLETIONS, API_STYLE_RESPONSES})
+
+PROVIDERS: Final[dict[str, ProviderSpec]] = {
+    "anthropic": ProviderSpec(
+        label="Anthropic",
+        sdk="anthropic",
+        api_key_env="ANTHROPIC_API_KEY",
+        base_url_env="ANTHROPIC_BASE_URL",
+        default_base_url="https://api.anthropic.com",
+        native_sdk=True,
+        api_styles=None,
+        chat_completions_max_output_param=None,
+    ),
+    "openai": ProviderSpec(
+        label="OpenAI",
+        sdk="openai",
+        api_key_env="OPENAI_API_KEY",
+        base_url_env="OPENAI_BASE_URL",
+        default_base_url="https://api.openai.com/v1",
+        native_sdk=True,
+        api_styles=_BOTH_API_STYLES,
+        # Real OpenAI hard-rejects the legacy ``max_tokens`` spelling on current models.
+        chat_completions_max_output_param="max_completion_tokens",
+    ),
+    "deepseek-openai": ProviderSpec(
+        label="DeepSeek",
+        sdk="openai",
+        api_key_env="DEEPSEEK_API_KEY",
+        base_url_env="DEEPSEEK_BASE_URL",
+        default_base_url="https://api.deepseek.com",
+        native_sdk=False,
+        api_styles=_BOTH_API_STYLES,
+        # This OpenAI-compatible endpoint documents only the legacy spelling.
+        chat_completions_max_output_param="max_tokens",
+    ),
+    "glm-openai": ProviderSpec(
+        label="GLM",
+        sdk="openai",
+        api_key_env="ZAI_API_KEY",
+        base_url_env="ZAI_BASE_URL",
+        default_base_url="https://open.bigmodel.cn/api/paas/v4",
+        native_sdk=False,
+        api_styles=None,
+        # This OpenAI-compatible endpoint documents only the legacy spelling.
+        chat_completions_max_output_param="max_tokens",
+    ),
+}
+
+# Built once at import; the Chat Completions classes bind their parameter from
+# it when they are defined, so a later change to PROVIDERS does not reach them.
+CHAT_COMPLETIONS_TOKEN_LIMIT_PARAMS: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        name: spec.chat_completions_max_output_param
+        for name, spec in PROVIDERS.items()
+        if spec.chat_completions_max_output_param is not None
+    }
+)

chrys/service/llm/proxy_route.py

@@ -0,0 +1,54 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Which proxy an LLM HTTP client sends a URL through.
+
+Both SDK default clients route by the same table httpx builds: the
+environment's proxy map (``HTTP(S)_PROXY``, ``ALL_PROXY``, ``NO_PROXY``) with
+the client's explicit mounts laid over it, sorted most specific first, first
+match wins.  :class:`ProxyRouter` rebuilds that table once, when the client is
+built, so a request hook can name its first hop without reaching into the
+client's transports.  ``tests/service/llm/test_proxy_route_contract.py`` pins
+it to ``httpx.AsyncClient._transport_for_url`` for both SDKs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from chrys.foundation.errors import Origin, origin_of
+from chrys.foundation.util.httpx_helpers import BYPASS_PROXY_MOUNTS
+
+if TYPE_CHECKING:
+    import httpx
+    from httpx._utils import URLPattern
+
+
+@dataclass(frozen=True, slots=True)
+class ProxyRouter:
+    """A client's proxy table: URL patterns, most specific first, to a proxy origin or direct."""
+
+    routes: tuple[tuple[URLPattern, Origin | None], ...]
+
+    @classmethod
+    def from_client_config(cls, *, bypass_proxy: bool) -> ProxyRouter:
+        """Build the table the client built at the same moment from the same environment.
+
+        Call it next to the client's construction: httpx and the SDKs read the
+        proxy environment once, when the client is built.
+        """
+        from httpx._utils import URLPattern, get_environment_proxies
+
+        table: dict[URLPattern, Origin | None] = {
+            URLPattern(key): None if url is None else origin_of(url) for key, url in get_environment_proxies().items()
+        }
+        if bypass_proxy:
+            table.update({URLPattern(key): None for key in BYPASS_PROXY_MOUNTS})
+        return cls(tuple(sorted(table.items())))
+
+    def proxy_for(self, url: httpx.URL) -> Origin | None:
+        """Return the proxy *url* goes through (credentials never kept), or None when it goes direct."""
+        for pattern, proxy in self.routes:
+            if pattern.matches(url):
+                return proxy
+        return None

chrys/service/llm/raw_http_log.py

@@ -0,0 +1,309 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Raw LLM HTTP request/response logging.
+
+Enabled with ``CHRYS_DEBUG_LLM_RAW_HTTP_LOG=1``.  This is intentionally separate
+from OpenTelemetry: OTel records semantic GenAI events, while this module
+captures the full HTTP request and response payloads seen by the provider
+SDK's httpx client.
+
+The log is unredacted by design.  It contains API keys, prompts, tool
+arguments, and model responses, so it must remain strictly opt-in.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Final
+from uuid import uuid4
+
+import httpx
+
+from chrys.foundation.util.chrys_headers import SESSION_ID_HEADER, X_SESSION_ID_HEADER
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from chrys.service.profiles.models.schema import ModelProfile
+
+logger = logging.getLogger(__name__)
+
+RAW_HTTP_LOG_ENV: Final[str] = "CHRYS_DEBUG_LLM_RAW_HTTP_LOG"
+"""Legacy alias for ``log.raw_http_capture``, kept for the docstring above."""
+RAW_HTTP_LOG_FILE: Final[str] = "llm_raw_http.jsonl"
+_EXCHANGE_ID_EXTENSION: Final[str] = "chrys_raw_http_exchange_id"
+_SESSION_ID_EXTENSION: Final[str] = "chrys_raw_http_session_id"
+_WRITE_LOCK = threading.Lock()
+
+
+def raw_http_logging_enabled() -> bool:
+    """Return True when full LLM HTTP logging is switched on for this process."""
+    from chrys.foundation.config.process_settings import process_settings
+
+    return process_settings().raw_http_capture
+
+
+def raw_http_log_path(session_id: str | None, session_dir: Path | None) -> Path | None:
+    """Return the session-scoped raw HTTP log path when logging is enabled."""
+    if not raw_http_logging_enabled():
+        return None
+    if session_dir is not None:
+        return session_dir / RAW_HTTP_LOG_FILE
+    if not session_id:
+        return None
+
+    from chrys.foundation.config.settings import resolve_sessions_dir
+    from chrys.foundation.util.session_ids import session_short_id
+
+    return resolve_sessions_dir() / session_short_id(session_id) / RAW_HTTP_LOG_FILE
+
+
+def build_raw_http_event_hooks(
+    *,
+    log_path: Path,
+    profile: ModelProfile,
+    session_id: str | None,
+) -> dict[str, list[Callable[..., Any]]]:
+    """Build async httpx event hooks that append raw request/response JSONL."""
+
+    async def _request_hook(request: httpx.Request) -> None:
+        exchange_id = uuid4().hex
+        request_session_id = _request_session_id(request, fallback=session_id)
+        request.extensions[_EXCHANGE_ID_EXTENSION] = exchange_id
+        request.extensions[_SESSION_ID_EXTENSION] = request_session_id
+        try:
+            body = await request.aread()
+            body_record = _body_to_record(body)
+        except Exception as exc:
+            body_record = {"read_error": type(exc).__name__, "message": str(exc)}
+        await _append_record_async(
+            log_path,
+            {
+                "timestamp": _timestamp(),
+                "event": "request",
+                "exchange_id": exchange_id,
+                "session_id": request_session_id,
+                "model_profile": _profile_record(profile),
+                "request": {
+                    "method": request.method,
+                    "url": str(request.url),
+                    "headers": _headers_to_record(request.headers),
+                    "body": body_record,
+                },
+            },
+        )
+
+    async def _response_hook(response: httpx.Response) -> None:
+        exchange_id = response.request.extensions.get(_EXCHANGE_ID_EXTENSION)
+        if not isinstance(exchange_id, str):
+            exchange_id = uuid4().hex
+        response_session_id = response.request.extensions.get(_SESSION_ID_EXTENSION)
+        if not isinstance(response_session_id, str):
+            response_session_id = session_id
+        response_record: dict[str, Any] = {
+            "status_code": response.status_code,
+            "reason_phrase": response.reason_phrase,
+            "headers": _headers_to_record(response.headers),
+        }
+        # Mock transports and some custom transports may return an already
+        # buffered response.  Real network responses normally reach this hook
+        # before ``AsyncClient.send(stream=False)`` performs its final read.
+        if hasattr(response, "_content"):
+            response_record["body"] = _body_to_record(response.content)
+            await _append_response_record(log_path, profile, response_session_id, exchange_id, response_record)
+            return
+        response.stream = _RawLogAsyncByteStream(
+            stream=response.stream,
+            log_path=log_path,
+            profile=profile,
+            session_id=response_session_id,
+            exchange_id=exchange_id,
+            response_record=response_record,
+        )
+
+    return {"request": [_request_hook], "response": [_response_hook]}
+
+
+def _request_session_id(request: httpx.Request, *, fallback: str | None) -> str | None:
+    """Return the final wire session id stamped on this request."""
+    return request.headers.get(X_SESSION_ID_HEADER) or request.headers.get(SESSION_ID_HEADER) or fallback
+
+
+class _RawLogAsyncByteStream(httpx.AsyncByteStream):
+    """Tee response bytes into the raw log without pre-consuming streams."""
+
+    def __init__(
+        self,
+        *,
+        stream: httpx.AsyncByteStream,
+        log_path: Path,
+        profile: ModelProfile,
+        session_id: str | None,
+        exchange_id: str,
+        response_record: dict[str, Any],
+    ) -> None:
+        self._stream = stream
+        self._log_path = log_path
+        self._profile = profile
+        self._session_id = session_id
+        self._exchange_id = exchange_id
+        self._response_record = response_record
+        self._chunks = bytearray()
+        self._logged = False
+
+    async def __aiter__(self):
+        try:
+            async for chunk in self._stream:
+                self._chunks.extend(chunk)
+                yield chunk
+        except Exception as exc:
+            await self._log_once({"read_error": type(exc).__name__, "message": str(exc)})
+            raise
+        else:
+            await self._log_once(_body_to_record(bytes(self._chunks)))
+
+    async def aclose(self) -> None:
+        try:
+            await self._stream.aclose()
+        finally:
+            await self._log_once(
+                {
+                    **_body_to_record(bytes(self._chunks)),
+                    "closed_before_complete": True,
+                }
+            )
+
+    async def _log_once(self, body_record: dict[str, Any]) -> None:
+        if self._logged:
+            return
+        self._logged = True
+        self._response_record["body"] = body_record
+        await _append_response_record(
+            self._log_path,
+            self._profile,
+            self._session_id,
+            self._exchange_id,
+            self._response_record,
+        )
+
+
+async def _append_response_record(
+    log_path: Path,
+    profile: ModelProfile,
+    session_id: str | None,
+    exchange_id: str,
+    response_record: dict[str, Any],
+) -> None:
+    await _append_record_async(
+        log_path,
+        {
+            "timestamp": _timestamp(),
+            "event": "response",
+            "exchange_id": exchange_id,
+            "session_id": session_id,
+            "model_profile": _profile_record(profile),
+            "response": response_record,
+        },
+    )
+
+
+async def _append_record_async(path: Path, record: dict[str, Any]) -> None:
+    try:
+        await asyncio.to_thread(_append_record, path, record)
+    except OSError:
+        logger.warning("Failed to write raw LLM HTTP log %s", path, exc_info=True)
+
+
+def _append_record(path: Path, record: dict[str, Any]) -> None:
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with _WRITE_LOCK:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            f.write(line)
+
+
+def _timestamp() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _profile_record(profile: ModelProfile) -> dict[str, str]:
+    return {
+        "id": profile.id,
+        "name": profile.name,
+        "provider": profile.provider,
+        "model_id": profile.model_id,
+    }
+
+
+def _headers_to_record(headers: httpx.Headers) -> list[list[str]]:
+    return [[name, value] for name, value in headers.multi_items()]
+
+
+def _body_to_record(body: bytes) -> dict[str, Any]:
+    record: dict[str, Any] = {"size_bytes": len(body)}
+    try:
+        record["encoding"] = "utf-8"
+        text = body.decode("utf-8")
+    except UnicodeDecodeError:
+        record["encoding"] = "base64"
+        record["base64"] = base64.b64encode(body).decode("ascii")
+    else:
+        try:
+            record["json"] = json.loads(text)
+        except json.JSONDecodeError:
+            sse_events = _parse_sse_events(text)
+            if sse_events is not None:
+                record["sse"] = sse_events
+            else:
+                record["text"] = text
+    return record
+
+
+def _parse_sse_events(text: str) -> list[dict[str, Any]] | None:
+    """Parse a Server-Sent Events body into structured events when possible."""
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    events: list[dict[str, Any]] = []
+    for block in normalized.split("\n\n"):
+        if not block.strip():
+            continue
+        event: dict[str, Any] = {}
+        data_lines: list[str] = []
+        comments: list[str] = []
+        for line in block.split("\n"):
+            if not line:
+                continue
+            if line.startswith(":"):
+                comments.append(line[1:].lstrip(" "))
+                continue
+            field, sep, value = line.partition(":")
+            if not sep:
+                value = ""
+            elif value.startswith(" "):
+                value = value[1:]
+            if field == "data":
+                data_lines.append(value)
+            elif field in {"event", "id", "retry"}:
+                event[field] = int(value) if field == "retry" and value.isdecimal() else value
+
+        if comments:
+            event["comments"] = comments
+        if data_lines:
+            data = "\n".join(data_lines)
+            if data.strip() == "[DONE]":
+                event["data"] = "[DONE]"
+            else:
+                try:
+                    event["data_json"] = json.loads(data)
+                except json.JSONDecodeError:
+                    event["data"] = data
+        if event:
+            events.append(event)
+    if any("data" in event or "data_json" in event for event in events):
+        return events
+    return None

chrys/service/llm/route_facts.py

@@ -0,0 +1,63 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Stamp route facts on every LLM request, and remember which first hops ever answered.
+
+The request hook runs before httpx sends each request — SDK retries and
+redirects included — and stamps a :class:`~chrys.foundation.errors.RouteFacts`
+snapshot into its extensions.  Every ``httpx.Request`` copies the extensions it
+is built with, so a redirect starts from a copy holding the previous hop's
+snapshot, which the hook replaces.  The response hook records the first hop as
+reached: any HTTP response through it proves the process could reach it at
+least once.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from chrys.foundation.errors import ROUTE_EXTENSION_KEY, Origin, RouteFacts, origin_of
+
+if TYPE_CHECKING:
+    import httpx
+
+    from chrys.service.llm.proxy_route import ProxyRouter
+
+# First hops (a proxy, or the target when direct) that returned at least one
+# HTTP response in this process. Never cleared at runtime: it is evidence that
+# a name once resolved, not proof it resolves now.
+_REACHED: set[Origin] = set()
+
+
+def record_reached(first_hop: Origin) -> None:
+    _REACHED.add(first_hop)
+
+
+def has_reached(first_hop: Origin) -> bool:
+    return first_hop in _REACHED
+
+
+def reset_reached_first_hops() -> None:
+    """Forget every reached first hop; tests only."""
+    _REACHED.clear()
+
+
+def build_route_hooks(router: ProxyRouter) -> dict[str, list[Callable[..., Any]]]:
+    """Return httpx event hooks that stamp and record *router*'s routes; list them first."""
+
+    async def stamp(request: httpx.Request) -> None:
+        target = origin_of(request.url)
+        if target is None:
+            request.extensions.pop(ROUTE_EXTENSION_KEY, None)
+            return
+        proxy = router.proxy_for(request.url)
+        request.extensions[ROUTE_EXTENSION_KEY] = RouteFacts(
+            target=target, proxy=proxy, first_hop_reached=has_reached(proxy or target)
+        )
+
+    async def record(response: httpx.Response) -> None:
+        facts = response.request.extensions.get(ROUTE_EXTENSION_KEY)
+        if isinstance(facts, RouteFacts):
+            record_reached(facts.first_hop)
+
+    return {"request": [stamp], "response": [record]}

chrys/service/llm/route_sessions.py

@@ -0,0 +1,49 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Stable LLM route-session id derivation for auxiliary request streams."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4, uuid5
+
+if TYPE_CHECKING:
+    from chrys.service.profiles.models.schema import ModelProfile
+
+# Chrys-owned UUIDv5 namespace for deriving opaque LLM routing session ids.
+# Changing this changes every derived auxiliary/sub-agent route session id.
+_LLM_ROUTE_SESSION_NAMESPACE = UUID("6ddd36f6-03d9-4e49-8558-fb0456857f55")
+_SEPARATOR = "\x1f"
+
+llm_route_session_id: ContextVar[str] = ContextVar("llm_route_session_id", default="")
+llm_parent_session_id: ContextVar[str] = ContextVar("llm_parent_session_id", default="")
+
+
+def derive_llm_route_session_id(
+    parent_session_id: str | None,
+    *,
+    route_kind: str,
+    route_parts: Sequence[str] = (),
+    model_profile: ModelProfile,
+) -> str:
+    """Return a stable child route-session id for a distinct LLM request stream."""
+    if not parent_session_id:
+        return uuid4().hex
+
+    from chrys.service.llm.clients import effective_model_base_url
+
+    seed = _SEPARATOR.join(
+        (
+            parent_session_id,
+            route_kind,
+            *route_parts,
+            model_profile.id,
+            model_profile.provider,
+            model_profile.api_style,
+            model_profile.model_id,
+            effective_model_base_url(model_profile),
+        )
+    )
+    return uuid5(_LLM_ROUTE_SESSION_NAMESPACE, seed).hex

chrys/service/llm/sdk_anthropic.py

@@ -0,0 +1,18 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``AsyncAnthropic`` client Chrys builds for the Anthropic provider.
+
+Importing this module loads the Anthropic SDK; the client factory imports it
+only while it builds such a client.
+"""
+
+from __future__ import annotations
+
+from anthropic import AsyncAnthropic
+
+from chrys.service.llm.sdk_headers import CaseFoldedDefaultHeaders
+from chrys.service.llm.sdk_retry import DeterministicConnectionDecisionGuard
+
+
+class RetryGuardedAsyncAnthropic(DeterministicConnectionDecisionGuard, CaseFoldedDefaultHeaders, AsyncAnthropic):
+    """``AsyncAnthropic`` that does not retry a connection error that cannot self-heal, and sends each header name once."""