ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/providers/__init__.py

@@ -0,0 +1,37 @@
+"""Provider adapter factory (SPEC section 11)."""
+
+from __future__ import annotations
+
+from ctxoptimizer.models import Endpoint, Provider
+from ctxoptimizer.providers.anthropic import AnthropicAdapter
+from ctxoptimizer.providers.base import PassthroughAdapter, ProviderAdapter
+from ctxoptimizer.providers.gemini import GeminiAdapter
+from ctxoptimizer.providers.ollama import OllamaAdapter
+from ctxoptimizer.providers.openai_chat import OpenAIChatAdapter
+from ctxoptimizer.providers.openai_responses import OpenAIResponsesAdapter
+
+
+def adapter_for(provider: Provider, endpoint: Endpoint) -> ProviderAdapter:
+    if provider is Provider.ANTHROPIC:
+        return AnthropicAdapter()
+    if provider is Provider.OPENAI:
+        if endpoint is Endpoint.RESPONSES:
+            return OpenAIResponsesAdapter()
+        return OpenAIChatAdapter()
+    if provider is Provider.GEMINI:
+        return GeminiAdapter()
+    if provider is Provider.OLLAMA:
+        return OllamaAdapter()
+    return PassthroughAdapter(provider)
+
+
+__all__ = [
+    "AnthropicAdapter",
+    "GeminiAdapter",
+    "OllamaAdapter",
+    "OpenAIChatAdapter",
+    "OpenAIResponsesAdapter",
+    "PassthroughAdapter",
+    "ProviderAdapter",
+    "adapter_for",
+]

ctxoptimizer/providers/anthropic.py

