llm-interface 0.2.0__tar.gz → 0.2.2__tar.gz

{llm_interface-0.2.0 → llm_interface-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-interface
-Version: 0.2.0
+Version: 0.2.2
 Summary: A flexible interface for working with various LLM providers
 License: Apache-2.0
 License-File: LICENSE

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/__init__.py

@@ -5,7 +5,7 @@ from .llm_interface import LLMInterface, ModelError
 from .llm_tool import Tool, tool
 from .token_usage import TokenUsage
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __all__ = [
     "LLMInterface",
     "llm_from_config",

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/anthropic.py

@@ -214,6 +214,32 @@ def convert_anthropic_models_to_ollama_response(
     return ListResponse(models=ollama_models)
 
 
+def _usage_int(value: Any) -> int:
+    """Usage counters that the SDK may leave unset (or that tests mock) become 0."""
+    return value if isinstance(value, int) else 0
+
+
+def _estimate_thinking_tokens(response: Any) -> int:
+    """Thinking tokens are billed as output but the API does not count them
+    separately. When the response carries thinking blocks, estimate them as the
+    output tokens that the visible text and tool-call blocks do not account for."""
+    blocks = list(getattr(response, "content", None) or [])
+    if not any(getattr(block, "type", None) == "thinking" for block in blocks):
+        return 0
+    visible_chars = 0
+    for block in blocks:
+        block_type = getattr(block, "type", None)
+        if block_type == "text":
+            visible_chars += len(getattr(block, "text", "") or "")
+        elif block_type == "tool_use":
+            try:
+                visible_chars += len(json.dumps(getattr(block, "input", None)))
+            except (TypeError, ValueError):
+                pass
+    output_tokens = _usage_int(getattr(response.usage, "output_tokens", 0))
+    return max(0, output_tokens - visible_chars // 4)
+
+
 class AnthropicWrapper:
     def __init__(
         self,
@@ -351,7 +377,11 @@ class AnthropicWrapper:
                 "prompt_tokens": usage.input_tokens,
                 "completion_tokens": usage.output_tokens,
                 "cached_tokens": usage.cache_read_input_tokens or 0,
+                "cache_creation_tokens": _usage_int(
+                    getattr(usage, "cache_creation_input_tokens", 0)
+                ),
                 "total_tokens": usage.input_tokens + usage.output_tokens,
+                "reasoning_tokens": _estimate_thinking_tokens(response),
             }
 
             if response.stop_reason == "refusal":

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/errors.py

@@ -4,3 +4,4 @@ CONTENT_FILTER = "content_filter"
 PROVIDER_SPECIFIC = "provider_specific"
 HTTP = "http"
 CONNECTION = "connection"
+RATE_LIMIT = "rate_limit"

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/llm_config.py

@@ -7,6 +7,7 @@ from .anthropic import AnthropicWrapper
 from .gemini import GeminiWrapper
 from .llm_interface import LLMInterface
 from .openai import OpenAIWrapper
+from .openai_responses import OpenAIResponsesWrapper
 from .openrouter import OpenRouterWrapper
 from .remote_ollama import RemoteOllama
 from .ssh import SSHConnection
@@ -36,12 +37,11 @@ def supports_structured_output(model_name: str) -> bool:
     # Check if this is a GPT model with version 5 or higher
     # This handles both base models and dated variants (e.g., gpt-5, gpt-5-mini, gpt-5-2025-01-01)
     if model_name.startswith("gpt-"):
-        # Extract the version number after "gpt-"
+        # Extract the major version after "gpt-" (gpt-5, gpt-5-mini, gpt-5.6-luna)
         parts = model_name[4:].split("-")
-        if parts and parts[0].isdigit():
-            version = int(parts[0])
-            if version >= 5:
-                return True
+        major = re.match(r"(\d+)(?:\.\d+)?$", parts[0]) if parts else None
+        if major and int(major.group(1)) >= 5:
+            return True
 
     # Models that always support structured outputs (no date requirements)
     base_models = {
@@ -97,6 +97,7 @@ def llm_from_config(
     effort: Optional[str] = None,
     prompt_caching: bool = True,
     max_tool_rounds: int = 5,
+    openai_api: Literal["responses", "chat"] = "responses",
 ) -> LLMInterface:
     """
     Creates and configures a language model interface based on specified provider and parameters.
@@ -119,12 +120,17 @@ def llm_from_config(
         structured_outputs (Optional[bool]): Whether to override structured output support. Defaults to None.
         thinking (Optional[Dict[str, Any]]): Extended thinking configuration forwarded to
             `AnthropicWrapper` (e.g. {"type": "adaptive"}). Only used by the "anthropic" provider.
-        effort (Optional[str]): Effort level (low|medium|high|xhigh|max) forwarded to
-            `AnthropicWrapper`. Only used by the "anthropic" provider.
+        effort (Optional[str]): Effort level forwarded to `AnthropicWrapper` as
+            `output_config.effort` (low|medium|high|xhigh|max) or to `OpenAIWrapper`
+            as `reasoning_effort` (none|low|medium|high|xhigh). Used by the
+            "anthropic" and "openai" providers.
         prompt_caching (bool): Whether `AnthropicWrapper` should send top-level `cache_control`.
             Defaults to True. Only used by the "anthropic" provider.
         max_tool_rounds (int): Maximum number of tool-call round-trips forwarded to
             `LLMInterface`. Defaults to 5. Used by the "openai" and "anthropic" providers.
+        openai_api (Literal["responses", "chat"]): Which OpenAI API the "openai"
+            provider talks to. "responses" (the default) supports reasoning
+            together with function tools; "chat" is the Chat Completions API.
 
     Returns:
         LLMInterface: Configured interface for interacting with the specified LLM.
@@ -154,8 +160,14 @@ def llm_from_config(
             api_key = os.getenv("OPENAI_API_KEY")
             if api_key is None:
                 raise ValueError("OPENAI_API_KEY not found in environment variables")
-            wrapper = OpenAIWrapper(
-                api_key=api_key, max_tokens=max_tokens, timeout=timeout
+            wrapper_class = (
+                OpenAIResponsesWrapper if openai_api == "responses" else OpenAIWrapper
+            )
+            wrapper = wrapper_class(
+                api_key=api_key,
+                max_tokens=max_tokens,
+                timeout=timeout,
+                reasoning_effort=effort,
             )
 
             support_structured_outputs = supports_structured_output(model_name)

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/llm_interface.py

@@ -47,6 +47,10 @@ class ModelError(Exception):
     pass
 
 
+# seconds to wait (times the attempt number) after a provider rate limit
+RATE_LIMIT_RETRY_DELAY = 15.0
+
+
 class LLMInterface:
     """
     A unified interface for interacting with various Language Learning Models (LLMs).
@@ -180,7 +184,10 @@ class LLMInterface:
         return new_model
 
     def _execute_tool_calls(
-        self, tool_calls: List[Dict[str, Any]], tools: List[Tool]
+        self,
+        tool_calls: List[Dict[str, Any]],
+        tools: List[Tool],
+        assistant_extra: Optional[Dict[str, Any]] = None,
     ) -> List[Dict[str, Any]]:
         """Execute every tool call made in a single assistant turn, as one unit.
 
@@ -199,6 +206,9 @@ class LLMInterface:
         Args:
             tool_calls (List[Dict[str, Any]]): The tool calls from the assistant's response.
             tools (List[Tool]): The tools available for execution.
+            assistant_extra (Optional[Dict[str, Any]]): Extra keys to keep on the
+                assistant message, e.g. provider-specific items a client needs to
+                replay on the next request.
 
         Returns:
             List[Dict[str, Any]]: ``[assistant_message, tool_message, ...]`` - one
@@ -287,11 +297,13 @@ class LLMInterface:
                     }
                 )
 
-        assistant_message = {
+        assistant_message: Dict[str, Any] = {
             "role": "assistant",
             "content": "",
             "tool_calls": assistant_tool_calls,
         }
+        if assistant_extra:
+            assistant_message.update(assistant_extra)
 
         return [assistant_message] + tool_messages
 
@@ -346,25 +358,24 @@ class LLMInterface:
 
             self.logger.info("Received chat response: %s", response)
 
-            # Check for timeout error
-            if (
-                "error" in response
-                and "error_type" in response
-                and (
-                    response.get("error_type") == errors.TIMEOUT
-                    or response.get("error_type") == errors.CONNECTION
-                )
-            ):
+            # Check for a transient error: timeouts, connection problems and
+            # rate limits are retried with a growing delay
+            error_type = response.get("error_type") if "error" in response else None
+            if error_type in (errors.TIMEOUT, errors.CONNECTION, errors.RATE_LIMIT):
                 retry_count += 1
                 if retry_count <= self.max_retries:
+                    delay = self.retry_delay * retry_count
+                    if error_type == errors.RATE_LIMIT:
+                        # per-minute token limits need real time to clear
+                        delay = max(delay, RATE_LIMIT_RETRY_DELAY * retry_count)
                     self.logger.warning(
                         "Request error (%s). Retrying (%d/%d) after %.1f seconds...",
                         response["error"],
                         retry_count,
                         self.max_retries,
-                        self.retry_delay * retry_count,
+                        delay,
                     )
-                    time.sleep(self.retry_delay * retry_count)
+                    time.sleep(delay)
                     continue
                 else:
                     self.logger.error(
@@ -390,6 +401,7 @@ class LLMInterface:
                 total_tokens=usage_data.get("total_tokens", 0),
                 cached_tokens=usage_data.get("cached_tokens", 0),
                 reasoning_tokens=usage_data.get("reasoning_tokens", 0),
+                cache_creation_tokens=usage_data.get("cache_creation_tokens", 0),
             )
 
         return response
@@ -523,8 +535,19 @@ class LLMInterface:
 
                 self.logger.info("Received tool calls: %s", tool_calls)
                 # Execute all tool calls from this turn as one unit and add
-                # the results to the conversation.
-                tool_messages = self._execute_tool_calls(tool_calls, tools or [])
+                # the results to the conversation. Clients that replay their
+                # own output items (the Responses API) keep them on the
+                # assistant message.
+                assistant_extra = None
+                if getattr(self.client, "keeps_provider_items", False):
+                    assistant_extra = {
+                        key: value
+                        for key, value in response.get("message", {}).items()
+                        if key not in ("content", "tool_calls")
+                    }
+                tool_messages = self._execute_tool_calls(
+                    tool_calls, tools or [], assistant_extra=assistant_extra
+                )
                 current_messages.extend(tool_messages)
 
                 if num_tool_rounds >= effective_max_tool_rounds:

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/openai.py

@@ -14,14 +14,17 @@
 import json
 import logging
 from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Set
 
 from ollama import ListResponse
+from openai import pydantic_function_tool
 from openai import (
     APITimeoutError,
+    BadRequestError,
     ContentFilterFinishReasonError,
     LengthFinishReasonError,
     OpenAI,
+    RateLimitError,
 )
 
 from . import errors
@@ -164,14 +167,93 @@ def convert_openai_models_to_ollama_response(openai_models_data) -> ListResponse
     return ListResponse(models=ollama_models)
 
 
+def _json_schema_response_format(schema: Any) -> Dict[str, Any]:
+    """A strict ``json_schema`` response_format for a Pydantic model, built the
+    same way the SDK's ``parse`` helper builds it."""
+    strict_schema = pydantic_function_tool(schema)["function"]["parameters"]
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": schema.__name__,
+            "schema": strict_schema,
+            "strict": True,
+        },
+    }
+
+
 class OpenAIWrapper:
-    def __init__(self, api_key: str, max_tokens: int = 4096, timeout: float = 600.0):
+    def __init__(
+        self,
+        api_key: str,
+        max_tokens: int = 4096,
+        timeout: float = 600.0,
+        reasoning_effort: Optional[str] = None,
+    ):
+        """
+        Args:
+            api_key (str): OpenAI API key.
+            max_tokens (int): Default ``max_completion_tokens`` for requests.
+            timeout (float): Request timeout in seconds.
+            reasoning_effort (Optional[str]): Forwarded as ``reasoning_effort`` on
+                every request for reasoning models (e.g. "none", "low", "medium",
+                "high"). None leaves the model default.
+        """
         self.client = OpenAI(api_key=api_key, timeout=timeout)
         self.max_tokens = max_tokens
+        self.reasoning_effort = reasoning_effort
+        # models (gpt-5.6-luna on chat completions) that only accept function
+        # tools with reasoning_effort "none"; filled in after the first rejection
+        self._effort_rejected_with_tools: Set[str] = set()
 
     def list(self) -> ListResponse:
         return convert_openai_models_to_ollama_response(self.client.models.list())
 
+    def _complete(
+        self,
+        api_params: Dict[str, Any],
+        tools: Optional[List[Dict[str, Any]]],
+        kwargs: Dict[str, Any],
+    ):
+        """One request. Returns (response, message, content), or a refusal dict."""
+        if "response_schema" in kwargs:
+            schema = kwargs["response_schema"]
+            strict_tools = all(
+                tool.get("function", {}).get("strict") for tool in (tools or [])
+            )
+            if strict_tools:
+                # `client.beta.chat.completions.parse` is deprecated in openai
+                # 3.x; use the stable `client.chat.completions.parse` instead.
+                response = self.client.chat.completions.parse(
+                    response_format=schema,
+                    **api_params,
+                )
+                message = response.choices[0].message
+
+                # Check for refusal
+                if "refusal" in message:
+                    return {"refusal": message.refusal, "content": None, "done": False}
+
+                return response, message, message.parsed
+
+            # parse() refuses to run with non-strict function tools (any tool
+            # with an optional parameter). Ask for the schema as a strict
+            # json_schema response_format instead and hand the JSON text back;
+            # LLMInterface validates it against the model.
+            response = self.client.chat.completions.create(
+                response_format=_json_schema_response_format(schema),
+                **api_params,
+            )
+            message = response.choices[0].message
+            if getattr(message, "refusal", None):
+                return {"refusal": message.refusal, "content": None, "done": False}
+            return response, message, message.content
+
+        if "format" in kwargs and kwargs["format"] == "json":
+            api_params["response_format"] = {"type": "json_object"}
+        response = self.client.chat.completions.create(**api_params)
+        message = response.choices[0].message
+        return response, message, message.content
+
     def chat(
         self,
         messages: List[Dict[str, Any]],
@@ -235,29 +317,40 @@ class OpenAIWrapper:
         if kwargs.get("tool_choice") is not None:
             api_params["tool_choice"] = kwargs["tool_choice"]
 
+        if tools and api_params["model"] in self._effort_rejected_with_tools:
+            api_params["reasoning_effort"] = "none"
+        elif self.reasoning_effort is not None:
+            api_params["reasoning_effort"] = self.reasoning_effort
+
         logging.debug("API parameters: %s", api_params)
 
         try:
-            if "response_schema" in kwargs:
-                # `client.beta.chat.completions.parse` is deprecated in openai
-                # 3.x; use the stable `client.chat.completions.parse` instead.
-                response = self.client.chat.completions.parse(
-                    response_format=kwargs.get("response_schema"),
-                    **api_params,
-                )
-                message = response.choices[0].message
-
-                # Check for refusal
-                if "refusal" in message:
-                    return {"refusal": message.refusal, "content": None, "done": False}
-
-                content = message.parsed
-            else:
-                if "format" in kwargs and kwargs["format"] == "json":
-                    api_params["response_format"] = {"type": "json_object"}
-                response = self.client.chat.completions.create(**api_params)
-                message = response.choices[0].message
-                content = message.content
+            try:
+                completed = self._complete(api_params, tools, kwargs)
+            except BadRequestError as e:
+                message_text = str(e)
+                if (
+                    tools
+                    and "reasoning_effort" in message_text
+                    and "not supported" in message_text
+                    and api_params.get("reasoning_effort") != "none"
+                ):
+                    # e.g. "Function tools with reasoning_effort are not supported
+                    # for gpt-5.6-luna in /v1/chat/completions. To use function
+                    # tools, use /v1/responses or set reasoning_effort to 'none'."
+                    logging.warning(
+                        "%s only accepts function tools with reasoning_effort "
+                        "'none' on chat completions; retrying that way",
+                        api_params["model"],
+                    )
+                    self._effort_rejected_with_tools.add(api_params["model"])
+                    api_params["reasoning_effort"] = "none"
+                    completed = self._complete(api_params, tools, kwargs)
+                else:
+                    raise
+            if isinstance(completed, dict):
+                return completed  # a refusal
+            response, message, content = completed
 
             # Log the usage details
             usage = response.usage
@@ -288,9 +381,13 @@ class OpenAIWrapper:
                 "done": response.choices[0].finish_reason == "stop",
             }
             if usage.prompt_tokens_details:
-                return_message["usage"][
-                    "cached_tokens"
-                ] = usage.prompt_tokens_details.cached_tokens
+                return_message["usage"]["cached_tokens"] = (
+                    usage.prompt_tokens_details.cached_tokens or 0
+                )
+            if usage.completion_tokens_details:
+                return_message["usage"]["reasoning_tokens"] = (
+                    usage.completion_tokens_details.reasoning_tokens or 0
+                )
             # Check for tool calls
             if message.tool_calls:
                 return_message["message"]["tool_calls"] = [
@@ -321,6 +418,14 @@ class OpenAIWrapper:
                 "done": False,
                 "usage": None,
             }
+        except RateLimitError as e:
+            return {
+                "error": f"Rate limited: {e}",
+                "error_type": errors.RATE_LIMIT,
+                "content": None,
+                "done": False,
+                "usage": None,
+            }
         except APITimeoutError:
             # Handle the timeout error
             return {

llm_interface-0.2.2/llm_interface/openai_responses.py

@@ -0,0 +1,351 @@
+# Copyright 2024 Niels Provos
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""OpenAI Responses API wrapper.
+
+The Responses API is where OpenAI's reasoning models expose reasoning together
+with function tools (chat completions only allows tools with
+``reasoning_effort="none"``). Requests are stateless (``store=False``): the whole
+transcript is translated into input items on every round, and the items the
+model produced in a tool-calling turn (reasoning, function calls) are replayed
+verbatim on the next round so the model keeps its reasoning across tool calls.
+"""
+
+import json
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from ollama import ListResponse
+from openai import (
+    APIConnectionError,
+    APITimeoutError,
+    OpenAI,
+    RateLimitError,
+    pydantic_function_tool,
+)
+
+from . import errors
+from .openai import convert_openai_models_to_ollama_response
+from .utils import encode_image_to_base64
+
+# Key on an assistant message under which LLMInterface keeps the raw output items
+# of a tool-calling turn so this wrapper can replay them.
+PROVIDER_ITEMS = "provider_items"
+
+
+def translate_tools_for_responses(
+    tools: Optional[List[Dict[str, Any]]],
+) -> List[Dict[str, Any]]:
+    """Chat-completions style tools (``{"type": "function", "function": {...}}``)
+    to the flat Responses API shape."""
+    translated = []
+    for tool in tools or []:
+        function = tool.get("function", tool)
+        translated.append(
+            {
+                "type": "function",
+                "name": function["name"],
+                "description": function.get("description", ""),
+                "parameters": function.get(
+                    "parameters", {"type": "object", "properties": {}}
+                ),
+                "strict": bool(function.get("strict", False)),
+            }
+        )
+    return translated
+
+
+def translate_messages_for_responses(
+    messages: List[Dict[str, Any]],
+) -> Tuple[Optional[str], List[Dict[str, Any]]]:
+    """Ollama/API style messages to (instructions, input items).
+
+    System messages become the ``instructions`` string; an assistant turn with
+    tool calls becomes its replayed provider items when it has them, otherwise
+    one ``function_call`` item per call; tool messages become
+    ``function_call_output`` items.
+    """
+    instruction_parts: List[str] = []
+    items: List[Dict[str, Any]] = []
+
+    for msg in messages:
+        role = msg.get("role")
+        if role == "system":
+            if msg.get("content"):
+                instruction_parts.append(msg["content"])
+        elif role == "user":
+            if msg.get("images"):
+                content: List[Dict[str, Any]] = [
+                    {"type": "input_text", "text": msg.get("content", "")}
+                ]
+                for image in msg["images"]:
+                    image_type = image.split(".")[-1].lower()
+                    content.append(
+                        {
+                            "type": "input_image",
+                            "image_url": f"data:image/{image_type};base64,"
+                            + encode_image_to_base64(image),
+                        }
+                    )
+                items.append({"role": "user", "content": content})
+            else:
+                items.append({"role": "user", "content": msg.get("content", "")})
+        elif role == "assistant" and msg.get("tool_calls"):
+            if msg.get(PROVIDER_ITEMS):
+                items.extend(msg[PROVIDER_ITEMS])
+                continue
+            if msg.get("content"):
+                items.append({"role": "assistant", "content": msg["content"]})
+            for tool_call in msg["tool_calls"]:
+                call_id = tool_call.get("id")
+                if not call_id:
+                    raise ValueError(
+                        "An assistant tool call must carry the id its result "
+                        f"answers; got {tool_call!r}"
+                    )
+                function = tool_call.get("function", tool_call)
+                arguments = function.get("arguments", {})
+                if not isinstance(arguments, str):
+                    arguments = json.dumps(arguments)
+                items.append(
+                    {
+                        "type": "function_call",
+                        "call_id": call_id,
+                        "name": function["name"],
+                        "arguments": arguments,
+                    }
+                )
+        elif role == "tool":
+            if not msg.get("tool_call_id"):
+                raise ValueError(
+                    "A tool message must carry the tool_call_id it answers; "
+                    f"got {msg!r}"
+                )
+            items.append(
+                {
+                    "type": "function_call_output",
+                    "call_id": msg["tool_call_id"],
+                    "output": str(msg.get("content", "")),
+                }
+            )
+        elif role == "assistant":
+            items.append({"role": "assistant", "content": msg.get("content", "")})
+        else:
+            raise ValueError(f"Unsupported message role: {role!r}")
+
+    instructions = "\n\n".join(instruction_parts) or None
+    return instructions, items
+
+
+def _json_schema_text_format(schema: Any) -> Dict[str, Any]:
+    strict_schema = pydantic_function_tool(schema)["function"]["parameters"]
+    return {
+        "format": {
+            "type": "json_schema",
+            "name": schema.__name__,
+            "schema": strict_schema,
+            "strict": True,
+        }
+    }
+
+
+class OpenAIResponsesWrapper:
+    """Client for the OpenAI Responses API with the same ``chat()`` contract as
+    the other wrappers."""
+
+    # LLMInterface keeps the raw output items of tool-calling turns on the
+    # transcript for clients that declare this
+    keeps_provider_items = True
+
+    def __init__(
+        self,
+        api_key: str,
+        max_tokens: int = 4096,
+        timeout: float = 600.0,
+        reasoning_effort: Optional[str] = None,
+    ):
+        """
+        Args:
+            api_key (str): OpenAI API key.
+            max_tokens (int): Default ``max_output_tokens`` for requests.
+            timeout (float): Request timeout in seconds.
+            reasoning_effort (Optional[str]): ``reasoning.effort`` for every
+                request ("none", "low", "medium", "high", ...). None leaves the
+                model default.
+        """
+        self.client = OpenAI(api_key=api_key, timeout=timeout)
+        self.max_tokens = max_tokens
+        self.reasoning_effort = reasoning_effort
+
+    def list(self) -> ListResponse:
+        return convert_openai_models_to_ollama_response(self.client.models.list())
+
+    def chat(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        One request to the Responses API.
+
+        Args:
+            messages: Conversation in the shared message format (system, user,
+                assistant with optional tool_calls, tool).
+            tools: Tools in the ``{"type": "function", "function": {...}}`` shape.
+            **kwargs: ``model``, ``max_tokens``, ``options`` (temperature),
+                ``response_schema`` (Pydantic model: strict json_schema output),
+                ``format`` ("json"), ``tool_choice``.
+
+        Returns:
+            The shared response dict: ``message`` (content, tool_calls,
+            provider_items), ``usage``, ``done``; or ``error``/``refusal`` entries.
+        """
+        instructions, input_items = translate_messages_for_responses(messages)
+
+        params: Dict[str, Any] = {
+            "model": kwargs.get("model", "gpt-5"),
+            "input": input_items,
+            "max_output_tokens": kwargs.get("max_tokens", self.max_tokens),
+            # stateless: the transcript is replayed in full on every round
+            "store": False,
+        }
+        if instructions:
+            params["instructions"] = instructions
+        if tools:
+            params["tools"] = translate_tools_for_responses(tools)
+        if kwargs.get("tool_choice") is not None:
+            params["tool_choice"] = kwargs["tool_choice"]
+        if "options" in kwargs and "temperature" in kwargs["options"]:
+            params["temperature"] = kwargs["options"]["temperature"]
+        if self.reasoning_effort is not None:
+            params["reasoning"] = {"effort": self.reasoning_effort}
+        if self.reasoning_effort != "none":
+            # reasoning items can only be replayed with their encrypted content
+            params["include"] = ["reasoning.encrypted_content"]
+        if "response_schema" in kwargs:
+            params["text"] = _json_schema_text_format(kwargs["response_schema"])
+        elif kwargs.get("format") == "json":
+            params["text"] = {"format": {"type": "json_object"}}
+
+        logging.debug("Responses API parameters: %s", params)
+
+        try:
+            response = self.client.responses.create(**params)
+        except APITimeoutError:
+            return {
+                "error": "Request timed out.",
+                "error_type": errors.TIMEOUT,
+                "content": None,
+                "done": False,
+                "usage": None,
+            }
+        except RateLimitError as e:
+            return {
+                "error": f"Rate limited: {e}",
+                "error_type": errors.RATE_LIMIT,
+                "content": None,
+                "done": False,
+                "usage": None,
+            }
+        except APIConnectionError as e:
+            return {
+                "error": f"Connection error: {e}",
+                "error_type": errors.CONNECTION,
+                "content": None,
+                "done": False,
+                "usage": None,
+            }
+
+        return self._translate_response(response)
+
+    @staticmethod
+    def _translate_response(response: Any) -> Dict[str, Any]:
+        output = list(getattr(response, "output", None) or [])
+        tool_calls: List[Dict[str, Any]] = []
+        texts: List[str] = []
+        refusal: Optional[str] = None
+        for item in output:
+            item_type = getattr(item, "type", None)
+            if item_type == "function_call":
+                tool_calls.append(
+                    {"id": item.call_id, "name": item.name, "arguments": item.arguments}
+                )
+            elif item_type == "message":
+                for part in getattr(item, "content", None) or []:
+                    part_type = getattr(part, "type", None)
+                    if part_type == "output_text":
+                        texts.append(part.text)
+                    elif part_type == "refusal":
+                        refusal = part.refusal
+
+        usage = response.usage
+        input_details = getattr(usage, "input_tokens_details", None)
+        output_details = getattr(usage, "output_tokens_details", None)
+        usage_info = {
+            "prompt_tokens": usage.input_tokens,
+            "completion_tokens": usage.output_tokens,
+            "total_tokens": usage.total_tokens,
+            "cached_tokens": _usage_int(getattr(input_details, "cached_tokens", 0)),
+            "reasoning_tokens": _usage_int(
+                getattr(output_details, "reasoning_tokens", 0)
+            ),
+        }
+
+        status = getattr(response, "status", None)
+        if status == "incomplete":
+            details = getattr(response, "incomplete_details", None)
+            reason = getattr(details, "reason", None)
+            if reason == "max_output_tokens":
+                return {
+                    "error": "Response exceeded the maximum allowed length.",
+                    "error_type": errors.LENGTH,
+                    "content": None,
+                    "done": False,
+                    "usage": usage_info,
+                }
+            if reason == "content_filter":
+                return {
+                    "error": "Content was rejected by the content filter.",
+                    "error_type": errors.CONTENT_FILTER,
+                    "content": None,
+                    "done": False,
+                    "usage": usage_info,
+                }
+
+        if refusal is not None and not tool_calls:
+            return {
+                "refusal": refusal,
+                "content": None,
+                "done": False,
+                "usage": usage_info,
+            }
+
+        message: Dict[str, Any] = {"content": "".join(texts)}
+        if tool_calls:
+            message["tool_calls"] = tool_calls
+            # everything the model emitted this turn (reasoning, calls, text),
+            # replayed verbatim on the next request
+            message[PROVIDER_ITEMS] = [
+                item.model_dump(exclude_none=True) for item in output
+            ]
+
+        return {
+            "message": message,
+            "usage": usage_info,
+            "done": status == "completed" and not tool_calls,
+        }
+
+
+def _usage_int(value: Any) -> int:
+    return value if isinstance(value, int) else 0

{llm_interface-0.2.0 → llm_interface-0.2.2}/llm_interface/token_usage.py

@@ -27,14 +27,21 @@ class TokenUsage(BaseModel):
         prompt_tokens (int): Number of tokens used in the prompt/input
         completion_tokens (int): Number of tokens generated in the response
         total_tokens (int): Total tokens used (prompt + completion)
-        cached_tokens (int): Number of tokens retrieved from cache (if supported)
-        reasoning_tokens (int): Number of tokens used for reasoning (if supported)
+        cached_tokens (int): Number of prompt tokens read from the provider's prompt
+            cache (if supported); they are billed at the cache-read rate
+        cache_creation_tokens (int): Number of prompt tokens written to the provider's
+            prompt cache (if supported); billed at the cache-write rate
+        reasoning_tokens (int): Number of tokens used for reasoning (if supported).
+            Reasoning tokens are part of completion_tokens. For Anthropic this is an
+            estimate: output tokens not accounted for by the visible text and tool calls
+            when the response contains thinking blocks
     """
 
     prompt_tokens: int = 0
     completion_tokens: int = 0
     total_tokens: int = 0
     cached_tokens: int = 0
+    cache_creation_tokens: int = 0
     reasoning_tokens: int = 0
 
     def update(
@@ -44,6 +51,7 @@ class TokenUsage(BaseModel):
         total_tokens: int = 0,
         cached_tokens: int = 0,
         reasoning_tokens: int = 0,
+        cache_creation_tokens: int = 0,
     ):
         """
         Updates token usage statistics.
@@ -54,6 +62,7 @@ class TokenUsage(BaseModel):
             total_tokens (int): Total tokens used
             cached_tokens (int): Number of tokens from cache
             reasoning_tokens (int): Number of reasoning tokens
+            cache_creation_tokens (int): Number of tokens written to the prompt cache
             **kwargs: Additional provider-specific metrics
         """
         self.prompt_tokens += prompt_tokens
@@ -66,6 +75,7 @@ class TokenUsage(BaseModel):
             self.total_tokens += prompt_tokens + completion_tokens
 
         self.cached_tokens += cached_tokens
+        self.cache_creation_tokens += cache_creation_tokens
         self.reasoning_tokens += reasoning_tokens
 
     def reset(self):
@@ -74,6 +84,7 @@ class TokenUsage(BaseModel):
         self.completion_tokens = 0
         self.total_tokens = 0
         self.cached_tokens = 0
+        self.cache_creation_tokens = 0
         self.reasoning_tokens = 0
 
     def get_all_stats(self) -> Dict[str, int]:
@@ -92,6 +103,8 @@ class TokenUsage(BaseModel):
         # Only include non-zero values for optional fields
         if self.cached_tokens > 0:
             stats["cached_tokens"] = self.cached_tokens
+        if self.cache_creation_tokens > 0:
+            stats["cache_creation_tokens"] = self.cache_creation_tokens
         if self.reasoning_tokens > 0:
             stats["reasoning_tokens"] = self.reasoning_tokens
 
@@ -102,6 +115,8 @@ class TokenUsage(BaseModel):
         result = f"Token usage: {self.total_tokens} total ({self.prompt_tokens} prompt, {self.completion_tokens} completion)"
         if self.cached_tokens > 0:
             result += f", {self.cached_tokens} cached"
+        if self.cache_creation_tokens > 0:
+            result += f", {self.cache_creation_tokens} cache writes"
         if self.reasoning_tokens > 0:
             result += f", {self.reasoning_tokens} reasoning"
         return result

{llm_interface-0.2.0 → llm_interface-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "llm-interface"
-version = "0.2.0"
+version = "0.2.2"
 description = "A flexible interface for working with various LLM providers"
 authors = ["Niels Provos <provos@gmail.com>"]
 license = "Apache-2.0"