easyharness 0.1.0__py3-none-any.whl

easyharness/__init__.py

@@ -0,0 +1,18 @@
+"""Minimal public SDK surface for EasyHarness.
+
+The package exposes only five public names: `Agent`, `ModelConfig`,
+`AgentEvent`, `ToolOutput`, and `tool`. Runtime bridging, tool contract
+validation, event mapping, and conversation compression stay inside private
+modules so ordinary callers never have to touch internal objects.
+"""
+
+from ._internal.runtime import Agent
+from ._internal.tools import tool
+from ._internal.types import AgentEvent, ModelConfig, ToolOutput
+
+__all__ = ["Agent", "ModelConfig", "AgentEvent", "ToolOutput", "tool"]
+
+__AUTHOR__ = '吴子豪 / Vortez Wohl'
+__EMAIL__ = 'vortez.wohl@gmail.com'
+__GITHUB__ = 'https://github.com/vortezwohl'
+__BLOG__ = 'https://vortezwohl.github.io'

easyharness/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Private implementation package for EasyHarness.
+
+It contains the runtime bridge, tool contracts, event mapping, and
+conversation compression internals. Callers should depend on the stable public
+entry points exposed from top-level `easyharness` instead of these modules.
+"""

easyharness/_internal/conversation.py

@@ -0,0 +1,173 @@
+"""Default conversation compression manager and event integration points.
+
+This module adds a thin wrapper around Strands
+`SummarizingConversationManager` so compression start, completion, and failure
+emit unified upper-layer events without changing the original
+reactive/proactive control-flow semantics.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from copy import deepcopy
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Callable, Protocol
+
+from strands.agent.conversation_manager import (
+    ConversationManager,
+    SummarizingConversationManager,
+)
+
+if TYPE_CHECKING:
+    from strands.agent.agent import Agent as StrandsAgent
+
+logger = logging.getLogger(__name__)
+
+InternalEventSink = Callable[[dict[str, object]], None]
+
+
+class SupportsEventSink(Protocol):
+    """Protocol for managers that optionally support event sink binding."""
+
+    def bind_event_sink(self, sink: InternalEventSink | None) -> None:
+        """Bind or clear an internal event sink."""
+
+
+def utc_now_iso() -> str:
+    """Return the current UTC time as an ISO 8601 string."""
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+class EventingSummarizingConversationManager(SummarizingConversationManager):
+    """Default summarizing conversation manager with compression events."""
+
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        """Initialize the default summarizing conversation manager."""
+
+        super().__init__(*args, **kwargs)
+        self._event_sink: InternalEventSink | None = None
+
+    def bind_event_sink(self, sink: InternalEventSink | None) -> None:
+        """Bind or clear the runtime event sink.
+
+        Args:
+            sink: Callback for internal compression events; `None` unbinds it.
+        """
+
+        self._event_sink = sink
+
+    def _emit(
+        self,
+        status: str,
+        *,
+        mode: str,
+        started_at: str,
+        duration_ms: int | None = None,
+        error: str | None = None,
+    ) -> None:
+        """Emit an internal compression event to the upper layer."""
+
+        if self._event_sink is None:
+            return
+
+        payload: dict[str, object] = {
+            "easyharness_compress": {
+                "status": status,
+                "started_at": started_at,
+                "duration_ms": duration_ms,
+                "mode": mode,
+            }
+        }
+        if error is not None:
+            payload["easyharness_compress"]["error"] = error
+        self._event_sink(payload)
+
+    def reduce_context(
+        self,
+        agent: StrandsAgent,
+        e: Exception | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Compress context and emit started/completed/failed events.
+
+        Args:
+            agent: Current Strands agent.
+            e: Triggering exception; `None` means proactive compression.
+            **kwargs: Reserved for compatibility with the underlying API.
+
+        Raises:
+            Exception: Propagated when reactive compression also fails.
+        """
+
+        del kwargs
+        mode = "reactive" if e is not None else "proactive"
+        started_at = utc_now_iso()
+        start = time.perf_counter()
+        self._emit("started", mode=mode, started_at=started_at)
+
+        try:
+            self._summarize_oldest(agent)
+        except Exception as summarization_error:
+            duration_ms = int((time.perf_counter() - start) * 1000)
+            self._emit(
+                "failed",
+                mode=mode,
+                started_at=started_at,
+                duration_ms=duration_ms,
+                error=str(summarization_error),
+            )
+            if e is not None:
+                logger.error("Summarization failed: %s", summarization_error)
+                raise summarization_error from e
+            logger.warning(
+                "Proactive summarization failed, continuing: %s",
+                summarization_error,
+            )
+        else:
+            duration_ms = int((time.perf_counter() - start) * 1000)
+            self._emit(
+                "completed",
+                mode=mode,
+                started_at=started_at,
+                duration_ms=duration_ms,
+            )
+
+
+def clone_conversation_manager(
+    conversation_manager: ConversationManager | None,
+) -> ConversationManager:
+    """Clone a conversation manager with the smallest practical cost.
+
+    Args:
+        conversation_manager: Caller-provided custom manager; falls back to the
+            default summarizing manager when omitted.
+
+    Returns:
+        A conversation manager instance ready for the current session.
+    """
+
+    if conversation_manager is None:
+        return EventingSummarizingConversationManager()
+
+    try:
+        return deepcopy(conversation_manager)
+    except Exception:
+        return conversation_manager
+
+
+def bind_event_sink_if_supported(
+    conversation_manager: ConversationManager,
+    sink: InternalEventSink | None,
+) -> None:
+    """Bind an internal event sink when the manager supports it.
+
+    Args:
+        conversation_manager: Manager used by the current session.
+        sink: Event sink to bind; `None` clears the binding.
+    """
+
+    binder = getattr(conversation_manager, "bind_event_sink", None)
+    if callable(binder):
+        binder(sink)

easyharness/_internal/model.py

@@ -0,0 +1,198 @@
+"""Bridge from public model config to the Strands model runtime.
+
+This module turns public `ModelConfig` values into a concrete
+`LiteLLMModel`. The SDK relies only on explicit inputs and does not read
+environment variables or introduce extra channel/profile indirection.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from strands.models.litellm import LiteLLMModel
+from strands.models._validation import _has_location_source
+from strands.types.content import ContentBlock, Messages, SystemContentBlock
+
+from easyharness._internal.types import ModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _model_mentions_deepseek(model_id: str) -> bool:
+    """Return whether the configured model name clearly targets DeepSeek."""
+
+    normalized = model_id.strip().lower()
+    if not normalized:
+        return False
+    if normalized.startswith("deepseek/"):
+        return True
+    if "/" in normalized:
+        _, normalized = normalized.split("/", 1)
+    return "deepseek" in normalized
+
+
+def _base_url_targets_deepseek(base_url: str) -> bool:
+    """Return whether the configured base URL points at DeepSeek."""
+
+    return "api.deepseek.com" in base_url.strip().lower()
+
+
+def _should_use_deepseek_compat(config: ModelConfig) -> bool:
+    """Return whether the runtime should enable the DeepSeek compatibility path."""
+
+    model_id = config.model.strip()
+    provider = model_id.split("/", 1)[0].lower() if "/" in model_id else None
+
+    if _model_mentions_deepseek(model_id):
+        return True
+
+    if provider not in (None, "openai"):
+        return False
+
+    return provider is None and _base_url_targets_deepseek(config.base_url)
+
+
+def _extract_reasoning_text(contents: list[ContentBlock]) -> str | None:
+    """Collapse reasoning text blocks into the string expected by DeepSeek."""
+
+    chunks: list[str] = []
+    for content in contents:
+        reasoning = content.get("reasoningContent")
+        if not reasoning:
+            continue
+
+        reasoning_text = reasoning.get("reasoningText")
+        if reasoning_text and reasoning_text.get("text"):
+            chunks.append(reasoning_text["text"])
+
+    text = "".join(chunks).strip()
+    return text or None
+
+
+class _DeepSeekLiteLLMModel(LiteLLMModel):
+    """Minimal LiteLLM variant that preserves DeepSeek tool-call reasoning."""
+
+    @classmethod
+    def _format_regular_messages(
+        cls, messages: Messages, **kwargs: Any
+    ) -> list[dict[str, Any]]:
+        """Format messages without dropping reasoning tied to tool calls."""
+
+        del kwargs
+        formatted_messages: list[dict[str, Any]] = []
+
+        for message in messages:
+            contents = message["content"]
+
+            filtered_contents = []
+            for content in contents:
+                if any(
+                    block_type in content
+                    for block_type in ["toolResult", "toolUse", "reasoningContent"]
+                ):
+                    continue
+                if _has_location_source(content):
+                    logger.warning(
+                        "Location sources are not supported by OpenAI | skipping content block"
+                    )
+                    continue
+                filtered_contents.append(content)
+
+            formatted_contents = [
+                cls.format_request_message_content(content)
+                for content in filtered_contents
+            ]
+            formatted_tool_calls = [
+                cls.format_request_message_tool_call(content["toolUse"])
+                for content in contents
+                if "toolUse" in content
+            ]
+            formatted_tool_messages = [
+                cls.format_request_tool_message(content["toolResult"])
+                for content in contents
+                if "toolResult" in content
+            ]
+
+            formatted_message: dict[str, Any] = {
+                "role": message["role"],
+                **({"content": formatted_contents} if formatted_contents else {}),
+                **({"tool_calls": formatted_tool_calls} if formatted_tool_calls else {}),
+            }
+
+            if message["role"] == "assistant" and formatted_tool_calls:
+                reasoning_text = _extract_reasoning_text(contents)
+                if reasoning_text is not None:
+                    formatted_message["reasoning_content"] = reasoning_text
+                    formatted_message.setdefault("content", "")
+
+            formatted_messages.append(formatted_message)
+
+            user_messages_with_images = []
+            for tool_msg in formatted_tool_messages:
+                tool_msg_clean, user_msg_with_images = cls._split_tool_message_images(
+                    tool_msg
+                )
+                formatted_messages.append(tool_msg_clean)
+                if user_msg_with_images:
+                    user_messages_with_images.append(user_msg_with_images)
+            formatted_messages.extend(user_messages_with_images)
+
+        return formatted_messages
+
+    @classmethod
+    def format_request_messages(
+        cls,
+        messages: Messages,
+        system_prompt: str | None = None,
+        *,
+        system_prompt_content: list[SystemContentBlock] | None = None,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """Format a DeepSeek-compatible messages array."""
+
+        formatted_messages = cls._format_system_messages(
+            system_prompt,
+            system_prompt_content=system_prompt_content,
+        )
+        formatted_messages.extend(cls._format_regular_messages(messages, **kwargs))
+        return [
+            message
+            for message in formatted_messages
+            if "content" in message or "tool_calls" in message
+        ]
+
+
+def build_runtime_model(config: ModelConfig) -> LiteLLMModel:
+    """Build the underlying LiteLLM model from public configuration.
+
+    Args:
+        config: Public SDK model configuration.
+
+    Returns:
+        A configured `LiteLLMModel` instance.
+    """
+
+    params: dict[str, object] = {
+        "temperature": config.temperature,
+        "top_p": config.top_p,
+    }
+    if config.seed is not None:
+        params["seed"] = config.seed
+
+    model_cls = (
+        _DeepSeekLiteLLMModel
+        if _should_use_deepseek_compat(config)
+        else LiteLLMModel
+    )
+
+    return model_cls(
+        client_args={
+            "api_key": config.api_key,
+            "base_url": config.base_url,
+            "custom_llm_provider": "openai",
+        },
+        model_id=config.model,
+        params=params,
+        stream=True,
+    )