@@ -0,0 +1,105 @@
+"""Anthropic Messages adapter (SPEC section 11.1)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from ctxoptimizer.analysis.segments import Segment, make_segment
+from ctxoptimizer.models import Provider, ToolResultRef
+from ctxoptimizer.providers.base import (
+    DictToolResultRef,
+    blocks_of,
+    text_of,
+)
+
+
+class AnthropicAdapter:
+    provider = Provider.ANTHROPIC
+
+    def model_of(self, payload: dict[str, Any]) -> str | None:
+        model = payload.get("model")
+        return model if isinstance(model, str) else None
+
+    def is_stream(self, payload: dict[str, Any]) -> bool:
+        return bool(payload.get("stream"))
+
+    def is_transformable(self, payload: dict[str, Any]) -> bool:
+        return True
+
+    def iter_tool_results(self, payload: dict[str, Any]) -> Iterator[ToolResultRef]:
+        names = self._tool_use_names(payload)
+        for message_index, message in enumerate(payload.get("messages") or []):
+            if not isinstance(message, dict):
+                continue
+            for block_index, block in enumerate(blocks_of(message.get("content"))):
+                if block.get("type") != "tool_result":
+                    continue
+                tool_use_id = str(block.get("tool_use_id") or "")
+                yield DictToolResultRef(
+                    block,
+                    message_index=message_index,
+                    block_index=block_index,
+                    tool_use_id=tool_use_id,
+                    tool_name=names.get(tool_use_id),
+                    is_error=bool(block.get("is_error")),
+                    key="content",
+                )
+
+    def segments(self, payload: dict[str, Any]) -> list[Segment]:
+        result: list[Segment] = []
+        for index, tool in enumerate(payload.get("tools") or []):
+            if isinstance(tool, dict):
+                result.append(make_segment("tool_def", tool, block_index=index))
+        system = payload.get("system")
+        system_blocks = blocks_of(system)
+        if isinstance(system, str):
+            system_blocks = [{"type": "text", "text": system}]
+        for index, block in enumerate(system_blocks):
+            result.append(make_segment("system", block, block_index=index))
+        for message_index, message in enumerate(payload.get("messages") or []):
+            if not isinstance(message, dict):
+                continue
+            role = str(message.get("role") or "")
+            for block_index, block in enumerate(blocks_of(message.get("content"))):
+                result.append(
+                    make_segment(
+                        "message",
+                        {**block, "role": role},
+                        msg_index=message_index,
+                        block_index=block_index,
+                    )
+                )
+        return result
+
+    def system_text(self, payload: dict[str, Any]) -> str:
+        return text_of(payload.get("system"))
+
+    def first_user_text(self, payload: dict[str, Any]) -> str:
+        for message in payload.get("messages") or []:
+            if isinstance(message, dict) and message.get("role") == "user":
+                return text_of(message.get("content"))
+        return ""
+
+    def tool_names(self, payload: dict[str, Any]) -> list[str]:
+        return [
+            str(tool["name"])
+            for tool in payload.get("tools") or []
+            if isinstance(tool, dict) and isinstance(tool.get("name"), str)
+        ]
+
+    def used_tool_names(self, payload: dict[str, Any]) -> list[str]:
+        return list(self._tool_use_names(payload).values())
+
+    def _tool_use_names(self, payload: dict[str, Any]) -> dict[str, str]:
+        names: dict[str, str] = {}
+        for message in payload.get("messages") or []:
+            if not isinstance(message, dict):
+                continue
+            for block in blocks_of(message.get("content")):
+                if block.get("type") == "tool_use" and isinstance(block.get("id"), str):
+                    names[block["id"]] = str(block.get("name") or "")
+        return names
+
+
+__all__ = ["AnthropicAdapter"]

ctxoptimizer/providers/base.py

@@ -0,0 +1,191 @@
+"""Provider adapter protocol and shared payload helpers (SPEC section 11)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Protocol
+
+from ctxoptimizer.analysis.segments import Segment
+from ctxoptimizer.models import Provider, ToolResultRef
+
+
+class ProviderAdapter(Protocol):
+    provider: Provider
+
+    def model_of(self, payload: dict[str, Any]) -> str | None: ...
+
+    def is_stream(self, payload: dict[str, Any]) -> bool: ...
+
+    def is_transformable(self, payload: dict[str, Any]) -> bool: ...
+
+    def iter_tool_results(self, payload: dict[str, Any]) -> Iterator[ToolResultRef]: ...
+
+    def segments(self, payload: dict[str, Any]) -> list[Segment]: ...
+
+    def system_text(self, payload: dict[str, Any]) -> str: ...
+
+    def first_user_text(self, payload: dict[str, Any]) -> str: ...
+
+    def tool_names(self, payload: dict[str, Any]) -> list[str]: ...
+
+    def used_tool_names(self, payload: dict[str, Any]) -> list[str]: ...
+
+
+class DictToolResultRef(ToolResultRef):
+    """Edits a text-bearing ``content``/``output`` field inside a JSON block."""
+
+    __slots__ = ("_block", "_key")
+
+    def __init__(
+        self,
+        block: dict[str, Any],
+        *,
+        message_index: int,
+        block_index: int | None,
+        tool_use_id: str,
+        tool_name: str | None,
+        is_error: bool,
+        key: str,
+    ) -> None:
+        super().__init__(
+            message_index=message_index,
+            block_index=block_index,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            is_error=is_error,
+        )
+        self._block = block
+        self._key = key
+
+    def get_text(self) -> str | None:
+        return content_text(self._block.get(self._key))
+
+    def set_text(self, new_text: str) -> None:
+        set_content_text(self._block, self._key, new_text)
+
+
+class MappingToolResultRef(ToolResultRef):
+    """Edits a string value on a mapping (Gemini functionResponse)."""
+
+    __slots__ = ("_block", "_key")
+
+    def __init__(
+        self,
+        block: dict[str, Any],
+        *,
+        key: str,
+        message_index: int,
+        block_index: int | None,
+        tool_use_id: str,
+        tool_name: str | None,
+        is_error: bool,
+    ) -> None:
+        super().__init__(
+            message_index=message_index,
+            block_index=block_index,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            is_error=is_error,
+        )
+        self._block = block
+        self._key = key
+
+    def get_text(self) -> str | None:
+        value = self._block.get(self._key)
+        return value if isinstance(value, str) else None
+
+    def set_text(self, new_text: str) -> None:
+        self._block[self._key] = new_text
+
+
+def content_text(value: Any) -> str | None:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts = [
+            part.get("text", "")
+            for part in value
+            if isinstance(part, dict) and part.get("type") == "text"
+        ]
+        return "".join(parts)
+    return None
+
+
+def set_content_text(block: dict[str, Any], key: str, text: str) -> None:
+    value = block.get(key)
+    if isinstance(value, list):
+        remaining = [
+            part for part in value if not (isinstance(part, dict) and part.get("type") == "text")
+        ]
+        block[key] = [{"type": "text", "text": text}, *remaining]
+    else:
+        block[key] = text
+
+
+def blocks_of(content: Any) -> list[dict[str, Any]]:
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    if isinstance(content, list):
+        return [block for block in content if isinstance(block, dict)]
+    return []
+
+
+def text_of(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return "".join(
+            part.get("text", "")
+            for part in value
+            if isinstance(part, dict) and part.get("type") == "text"
+        )
+    return ""
+
+
+class PassthroughAdapter:
+    """No structural access; used for native Gemini/Ollama until P6."""
+
+    provider: Provider
+
+    def __init__(self, provider: Provider) -> None:
+        self.provider = provider
+
+    def model_of(self, payload: dict[str, Any]) -> str | None:
+        model = payload.get("model")
+        return model if isinstance(model, str) else None
+
+    def is_stream(self, payload: dict[str, Any]) -> bool:
+        return bool(payload.get("stream"))
+
+    def is_transformable(self, payload: dict[str, Any]) -> bool:
+        return False
+
+    def iter_tool_results(self, payload: dict[str, Any]) -> Iterator[ToolResultRef]:
+        return iter(())
+
+    def segments(self, payload: dict[str, Any]) -> list[Segment]:
+        return []
+
+    def system_text(self, payload: dict[str, Any]) -> str:
+        return ""
+
+    def first_user_text(self, payload: dict[str, Any]) -> str:
+        return ""
+
+    def tool_names(self, payload: dict[str, Any]) -> list[str]:
+        return []
+
+    def used_tool_names(self, payload: dict[str, Any]) -> list[str]:
+        return []
+
+
+__all__ = [
+    "DictToolResultRef",
+    "MappingToolResultRef",
+    "PassthroughAdapter",
+    "ProviderAdapter",
+    "blocks_of",
+    "content_text",
+    "set_content_text",
+    "text_of",
+]

ctxoptimizer/providers/gemini.py

@@ -0,0 +1,143 @@
+"""Native Gemini ``generateContent`` adapter (SPEC section 11.4, P6-1).
+
+Telemetry first: segments and tool-result handles are exposed so the analysis
+layer can measure usage. Transforms only touch string leaves inside
+``functionResponse`` parts, which is the byte-true subset.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from ctxoptimizer.analysis.segments import Segment, make_segment
+from ctxoptimizer.models import Provider, ToolResultRef
+from ctxoptimizer.providers.base import MappingToolResultRef, text_of
+
+
+class GeminiAdapter:
+    provider = Provider.GEMINI
+
+    def model_of(self, payload: dict[str, Any]) -> str | None:
+        model = payload.get("model")
+        return model if isinstance(model, str) else None
+
+    def is_stream(self, payload: dict[str, Any]) -> bool:
+        return bool(payload.get("stream"))
+
+    def is_transformable(self, payload: dict[str, Any]) -> bool:
+        return isinstance(payload.get("contents"), list)
+
+    def iter_tool_results(self, payload: dict[str, Any]) -> Iterator[ToolResultRef]:
+        for message_index, content in enumerate(payload.get("contents") or []):
+            if not isinstance(content, dict):
+                continue
+            for block_index, part in enumerate(content.get("parts") or []):
+                if not isinstance(part, dict):
+                    continue
+                response = part.get("functionResponse")
+                if not isinstance(response, dict):
+                    continue
+                name = str(response.get("name") or "")
+                handle = _response_handle(response)
+                if handle is None:
+                    continue
+                parent, key, is_error = handle
+                yield MappingToolResultRef(
+                    parent,
+                    key=key,
+                    message_index=message_index,
+                    block_index=block_index,
+                    tool_use_id=name,
+                    tool_name=name or None,
+                    is_error=is_error,
+                )
+
+    def segments(self, payload: dict[str, Any]) -> list[Segment]:
+        result: list[Segment] = []
+        for tool in payload.get("tools") or []:
+            if not isinstance(tool, dict):
+                continue
+            result.extend(
+                make_segment("tool_def", declaration)
+                for declaration in tool.get("functionDeclarations") or []
+                if isinstance(declaration, dict)
+            )
+        system = _parts(payload.get("systemInstruction"))
+        for index, part in enumerate(system):
+            result.append(make_segment("system", part, block_index=index))
+        for message_index, content in enumerate(payload.get("contents") or []):
+            if not isinstance(content, dict):
+                continue
+            role = str(content.get("role") or "")
+            for block_index, part in enumerate(content.get("parts") or []):
+                if isinstance(part, dict):
+                    result.append(
+                        make_segment(
+                            "message",
+                            {"role": role, **part},
+                            msg_index=message_index,
+                            block_index=block_index,
+                        )
+                    )
+        return result
+
+    def system_text(self, payload: dict[str, Any]) -> str:
+        return text_of(_parts(payload.get("systemInstruction")))
+
+    def first_user_text(self, payload: dict[str, Any]) -> str:
+        for content in payload.get("contents") or []:
+            if isinstance(content, dict) and content.get("role") == "user":
+                return text_of(_parts(content))
+        return ""
+
+    def tool_names(self, payload: dict[str, Any]) -> list[str]:
+        names: list[str] = []
+        for tool in payload.get("tools") or []:
+            if not isinstance(tool, dict):
+                continue
+            names.extend(
+                declaration["name"]
+                for declaration in tool.get("functionDeclarations") or []
+                if isinstance(declaration, dict) and isinstance(declaration.get("name"), str)
+            )
+        return names
+
+    def used_tool_names(self, payload: dict[str, Any]) -> list[str]:
+        names: list[str] = []
+        for content in payload.get("contents") or []:
+            if not isinstance(content, dict):
+                continue
+            for part in content.get("parts") or []:
+                if not isinstance(part, dict):
+                    continue
+                call = part.get("functionCall")
+                if isinstance(call, dict) and isinstance(call.get("name"), str):
+                    names.append(call["name"])
+        return names
+
+
+def _parts(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, dict):
+        parts = value.get("parts")
+        if isinstance(parts, list):
+            return [part for part in parts if isinstance(part, dict)]
+    return []
+
+
+def _response_handle(
+    response: dict[str, Any],
+) -> tuple[dict[str, Any], str, bool] | None:
+    inner = response.get("response")
+    if isinstance(inner, str):
+        return response, "response", False
+    if not isinstance(inner, dict):
+        return None
+    is_error = "error" in inner
+    for key in ("content", "result", "output", "text"):
+        if isinstance(inner.get(key), str):
+            return inner, key, is_error
+    return None
+
+
+__all__ = ["GeminiAdapter"]

ctxoptimizer/providers/ollama.py

@@ -0,0 +1,133 @@
+"""Native Ollama ``/api/chat`` and ``/api/generate`` adapter (P6-2)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from ctxoptimizer.analysis.segments import Segment, make_segment
+from ctxoptimizer.models import Provider, ToolResultRef
+from ctxoptimizer.providers.base import DictToolResultRef, text_of
+
+
+class OllamaAdapter:
+    provider = Provider.OLLAMA
+
+    def model_of(self, payload: dict[str, Any]) -> str | None:
+        model = payload.get("model")
+        return model if isinstance(model, str) else None
+
+    def is_stream(self, payload: dict[str, Any]) -> bool:
+        # Ollama streams by default when ``stream`` is omitted.
+        return bool(payload.get("stream", True))
+
+    def is_transformable(self, payload: dict[str, Any]) -> bool:
+        return isinstance(payload.get("messages"), list) or isinstance(payload.get("prompt"), str)
+
+    def iter_tool_results(self, payload: dict[str, Any]) -> Iterator[ToolResultRef]:
+        for message_index, message in enumerate(payload.get("messages") or []):
+            if not isinstance(message, dict) or message.get("role") != "tool":
+                continue
+            yield DictToolResultRef(
+                message,
+                message_index=message_index,
+                block_index=None,
+                tool_use_id=str(message.get("tool_name") or ""),
+                tool_name=(
+                    message.get("tool_name") if isinstance(message.get("tool_name"), str) else None
+                ),
+                is_error=False,
+                key="content",
+            )
+
+    def segments(self, payload: dict[str, Any]) -> list[Segment]:
+        result: list[Segment] = []
+        for tool in payload.get("tools") or []:
+            if not isinstance(tool, dict):
+                continue
+            function = tool.get("function")
+            if isinstance(function, dict):
+                result.append(make_segment("tool_def", function))
+        system = payload.get("system")
+        if isinstance(system, str) and system:
+            result.append(make_segment("system", {"type": "text", "text": system}))
+        messages = payload.get("messages")
+        if isinstance(messages, list):
+            for message_index, message in enumerate(messages):
+                if not isinstance(message, dict):
+                    continue
+                role = str(message.get("role") or "")
+                content = message.get("content")
+                if isinstance(content, str):
+                    result.append(
+                        make_segment(
+                            "message",
+                            {"role": role, "content": content},
+                            msg_index=message_index,
+                            block_index=0,
+                        )
+                    )
+                elif content is None and isinstance(message.get("tool_calls"), list):
+                    result.append(
+                        make_segment(
+                            "message",
+                            {"role": role, "tool_calls": message["tool_calls"]},
+                            msg_index=message_index,
+                        )
+                    )
+        elif isinstance(payload.get("prompt"), str):
+            result.append(
+                make_segment(
+                    "message",
+                    {"role": "user", "content": payload["prompt"]},
+                    msg_index=0,
+                    block_index=0,
+                )
+            )
+        return result
+
+    def system_text(self, payload: dict[str, Any]) -> str:
+        system = payload.get("system")
+        if isinstance(system, str):
+            return system
+        parts = [
+            text_of(message.get("content"))
+            for message in payload.get("messages") or []
+            if isinstance(message, dict) and message.get("role") == "system"
+        ]
+        return "\n".join(part for part in parts if part)
+
+    def first_user_text(self, payload: dict[str, Any]) -> str:
+        prompt = payload.get("prompt")
+        if isinstance(prompt, str):
+            return prompt
+        for message in payload.get("messages") or []:
+            if isinstance(message, dict) and message.get("role") == "user":
+                return text_of(message.get("content"))
+        return ""
+
+    def tool_names(self, payload: dict[str, Any]) -> list[str]:
+        names: list[str] = []
+        for tool in payload.get("tools") or []:
+            if not isinstance(tool, dict):
+                continue
+            function = tool.get("function")
+            if isinstance(function, dict) and isinstance(function.get("name"), str):
+                names.append(function["name"])
+        return names
+
+    def used_tool_names(self, payload: dict[str, Any]) -> list[str]:
+        names: list[str] = []
+        for message in payload.get("messages") or []:
+            if not isinstance(message, dict):
+                continue
+            for call in message.get("tool_calls") or []:
+                if not isinstance(call, dict):
+                    continue
+                function = call.get("function")
+                if isinstance(function, dict) and isinstance(function.get("name"), str):
+                    names.append(function["name"])
+        return names
+
+
+__all__ = ["OllamaAdapter"]