iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/llm/chat_completions/reasoning.py

@@ -0,0 +1,244 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The reasoning fields Chat Completions dialects use, read and replayed.
+
+Compatible endpoints put the model's reasoning in one of three message
+fields: ``reasoning_details`` (OpenRouter; structured), ``reasoning_content``
+(DeepSeek, GLM, Kimi; plaintext) or vLLM's newer ``reasoning`` (plaintext,
+sometimes a mirror of one of the others). Each captured value is stamped
+with the field it came from, and replay sends it back under that field only.
+Replay depends on the dialect, never on the provider: Kimi runs on the plain
+``openai`` provider. ``reasoning_details`` may hold state only the endpoint
+that sent it can read, so it is stamped with that endpoint and replays only
+there; plaintext replays anywhere.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Collection, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+from chrys.foundation.reasoning_origin import replays_to
+from chrys.kernel import Content, Message
+from chrys.kernel._content import _ANTHROPIC_REDACTED_THINKING_KEY
+
+if TYPE_CHECKING:
+    from chrys.foundation.reasoning_origin import ReasoningOrigin
+
+    from .client import ChatCompletionsVariant
+
+logger = logging.getLogger(__name__)
+
+REASONING_DETAILS_FIELD = "reasoning_details"
+REASONING_CONTENT_FIELD = "reasoning_content"
+REASONING_FIELD = "reasoning"
+REASONING_FORMAT_KEY = "openai_reasoning_format"
+
+REASONING_FIELDS: tuple[str, ...] = (REASONING_DETAILS_FIELD, REASONING_CONTENT_FIELD, REASONING_FIELD)
+
+
+def reasoning_fields(source: Any) -> dict[str, Any]:
+    """The reasoning fields an SDK message or delta carries, by wire name.
+
+    ``reasoning_details`` and ``reasoning_content`` come first, as they may
+    hold state the provider needs back. A gateway can mirror the same
+    plaintext into ``reasoning`` too, so that field counts only when neither
+    of the others is present.
+    """
+    found = {
+        name: value
+        for name in (REASONING_DETAILS_FIELD, REASONING_CONTENT_FIELD)
+        if (value := getattr(source, name, None)) is not None
+    }
+    if not found and (mirror := getattr(source, REASONING_FIELD, None)) is not None:
+        found[REASONING_FIELD] = mirror
+    return found
+
+
+# --- capture ----------------------------------------------------------------
+
+
+def message_reasoning(message: Any, *, origin: ReasoningOrigin | None = None) -> list[Content]:
+    """A whole choice message's reasoning: one protected JSON payload per field.
+
+    ``reasoning_details`` is stamped with *origin*, the endpoint that sent it.
+    """
+    return [
+        Content.from_text_reasoning(
+            protected_data=json.dumps(value), additional_properties=_capture_props(name, origin)
+        )
+        for name, value in reasoning_fields(message).items()
+    ]
+
+
+def message_reasoning_props(message: Any, *, origin: ReasoningOrigin | None = None) -> dict[str, Any]:
+    """The same fields as message properties, the leading one named as the format.
+
+    They duplicate the contents :func:`message_reasoning` returns; replay
+    prefers the contents. A ``reasoning_details`` among them is stamped with
+    *origin*.
+    """
+    props = reasoning_fields(message)
+    if props:
+        props[REASONING_FORMAT_KEY] = next(iter(props))
+    if origin is not None and REASONING_DETAILS_FIELD in props:
+        origin.stamp(props)
+    return props
+
+
+def delta_reasoning(
+    fields: Mapping[str, Any], *, include_plain: bool, origin: ReasoningOrigin | None = None
+) -> list[Content]:
+    """The reasoning contents of one streamed delta's fields.
+
+    ``reasoning_details`` stays a protected payload, stamped with *origin*. A
+    plaintext field is the display text itself, left out when
+    *include_plain* is false.
+    """
+    contents: list[Content] = []
+    for name, value in fields.items():
+        if name == REASONING_DETAILS_FIELD:
+            contents.append(
+                Content.from_text_reasoning(
+                    protected_data=json.dumps(value), additional_properties=_capture_props(name, origin)
+                )
+            )
+        elif not include_plain:
+            continue
+        elif isinstance(value, str):
+            contents.append(Content.from_text_reasoning(text=value, additional_properties={REASONING_FORMAT_KEY: name}))
+        else:
+            logger.debug("Ignoring non-string Chat Completions reasoning delta of type %s", type(value).__name__)
+    return contents
+
+
+def _capture_props(field: str, origin: ReasoningOrigin | None) -> dict[str, Any]:
+    """A captured content's properties: its field, and for ``reasoning_details`` the endpoint."""
+    props: dict[str, Any] = {REASONING_FORMAT_KEY: field}
+    if origin is not None and field == REASONING_DETAILS_FIELD:
+        origin.stamp(props)
+    return props
+
+
+# --- replay -----------------------------------------------------------------
+
+
+def replays_reasoning(messages: Sequence[Message], *, variant: ChatCompletionsVariant, request_has_tools: bool) -> bool:
+    """Whether this request sends historical reasoning back.
+
+    By default it always does: endpoints with preserved thinking (GLM) need it
+    on every multi-turn request, and Kimi needs every assistant message's
+    ``reasoning_content``. Scoping replay by provider is impossible (Kimi and
+    OpenAI share ``openai``, differing only by base URL) and unnecessary:
+    OpenAI's Chat Completions API drops unknown message-level fields before
+    tokenization (checked live: no 400, no prompt tokens), so any history
+    replays safely. Its strict validation covers top-level request
+    parameters only.
+
+    A variant that replays reasoning only with tools (DeepSeek) does so on a
+    request that sends tools or follows a tool interaction.
+    """
+    if not variant.reasoning_with_tools or request_has_tools:
+        return True
+    return any(
+        message.role == "tool"
+        or any(content.type in ("function_call", "function_result") for content in message.contents)
+        for message in messages
+    )
+
+
+def pad_reasoning_content(wire: list[dict[str, Any]]) -> None:
+    """Give every assistant wire message a ``reasoning_content``, empty where it had none.
+
+    Once tools are in play DeepSeek wants one on each assistant message, and
+    history another model wrote (or DeepSeek with thinking off) has none.
+    Only the wire copy changes.
+    """
+    for message in wire:
+        if message.get("role") == "assistant":
+            message.setdefault(REASONING_CONTENT_FIELD, "")
+
+
+def contribution(content: Content, *, origin: ReasoningOrigin | None = None) -> tuple[str, Any] | None:
+    """The field and value one reasoning content replays as to the endpoint *origin*, or ``None``.
+
+    Reasoning another endpoint issued replays as nothing. The format stamp
+    names the field. A stamp naming none of these fields belongs to another
+    dialect, whose state would be forged by replaying it here. A protected
+    payload replays when it decodes as JSON to something other than
+    ``null``; anything else is another provider's opaque state (Responses
+    encrypted reasoning, Anthropic signatures) and silences the content's
+    text as well. Without a payload, a stamped content replays its text. An
+    unstamped content, from before the stamp existed, replays only a
+    decodable payload, as ``reasoning_details``.
+    """
+    properties = content.additional_properties
+    if properties.get(_ANTHROPIC_REDACTED_THINKING_KEY) or not replays_to(properties, origin):
+        return None
+    stamp = properties.get(REASONING_FORMAT_KEY)
+    field = stamp if stamp in REASONING_FIELDS else None
+    if field is None and REASONING_FORMAT_KEY in properties:
+        return None
+    if content.protected_data is not None:
+        payload = _decoded_payload(content.protected_data)
+        if payload is None:
+            return None
+        return field or REASONING_DETAILS_FIELD, payload
+    if field is not None and content.text is not None:
+        return field, content.text
+    return None
+
+
+def fold(fields: dict[str, Any], field: str, payload: Any) -> None:
+    """Add one contribution to a per-field aggregate.
+
+    Plaintext fields concatenate strings and ``reasoning_details`` extends
+    lists; any other pairing keeps the later value.
+    """
+    if field in fields:
+        earlier = fields[field]
+        if field == REASONING_DETAILS_FIELD:
+            if isinstance(earlier, list) and isinstance(payload, list):
+                payload = [*cast("list[Any]", earlier), *cast("list[Any]", payload)]
+        elif isinstance(earlier, str) and isinstance(payload, str):
+            payload = earlier + payload
+    fields[field] = payload
+
+
+def replayable_fields(message: Message, *, origin: ReasoningOrigin | None = None) -> dict[str, Any]:
+    """The reasoning fields a message replays to the endpoint *origin*, aggregated in capture order.
+
+    Its contents decide (see :func:`contribution`); the copy kept in the
+    message properties fills in only fields no content supplied.
+    """
+    fields: dict[str, Any] = {}
+    for content in message.contents:
+        if content.type == "text_reasoning" and (found := contribution(content, origin=origin)) is not None:
+            fold(fields, *found)
+    fields.update(stored_reasoning(message, skip=fields, origin=origin))
+    return fields
+
+
+def stored_reasoning(
+    message: Message, *, skip: Collection[str] = (), origin: ReasoningOrigin | None = None
+) -> dict[str, Any]:
+    """The reasoning fields kept in the message properties, except those in *skip*.
+
+    A ``reasoning_details`` an endpoint other than *origin* sent is left out.
+    """
+    properties = message.additional_properties
+    if not replays_to(properties, origin):
+        skip = {*skip, REASONING_DETAILS_FIELD}
+    return {
+        name: properties[name] for name in REASONING_FIELDS if name not in skip and properties.get(name) is not None
+    }
+
+
+def _decoded_payload(protected_data: str) -> Any | None:
+    """A Chat Completions client's own JSON payload; ``None`` for anything else."""
+    try:
+        return json.loads(protected_data)
+    except ValueError:
+        return None

