strands-exaone 0.1.0__py3-none-any.whl

strands_exaone/__init__.py

@@ -0,0 +1,7 @@
+"""EXAONE model provider for Strands Agents."""
+
+from .errors import ExaoneContextWindowError, ExaoneError, ExaoneThrottledError
+from .model import ExaoneModel
+from .retry_strategy import ExaoneRetryStrategy
+
+__all__ = ["ExaoneContextWindowError", "ExaoneError", "ExaoneModel", "ExaoneRetryStrategy", "ExaoneThrottledError"]

strands_exaone/errors.py

@@ -0,0 +1,104 @@
+"""Provider errors with safe, request-specific response details."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from strands.types.exceptions import ContextWindowOverflowException, ModelThrottledException
+
+
+class ExaoneError(Exception):
+    """EXAONE request failed or returned an invalid stream."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: Any = None,
+        error_type: str | None = None,
+        param: Any = None,
+        request_id: str | None = None,
+        headers: dict[str, str] | None = None,
+        body: Any = None,
+        finish_reason: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.error_type = error_type
+        self.param = param
+        self.request_id = request_id
+        self.headers = headers or {}
+        self.body = body
+        self.finish_reason = finish_reason
+
+
+class ExaoneThrottledError(ModelThrottledException):
+    """HTTP 429 with the sanitized response attached as ``details``."""
+
+    def __init__(self, details: ExaoneError) -> None:
+        super().__init__(str(details))
+        self.details = details
+        self.status_code = details.status_code
+        self.error_type = details.error_type
+        self.request_id = details.request_id
+        self.headers = details.headers
+        self.body = details.body
+        self.code = details.code
+        self.param = details.param
+
+
+class ExaoneContextWindowError(ContextWindowOverflowException):
+    """The service explicitly reported that the context window was exceeded."""
+
+    def __init__(self, details: ExaoneError) -> None:
+        super().__init__(str(details))
+        self.details = details
+        self.status_code = details.status_code
+        self.error_type = details.error_type
+        self.request_id = details.request_id
+        self.headers = details.headers
+        self.body = details.body
+        self.code = details.code
+        self.param = details.param
+
+
+def redact(value: Any, secret: str) -> Any:
+    """Remove a credential from a response before exposing it."""
+    if isinstance(value, str):
+        return value.replace(secret, "[REDACTED]") if secret else value
+    if isinstance(value, dict):
+        return {redact(key, secret): redact(item, secret) for key, item in value.items()}
+    if isinstance(value, list):
+        return [redact(item, secret) for item in value]
+    return value
+
+
+def response_error(status: int, body: Any, headers: dict[str, str], secret: str) -> Exception:
+    """Map an error envelope without conflating arbitrary bad requests with context overflow."""
+    body = redact(body, secret)
+    envelope = body if isinstance(body, dict) else {}
+    nested = envelope.get("error", {})
+    if not isinstance(nested, dict):
+        nested = {}
+    fallback = f"HTTP {status}"
+    if 200 <= status < 300:
+        fallback = "EXAONE returned an error in the response body"
+    message = nested.get("message") or envelope.get("description") or fallback
+    code = nested["code"] if "code" in nested else envelope.get("result_code")
+    details = ExaoneError(
+        str(message),
+        status_code=status,
+        code=code,
+        error_type=nested.get("type") if isinstance(nested.get("type"), str) else None,
+        param=nested.get("param"),
+        request_id=headers.get("x-request-id"),
+        headers=headers,
+        body=body,
+    )
+    if status == 429:
+        return ExaoneThrottledError(details)
+    if status in {400, 413} and nested.get("code") == "context_length_exceeded":
+        return ExaoneContextWindowError(details)
+    return details

strands_exaone/formatting.py

