iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/llm/anthropic_messages/client.py

@@ -0,0 +1,254 @@
+# 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 Messages API client: one request out, one message or event stream back.
+
+It runs over a configured Anthropic SDK client (direct, Bedrock, Foundry or
+Vertex) and owns closing it. :mod:`.request` builds the request,
+:mod:`.decode` and :mod:`.stream` read the answer.
+
+When the service refuses replayed thinking as bound to a different
+conversation, the client resends the request once without it, unless the
+request asked for that refusal; see :meth:`AnthropicMessagesClient._create`.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterable, Awaitable, Collection, Mapping, Sequence
+from inspect import isawaitable
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Self, override
+
+from anthropic import Omit
+
+from chrys.foundation.errors import is_thinking_binding_rejection
+from chrys.foundation.models.history_markers import ANTHROPIC_THINKING_STRIPPED_KEY
+from chrys.foundation.reasoning_origin import ReasoningOrigin
+from chrys.foundation.util.once_close import OnceClose
+from chrys.kernel import ChatResponse, ChatResponseUpdate, Message, ResponseStream, report_wire_progress
+from chrys.service.llm.wire_client import RequestHeaders, WireClient
+
+from .decode import decode_message
+from .request import BETA_HEADER, BuiltRequest, build_request
+from .stream import StreamState
+
+if TYPE_CHECKING:
+    from anthropic import AsyncAnthropic, AsyncAnthropicBedrock, AsyncAnthropicFoundry, AsyncAnthropicVertex
+
+    from chrys.kernel import Content
+    from chrys.kernel.compaction import CompactionStrategy, TokenizerProtocol
+    from chrys.service.llm.observer import WireCallObserver
+
+    type AnthropicSdkClient = AsyncAnthropic | AsyncAnthropicBedrock | AsyncAnthropicFoundry | AsyncAnthropicVertex
+
+logger = logging.getLogger(__name__)
+
+REASONING_PROTOCOL: Final = "anthropic_messages"
+"""The protocol a reasoning stamp names for this client."""
+
+
+class AnthropicMessagesClient(WireClient):
+    """Messages API wire client over a configured Anthropic SDK client.
+
+    The tool loop and chat middleware wrap it in the stack the client factory
+    builds.
+    """
+
+    OTEL_PROVIDER_NAME: ClassVar[str] = "anthropic"
+    # The Messages API keeps no conversation state, so a ``store`` option
+    # copied into a profile never moves its history to the service side.
+    FORCES_STATELESS: ClassVar[bool] = True
+
+    def __init__(
+        self,
+        model: str | None = None,
+        *,
+        sdk_client: AnthropicSdkClient | None = None,
+        observer: WireCallObserver | None = None,
+        request_headers: RequestHeaders | None = None,
+        compaction_strategy: CompactionStrategy | None = None,
+        tokenizer: TokenizerProtocol | None = None,
+        additional_properties: dict[str, Any] | None = None,
+    ) -> None:
+        if sdk_client is None:
+            raise ValueError("AnthropicMessagesClient requires a pre-configured sdk_client.")
+        super().__init__(
+            observer=observer,
+            request_headers=request_headers,
+            compaction_strategy=compaction_strategy,
+            tokenizer=tokenizer,
+            additional_properties=additional_properties,
+        )
+        self.sdk_client = sdk_client
+        self.model = model or ""
+        self._close_sdk = OnceClose(self._close_sdk_client)
+
+    @classmethod
+    @override
+    def from_sdk_client(
+        cls,
+        sdk_client: AnthropicSdkClient,
+        *,
+        model: str,
+        observer: WireCallObserver | None = None,
+        request_headers: RequestHeaders | None = None,
+    ) -> Self:
+        return cls(model=model, sdk_client=sdk_client, observer=observer, request_headers=request_headers)
+
+    @override
+    def service_url(self) -> str:
+        return str(self.sdk_client.base_url)
+
+    async def aclose(self) -> None:
+        """Close the SDK client and its HTTP pool; concurrent callers share one close."""
+        await self._close_sdk()
+
+    async def _close_sdk_client(self) -> None:
+        await self.sdk_client.close()
+
+    def reasoning_origin(self) -> ReasoningOrigin | None:
+        """The endpoint this client's thinking comes from, and the only one it replays to."""
+        return ReasoningOrigin.of(REASONING_PROTOCOL, self.sdk_client.base_url)
+
+    def _build_request(
+        self,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        call_kwargs: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        return self._prepare(messages, options, call_kwargs).request
+
+    def _prepare(
+        self,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        call_kwargs: Mapping[str, Any],
+        *,
+        skip_thinking: Collection[Content] = (),
+    ) -> BuiltRequest:
+        built = build_request(
+            messages,
+            options,
+            call_kwargs,
+            model=self.model,
+            base_url=self.sdk_client.base_url,
+            default_headers=self.sdk_client.default_headers,
+            origin=self.reasoning_origin(),
+            skip_thinking=skip_thinking,
+        )
+        self._stamp_request_headers(built.request)
+        return built
+
+    async def _create(
+        self,
+        built: BuiltRequest,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        call_kwargs: Mapping[str, Any],
+        *,
+        stream: bool,
+    ) -> Any:
+        """Send *built*, and once more without its thinking if the service refuses that thinking.
+
+        The service refuses replayed thinking bound to a different
+        conversation unless the request lets it drop the block. The request
+        is rebuilt without the thinking it replayed and sent again, unless
+        it asked for the refusal (``prefix_mismatch_behavior: error``).
+        Nothing was answered yet, so nothing is replayed twice. Once the
+        resend is accepted, that thinking is marked and never sent again,
+        which keeps later requests' history the same as the accepted one's.
+        A second failure is raised as it is.
+        """
+        try:
+            return await self._sdk_create(built.request, stream=stream)
+        except Exception as exc:
+            if not (
+                built.thinking and built.policy.mismatch_behavior != "error" and is_thinking_binding_rejection(exc)
+            ):
+                raise
+        resend = self._prepare(messages, options, call_kwargs, skip_thinking=built.thinking)
+        # The refusal is the service answering: the resend's wait for its first byte is timed afresh.
+        report_wire_progress()
+        result = await self._sdk_create(resend.request, stream=stream)
+        for content in built.thinking:
+            content.additional_properties[ANTHROPIC_THINKING_STRIPPED_KEY] = True
+        logger.warning(
+            "Anthropic refused replayed thinking as bound to a different conversation; the request was resent "
+            "without the %d reasoning item(s) it replayed, which are not sent again.",
+            len(built.thinking),
+        )
+        return result
+
+    def _sdk_create(self, request: dict[str, Any], *, stream: bool) -> Awaitable[Any]:
+        return self.sdk_client.beta.messages.create(**self._sdk_request(request), stream=stream)  # type: ignore[misc]
+
+    def _sdk_request(self, request: dict[str, Any]) -> dict[str, Any]:
+        """*request* with the SDK client's default ``anthropic-beta`` headers it replaces left out.
+
+        The SDK merges its default headers into a request's case-sensitively,
+        so a default spelled otherwise than the request's header, or any one
+        when the request sends none, would go out as a second header. An
+        ``Omit()`` drops it; it is added only here, as it is no header value
+        the stamped request may carry.
+        """
+        headers = request["extra_headers"]
+        omitted = {
+            name: Omit()
+            for name in self.sdk_client.default_headers
+            if name.lower() == BETA_HEADER and name not in headers
+        }
+        return {**request, "extra_headers": {**headers, **omitted}} if omitted else request
+
+    @override
+    def _send(
+        self,
+        *,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        **kwargs: Any,
+    ) -> Awaitable[ChatResponse]:
+        built = self._prepare(messages, options, kwargs)
+
+        async def response() -> ChatResponse:
+            message = await self._create(built, messages, options, kwargs, stream=False)
+            return decode_message(
+                message, response_format=options.get("response_format"), origin=self.reasoning_origin()
+            )
+
+        return response()
+
+    @override
+    def _open_stream(
+        self,
+        *,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        **kwargs: Any,
+    ) -> ResponseStream[ChatResponseUpdate, ChatResponse]:
+        built = self._prepare(messages, options, kwargs)
+
+        async def updates() -> AsyncIterable[ChatResponseUpdate]:
+            state = StreamState(origin=self.reasoning_origin())
+            events: Any = None
+            try:
+                events = await self._create(built, messages, options, kwargs, stream=True)
+                async for event in events:
+                    for update in state.updates_for(event):
+                        yield update
+                state.finish()
+            finally:
+                if events is not None:
+                    await _close_event_stream(events)
+
+        return self._build_response_stream(updates(), response_format=options.get("response_format"))
+
+
+async def _close_event_stream(events: Any) -> None:
+    """Close the SDK event stream; a failure to close is only logged."""
+    try:
+        close = getattr(events, "close", None) or getattr(events, "aclose", None)
+        if close is not None and isawaitable(closing := close()):
+            await closing
+    except Exception:
+        logger.debug("Failed to close Anthropic message stream", exc_info=True)

chrys/service/llm/anthropic_messages/decode.py

@@ -0,0 +1,331 @@
+# 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).
+
+"""Decode Messages API responses: content blocks, citations, usage and stop reasons.
+
+The same block decoder reads a blocking response's content and a stream's
+block starts and deltas; :mod:`.stream` adds what only the stream knows.
+Server-tool and MCP blocks are decoded in :mod:`.server_tools`.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Final
+
+from chrys.foundation.reasoning_origin import ReasoningOrigin
+from chrys.kernel import (
+    Annotation,
+    ChatResponse,
+    Content,
+    FinishReason,
+    FinishReasonLiteral,
+    Message,
+    TextSpanRegion,
+    UsageDetails,
+)
+from chrys.kernel._content import _ANTHROPIC_REDACTED_THINKING_KEY
+from chrys.service.llm.chat_completions.decode import refused_calls_error
+
+from . import server_tools
+
+if TYPE_CHECKING:
+    from anthropic.types.beta import BetaMessage, BetaMessageDeltaUsage, BetaUsage
+
+logger = logging.getLogger(__name__)
+
+_FINISH_REASONS: Final[Mapping[str, FinishReasonLiteral]] = {
+    "end_turn": "stop",
+    "pause_turn": "stop",
+    "stop_sequence": "stop",
+    "max_tokens": "length",
+    # Cut off, without the window-filled marker Chat Completions sets
+    # (``CONTEXT_WINDOW_FILLED_KEY``): a LAST_WORDS note cut off here is kept.
+    "model_context_window_exceeded": "length",
+    "tool_use": "tool_calls",
+    "refusal": "content_filter",
+}
+
+# Server tools that run in the code container; tools they call report results
+# nested in it.
+_CONTAINER_TOOLS: Final = frozenset({"code_execution", "bash_code_execution", "text_editor_code_execution"})
+
+
+def log_input_transformations(source: object) -> None:
+    """Log at DEBUG the blocks the service changed in the request before the model saw it.
+
+    *source* is a message or a ``message_delta`` event. Only each entry's
+    type, reason and path are logged, never block content or signatures.
+    """
+    # The SDK does not model the field yet: it is an extra attribute of its model.
+    entries = getattr(source, "input_transformations", None)
+    if not entries or not isinstance(entries, list):
+        return
+    logger.debug(
+        "The service changed %d block(s) of the request: %s",
+        len(entries),
+        [tuple(_entry_field(entry, name) for name in ("type", "reason", "path")) for entry in entries],
+    )
+
+
+def _entry_field(entry: object, name: str) -> object:
+    return entry.get(name) if isinstance(entry, Mapping) else getattr(entry, name, None)
+
+
+def decode_message(
+    message: BetaMessage, *, response_format: Any, origin: ReasoningOrigin | None = None
+) -> ChatResponse:
+    """A blocking response as one assistant message, its thinking stamped with *origin*.
+
+    A message that stops for a refusal yet asks for tool calls raises: the
+    calls are never run.
+    """
+    log_input_transformations(message)
+    usage = decode_usage(message.usage)
+    if usage is not None and (estimate := blocking_context_estimate(message.usage, message.content)) is not None:
+        usage["context_input_token_estimate"] = estimate
+    contents = decode_blocks(message.content, origin=origin)
+    if message.stop_reason == "refusal" and any(content.type == "function_call" for content in contents):
+        hosted = [content for content in contents if content.provider_hosted]
+        raise refused_calls_error(hosted, usage_details=usage)
+    return ChatResponse(
+        response_id=message.id,
+        messages=[Message(role="assistant", contents=contents, raw_representation=message)],
+        usage_details=usage,
+        model=message.model,
+        finish_reason=decode_stop_reason(message.stop_reason),
+        response_format=response_format,
+        raw_representation=message,
+    )
+
+
+def decode_stop_reason(stop_reason: str | None) -> FinishReason | None:
+    """The finish reason of *stop_reason*; one Chrys does not map is kept as it is."""
+    if not stop_reason:
+        return None
+    return FinishReason(_FINISH_REASONS.get(stop_reason, stop_reason))
+
+
+def decode_blocks(blocks: Sequence[Any], *, origin: ReasoningOrigin | None = None) -> list[Content]:
+    """Decode content blocks, or the deltas of streamed ones; unsupported blocks are skipped.
+
+    Thinking, signatures and redacted thinking are stamped with *origin*, the
+    endpoint that sent them.
+    """
+    contents = [content for block in blocks if (content := _decode_block(block)) is not None]
+    if origin is not None:
+        for content in contents:
+            if content.type == "text_reasoning":
+                origin.stamp(content.additional_properties)
+    return contents
+
+
+def _decode_block(block: Any) -> Content | None:
+    match block.type:
+        case "text" | "text_delta":
+            return Content.from_text(text=block.text, raw_representation=block, annotations=decode_citations(block))
+        case "citations_delta":
+            # A streamed citation of the text block it arrives in; response
+            # assembly merges it into that text.
+            return Content.from_text(text="", raw_representation=block, annotations=[_decode_citation(block.citation)])
+        case "thinking" | "thinking_delta":
+            # A thinking delta carries no signature; a later signature delta does.
+            signature = getattr(block, "signature", None)
+            return Content.from_text_reasoning(text=block.thinking, protected_data=signature, raw_representation=block)
+        case "signature_delta":
+            return Content.from_text_reasoning(text=None, protected_data=block.signature, raw_representation=block)
+        case "redacted_thinking":
+            return Content.from_text_reasoning(
+                text=None,
+                protected_data=block.data,
+                additional_properties={_ANTHROPIC_REDACTED_THINKING_KEY: True},
+                raw_representation=block,
+            )
+        case "tool_use":
+            return Content.from_function_call(
+                call_id=block.id, name=block.name, arguments=block.input, raw_representation=block
+            )
+        case "server_tool_use":
+            return server_tools.decode_server_tool_use(block)
+        case "mcp_tool_use":
+            return server_tools.decode_mcp_tool_use(block)
+        case "mcp_tool_result":
+            return server_tools.decode_mcp_tool_result(block, output=_mcp_output(block))
+        case "input_json_delta":
+            # Only the stream event knows which block the input belongs to.
+            logger.debug("Ignoring Anthropic input_json_delta without stream event context")
+            return None
+        case kind if kind != "tool_result" and kind.endswith("_tool_result"):
+            return server_tools.decode_server_tool_result(block)
+        case kind:
+            logger.debug("Ignoring unsupported content type: %s", kind)
+            return None
+
+
+def _mcp_output(block: Any) -> list[Content] | None:
+    output = block.content
+    if not output:
+        return None
+    if isinstance(output, list):
+        return decode_blocks(output)
+    if isinstance(output, (str, bytes)):
+        return [Content.from_text(text=str(output), raw_representation=block)]
+    return decode_blocks([output])
+
+
+@dataclass(frozen=True, slots=True)
+class _CitationShape:
+    """Where one citation type keeps the fields an annotation reads."""
+
+    title: str
+    span: tuple[str, str] | None
+    """The start and end attributes of the cited region."""
+    url: str | None = None
+    names_file: bool = False
+    """The citation may name the uploaded file it cites."""
+
+
+_CITATION_SHAPES: Final[Mapping[str, _CitationShape]] = {
+    "char_location": _CitationShape("document_title", ("start_char_index", "end_char_index"), names_file=True),
+    "page_location": _CitationShape("document_title", ("start_page_number", "end_page_number"), names_file=True),
+    "content_block_location": _CitationShape(
+        "document_title", ("start_block_index", "end_block_index"), names_file=True
+    ),
+    "web_search_result_location": _CitationShape("title", None, url="url"),
+    "search_result_location": _CitationShape("title", ("start_block_index", "end_block_index"), url="source"),
+}
+
+
+def decode_citations(block: Any) -> list[Annotation] | None:
+    """The citations of a text block as annotations; None when it cites nothing."""
+    citations = getattr(block, "citations", None)
+    if not citations:
+        return None
+    return [_decode_citation(citation) for citation in citations] or None
+
+
+def _decode_citation(citation: Any) -> Annotation:
+    annotation = Annotation(type="citation", raw_representation=citation)
+    shape = _CITATION_SHAPES.get(citation.type)
+    if shape is None:
+        logger.debug("Unknown citation type encountered: %s", citation.type)
+        return annotation
+    if (title := getattr(citation, shape.title, None)) is not None:
+        annotation["title"] = title
+    annotation["snippet"] = citation.cited_text
+    if shape.url is not None:
+        annotation["url"] = getattr(citation, shape.url)
+    if shape.names_file and citation.file_id:
+        annotation["file_id"] = citation.file_id
+    if shape.span is not None:
+        start, end = shape.span
+        annotation["annotated_regions"] = [
+            TextSpanRegion(type="text_span", start_index=getattr(citation, start), end_index=getattr(citation, end))
+        ]
+    return annotation
+
+
+def token_count(value: Any) -> int | None:
+    """*value* when it is a token count: a non-negative int that is not a bool."""
+    if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+        return value
+    return None
+
+
+def decode_usage(usage: BetaUsage | BetaMessageDeltaUsage | None) -> UsageDetails | None:
+    """Usage details of a response, or of a stream's start or message delta.
+
+    Cache creation and reads are reported under the shared keys and under
+    ``anthropic.``-prefixed ones. Both are also added to ``input_token_count``:
+    cached prompt tokens still occupy the context window.
+    """
+    if not usage:
+        return None
+    details = UsageDetails(output_token_count=usage.output_tokens)
+    if usage.input_tokens is not None:
+        details["input_token_count"] = usage.input_tokens
+    created, read = usage.cache_creation_input_tokens, usage.cache_read_input_tokens
+    if created is not None:
+        details["anthropic.cache_creation_input_tokens"] = created  # type: ignore[typeddict-unknown-key]
+        details["cache_creation_input_token_count"] = created
+    if read is not None:
+        details["anthropic.cache_read_input_tokens"] = read  # type: ignore[typeddict-unknown-key]
+        details["cache_read_input_token_count"] = read
+    if (floor := context_floor(usage)) is not None:
+        details["context_input_token_floor"] = floor
+    if (cached := int(created or 0) + int(read or 0)) > 0 and "input_token_count" in details:
+        details["input_token_count"] = int(details["input_token_count"] or 0) + cached
+    return details
+
+
+def context_floor(usage: BetaUsage | BetaMessageDeltaUsage | None) -> int | None:
+    """Context tokens *usage* proves: uncached input plus cache creation.
+
+    Cache reads are left out because a hosted-tool loop reports them summed
+    over its sampling passes.
+    """
+    if usage is None:
+        return None
+    uncached, created = token_count(usage.input_tokens), token_count(usage.cache_creation_input_tokens)
+    if uncached is None or created is None:
+        return None
+    return created + uncached
+
+
+def stream_context_input(usage: BetaMessageDeltaUsage | None, *, first_cache_read: int | None) -> int | None:
+    """Context occupancy at the end of a streamed response.
+
+    The final usage of a hosted-tool loop sums cache reads over every sampling
+    pass; of those, only the first request's read (*first_cache_read*, from
+    the message start) is still in the context.
+    """
+    if first_cache_read is None or (floor := context_floor(usage)) is None:
+        return None
+    return first_cache_read + floor
+
+
+def blocking_context_estimate(usage: BetaUsage | None, blocks: Sequence[Any]) -> int | None:
+    """Estimate the context occupancy of a blocking response.
+
+    A blocking response reports only the cache reads summed over its sampling
+    passes. Their mean estimates the cached prefix still held, and counts
+    only when it exceeds the cache creation.
+    """
+    floor = context_floor(usage)
+    if usage is None or floor is None:
+        return None
+    read, created = token_count(usage.cache_read_input_tokens), token_count(usage.cache_creation_input_tokens)
+    passes = _sampling_passes(blocks)
+    if read is None or created is None or passes is None:
+        return floor
+    mean_read = -(-read // passes)
+    return floor + mean_read if mean_read > created else floor
+
+
+def _sampling_passes(blocks: Sequence[Any]) -> int | None:
+    """Sampling passes of a blocking response; None when no server tool returned.
+
+    Every top-level server-tool result starts another pass. A result for a
+    tool called inside a running container tool is part of that tool's pass.
+    """
+    running_containers: list[str] = []
+    results = 0
+    for block in blocks:
+        kind = str(getattr(block, "type", ""))
+        if kind == "server_tool_use":
+            call_id = getattr(block, "id", None)
+            if getattr(block, "name", None) in _CONTAINER_TOOLS and isinstance(call_id, str):
+                running_containers.append(call_id)
+        elif kind != "tool_result" and kind.endswith("_tool_result"):
+            answered = getattr(block, "tool_use_id", None)
+            if isinstance(answered, str) and answered in running_containers:
+                position = running_containers.index(answered)
+                del running_containers[position]
+                if position == 0:
+                    results += 1
+            elif not running_containers:
+                results += 1
+    return results + 1 if results else None