chrys/service/llm/chat_completions/request.py

@@ -0,0 +1,192 @@
+# Copyright (c) Microsoft. All rights reserved.
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+# Contains code adapted from Microsoft Agent Framework (MIT License; see NOTICE).
+
+"""The Chat Completions request one chat call sends."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Mapping, MutableMapping, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+from openai.lib._parsing._completions import type_to_response_format_param
+
+from chrys.kernel import (
+    FunctionTool,
+    Message,
+    ToolTypes,
+    normalize_tools,
+    prepend_instructions_to_messages,
+    validate_tool_mode,
+)
+from chrys.kernel.exceptions import ChatClientInvalidRequestException
+from chrys.service.llm._structured_outputs import (
+    _materialize_json_structure,
+    _sanitize_response_format_name,
+    _strictify_response_schema,
+)
+from chrys.service.profiles.models.options import STREAM_REQUIRES_FINISH_REASON_OPTION
+
+from .history import encode_messages
+
+if TYPE_CHECKING:
+    from chrys.foundation.reasoning_origin import ReasoningOrigin
+
+    from .client import ChatCompletionsVariant
+
+logger = logging.getLogger(__name__)
+
+# Options the request carries in another form or not at all.
+_NOT_FORWARDED = frozenset({"instructions", "tools", "conversation_id", STREAM_REQUIRES_FINISH_REASON_OPTION})
+
+# Chat option names and the names this API uses for them.
+_RENAMED_OPTIONS = (("allow_multiple_tool_calls", "parallel_tool_calls"), ("max_tokens", "max_completion_tokens"))
+
+
+def build_request(
+    messages: Sequence[Message],
+    options: Mapping[str, Any],
+    *,
+    model: str,
+    variant: ChatCompletionsVariant,
+    origin: ReasoningOrigin | None = None,
+) -> dict[str, Any]:
+    """The keyword arguments of one ``chat.completions.create`` call to the endpoint *origin*, before the headers are stamped."""
+    _require_single_choice(options)
+    if instructions := options.get("instructions"):
+        messages = prepend_instructions_to_messages(list(messages), instructions, role="system")
+    request = {key: value for key, value in options.items() if value is not None and key not in _NOT_FORWARDED}
+    # Tools first: whether reasoning replays can depend on the request sending any.
+    tools = options.get("tools")
+    tool_fields = encode_tools(tools) if tools is not None else {}
+    if messages and "messages" not in request:
+        request["messages"] = encode_messages(
+            messages, variant=variant, request_has_tools=bool(tool_fields.get("tools")), origin=origin
+        )
+    if "messages" not in request:
+        raise ChatClientInvalidRequestException("Messages are required for chat completions")
+    for chat_name, wire_name in _RENAMED_OPTIONS:
+        if chat_name in request:
+            request[wire_name] = request.pop(chat_name)
+    # Real OpenAI rejects the legacy ``max_tokens`` on current models, while
+    # some compatible endpoints (DeepSeek, GLM) honor only that name.
+    cap = variant.max_output_param
+    if cap != "max_completion_tokens" and cap not in request and "max_completion_tokens" in request:
+        request[cap] = request.pop("max_completion_tokens")
+    if not request.get("model"):
+        if not model:
+            raise ValueError("model must be a non-empty string")
+        request["model"] = model
+    request.update(tool_fields)
+    # Tool choice and parallel calls go out only with tools.
+    tool_choice = request.pop("tool_choice", None)
+    if not request.get("tools"):
+        request.pop("parallel_tool_calls", None)
+    elif tool_choice and (wire_choice := _wire_tool_choice(tool_choice)) is not None:
+        request["tool_choice"] = wire_choice
+    # Presence, not truthiness: an empty mapping is a valid JSON schema
+    # without a type and still needs its envelope.
+    if (response_format := options.get("response_format")) is not None:
+        request["response_format"] = encode_response_format(response_format, model=request.get("model"))
+    return request
+
+
+def encode_tools(
+    tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
+) -> dict[str, Any]:
+    """The request's ``tools`` and ``web_search_options``.
+
+    A function tool goes out as its JSON schema spec. A ``web_search``
+    mapping configures the search options rather than joining the list;
+    anything else is sent as given.
+    """
+    listed: list[Any] = []
+    search: dict[str, Any] | None = None
+    for tool in normalize_tools(tools):
+        if isinstance(tool, FunctionTool):
+            listed.append(tool.to_json_schema_spec())
+            continue
+        if isinstance(tool, MutableMapping):
+            spec = cast("MutableMapping[str, Any]", tool)
+            if spec.get("type") == "web_search":
+                search = {key: value for key, value in spec.items() if key != "type"}
+                continue
+        listed.append(tool)
+    fields: dict[str, Any] = {"tools": listed} if listed else {}
+    if search is not None:
+        fields["web_search_options"] = search
+    return fields
+
+
+def encode_response_format(response_format: Any, *, model: Any) -> dict[str, Any]:
+    """The ``response_format`` for a model class, a format envelope or a raw JSON schema.
+
+    The two clients accept the same inputs. An envelope keeps its shape with
+    its name made valid; ``json_object`` and ``text`` pass as given. Any
+    other mapping is a raw schema: JSON Schema allows an array-valued or an
+    absent ``type`` (enum-only schemas), so no keyword test could tell them
+    apart.
+    """
+    if not isinstance(response_format, Mapping):
+        # The SDK helper copies the model class's name into the envelope unchecked.
+        return _valid_name(cast("dict[str, Any]", type_to_response_format_param(response_format)))
+    # Read-only views are copied once; plain dicts pass through by identity.
+    given = response_format if isinstance(response_format, dict) else dict(response_format)
+    given = cast("dict[str, Any]", given)
+    kind = given.get("type")
+    if kind == "json_schema":
+        return _valid_name(given)
+    # An equality test: an array-valued (unhashable) type reads as a raw schema.
+    if kind in ("json_object", "text"):
+        return given
+    # A copy: the strictifier edits nested mappings in place, and the caller's
+    # may be read-only views.
+    schema = _materialize_json_structure(given)
+    # Strict mode rejects unknown keys, so the title becomes the name.
+    envelope: dict[str, Any] = {"name": _sanitize_response_format_name(schema.pop("title", None))}
+    envelope["schema"], strict = _strictify_response_schema(schema, model=model)
+    if strict:
+        envelope["strict"] = True
+    return {"type": "json_schema", "json_schema": envelope}
+
+
+def _valid_name(response_format: dict[str, Any]) -> dict[str, Any]:
+    """A ``json_schema`` envelope with a valid name; copied only when the name changes."""
+    json_schema = response_format.get("json_schema")
+    if not isinstance(json_schema, Mapping):
+        return response_format
+    schema_spec = cast("Mapping[str, Any]", json_schema)
+    name = schema_spec.get("name")
+    valid = _sanitize_response_format_name(name)
+    if valid == name:
+        return response_format
+    return {**response_format, "json_schema": {**schema_spec, "name": valid}}
+
+
+def _wire_tool_choice(tool_choice: Any) -> Any:
+    """The ``tool_choice`` value for a chat tool mode; ``None`` when there is none."""
+    mode = validate_tool_mode(tool_choice)
+    if mode is None:
+        return None
+    name = mode.get("mode")
+    if name == "required" and (function := mode.get("required_function_name")) is not None:
+        return {"type": "function", "function": {"name": function}}
+    if name in ("auto", "required") and mode.get("allowed_tools") is not None:
+        logger.warning(
+            "The Chat Completions client does not send allowed_tools; the setting is ignored "
+            "(the Responses API client sends it)."
+        )
+    return name
+
+
+def _require_single_choice(options: Mapping[str, Any]) -> None:
+    """Refuse ``n`` other than 1: the kernel reads one conversation, not alternative choices.
+
+    ``extra_body`` counts too, as the SDK merges it over the named parameters.
+    """
+    extra_body = options.get("extra_body")
+    for source in (options, extra_body if isinstance(extra_body, Mapping) else {}):
+        count = cast("Mapping[str, Any]", source).get("n")
+        if count is not None and (type(count) is not int or count != 1):
+            raise ChatClientInvalidRequestException("The Chat Completions client supports only n=1")