@@ -0,0 +1,131 @@
+"""Translate Strands conversation history to EXAONE Chat Completions."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from strands.types.content import ContentBlock, Message, Messages, SystemContentBlock
+from strands.types.tools import ToolChoice, ToolResult, ToolSpec, ToolUse
+
+
+def _text_of_result(result: ToolResult) -> str:
+    parts: list[str] = []
+    for item in result.get("content", []):
+        if "text" in item:
+            parts.append(item["text"])
+        elif "json" in item:
+            parts.append(json.dumps(item["json"], ensure_ascii=False, separators=(",", ":")))
+        else:
+            raise ValueError("EXAONE supports text and JSON tool results only")
+    text = "\n".join(parts)
+    return f"[ERROR] {text}" if result.get("status") == "error" else text
+
+
+def _tool_call(tool: ToolUse) -> dict[str, Any]:
+    if tool.get("reasoningSignature"):
+        raise ValueError("EXAONE does not support tool reasoning signatures")
+    return {
+        "id": tool["toolUseId"],
+        "type": "function",
+        "function": {
+            "name": tool["name"],
+            "arguments": json.dumps(tool["input"], ensure_ascii=False, separators=(",", ":")),
+        },
+    }
+
+
+def _reasoning_text(block: ContentBlock) -> str:
+    reasoning = block["reasoningContent"]
+    if reasoning.get("redactedContent") is not None:
+        raise ValueError("EXAONE does not support redacted reasoning")
+    value = reasoning.get("reasoningText") or {}
+    if value.get("signature"):
+        raise ValueError("EXAONE does not support reasoning signatures")
+    return value.get("text", "")
+
+
+def _message_parts(message: Message) -> tuple[list[str], list[str], list[dict[str, Any]], list[dict[str, Any]]]:
+    text: list[str] = []
+    reasoning: list[str] = []
+    calls: list[dict[str, Any]] = []
+    results: list[dict[str, Any]] = []
+    role = message["role"]
+    for block in message["content"]:
+        if "text" in block:
+            text.append(block["text"])
+        elif "reasoningContent" in block and role == "assistant":
+            reasoning.append(_reasoning_text(block))
+        elif "toolUse" in block and role == "assistant":
+            calls.append(_tool_call(block["toolUse"]))
+        elif "toolResult" in block and role == "user":
+            result = block["toolResult"]
+            results.append({"role": "tool", "tool_call_id": result["toolUseId"], "content": _text_of_result(result)})
+        else:
+            raise ValueError(f"Unsupported EXAONE content block for {role}: {', '.join(block)}")
+    return text, reasoning, calls, results
+
+
+def _system_messages(
+    system_prompt: str | None, system_prompt_content: list[SystemContentBlock] | None
+) -> list[dict[str, Any]]:
+    if system_prompt_content is not None:
+        return [{"role": "system", "content": block["text"]} for block in system_prompt_content if "text" in block]
+    return [{"role": "system", "content": system_prompt}] if system_prompt else []
+
+
+def _format_message(message: Message) -> list[dict[str, Any]]:
+    role = message["role"]
+    if role not in {"user", "assistant"}:
+        raise ValueError(f"Unsupported Strands message role: {role}")
+    text, reasoning, calls, results = _message_parts(message)
+    if role == "assistant":
+        assistant: dict[str, Any] = {"role": "assistant", "content": "".join(text)}
+        if reasoning:
+            assistant["reasoning_content"] = "".join(reasoning)
+        if calls:
+            assistant["tool_calls"] = calls
+        return [assistant]
+    if text:
+        return [*results, {"role": "user", "content": "".join(text)}]
+    if not results:
+        raise ValueError("User message must contain text or a tool result")
+    return results
+
+
+def format_messages(
+    messages: Messages,
+    system_prompt: str | None,
+    system_prompt_content: list[SystemContentBlock] | None,
+) -> list[dict[str, Any]]:
+    """Build ordered wire messages without losing thinking or tool result IDs."""
+    output = _system_messages(system_prompt, system_prompt_content)
+    for message in messages:
+        output.extend(_format_message(message))
+    return output
+
+
+def format_tools(specs: list[ToolSpec]) -> list[dict[str, Any]]:
+    """Convert Strands tool specifications to OpenAI-compatible functions."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": spec["name"],
+                "description": spec["description"],
+                "parameters": spec["inputSchema"]["json"],
+            },
+        }
+        for spec in specs
+    ]
+
+
+def format_tool_choice(choice: ToolChoice) -> str | dict[str, Any]:
+    """Map a Strands tool choice to the Chat Completions wire format."""
+    if "auto" in choice:
+        return "auto"
+    if "any" in choice:
+        return "required"
+    if "tool" in choice:
+        return {"type": "function", "function": {"name": cast(dict[str, Any], choice)["tool"]["name"]}}
+    raise ValueError("Unsupported tool choice")

strands_exaone/metadata.py

@@ -0,0 +1,95 @@
+"""Collect response metadata without duplicating message or reasoning content."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+_FIELDS = (
+    "id",
+    "object",
+    "created",
+    "model",
+    "metadata",
+    "service_tier",
+    "system_fingerprint",
+    "moderation",
+    "result_code",
+    "description",
+)
+_CHOICE_FIELDS = ("index", "finish_reason", "logprobs", "matched_stop")
+_MESSAGE_FIELDS = ("refusal", "annotations", "audio", "function_call")
+
+
+class ResponseMetadata:
+    """Merge the metadata fields of consecutive Chat Completions chunks."""
+
+    def __init__(self, *, enabled: bool = True) -> None:
+        self.enabled = enabled
+        self.response: dict[str, Any] = {}
+        self._choice: dict[str, Any] = {}
+
+    def add(self, chunk: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        for key in _FIELDS:
+            if key in chunk and (chunk[key] is not None or key not in self.response):
+                self.response[key] = deepcopy(chunk[key])
+        choices = chunk.get("choices")
+        if not isinstance(choices, list):
+            return
+        for choice in choices:
+            if isinstance(choice, dict):
+                self._add_choice(choice)
+        if choices:
+            self.response["choices"] = [self._choice]
+
+    def _add_choice(self, choice: dict[str, Any]) -> None:
+        for key in _CHOICE_FIELDS:
+            if key not in choice:
+                continue
+            value = choice[key]
+            if key == "logprobs" and isinstance(value, dict):
+                self._merge_logprobs(value)
+            elif value is not None or key not in self._choice:
+                self._choice[key] = deepcopy(value)
+        message = choice.get("message")
+        if isinstance(message, dict):
+            self._add_message(message)
+        delta = choice.get("delta")
+        if isinstance(delta, dict):
+            self._add_delta(delta)
+
+    def _add_message(self, message: dict[str, Any]) -> None:
+        fields = {key: deepcopy(message[key]) for key in _MESSAGE_FIELDS if key in message}
+        if fields:
+            self._choice["message"] = fields
+
+    def _add_delta(self, delta: dict[str, Any]) -> None:
+        message = self._choice.setdefault("message", {})
+        for key in ("refusal", "annotations"):
+            if key not in delta:
+                continue
+            value = delta[key]
+            previous = message.get(key)
+            if isinstance(previous, str) and isinstance(value, str) and key == "refusal":
+                message[key] = previous + value
+            elif isinstance(previous, list) and isinstance(value, list) and key == "annotations":
+                previous.extend(deepcopy(value))
+            elif value is not None or key not in message:
+                message[key] = deepcopy(value)
+        if not message:
+            self._choice.pop("message", None)
+        raw = {key: deepcopy(delta[key]) for key in ("audio", "function_call") if key in delta}
+        if raw:
+            self._choice.setdefault("message_deltas", []).append(raw)
+
+    def _merge_logprobs(self, value: dict[str, Any]) -> None:
+        previous = self._choice.get("logprobs")
+        result: dict[str, Any] = previous if isinstance(previous, dict) else {}
+        for key, item in value.items():
+            if key in {"content", "refusal"} and isinstance(item, list) and isinstance(result.get(key), list):
+                result[key].extend(deepcopy(item))
+            elif item is not None or key not in result:
+                result[key] = deepcopy(item)
+        self._choice["logprobs"] = result