calfkit 0.3.2__tar.gz → 0.3.4__tar.gz

calfkit-0.3.4/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.4"
+}

{calfkit-0.3.2 → calfkit-0.3.4}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.4](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.3...v0.3.4) (2026-05-23)
+
+
+### Documentation
+
+* add Ask DeepWiki badge to README ([#152](https://github.com/calf-ai/calfkit-sdk/issues/152)) ([2fb90f7](https://github.com/calf-ai/calfkit-sdk/commit/2fb90f70ddf9e5363759936c385af04c58651e33))
+
+## [0.3.3](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.2...v0.3.3) (2026-05-22)
+
+
+### Bug Fixes
+
+* (agent,tool) surface tool exceptions to the agent instead of hanging ([#146](https://github.com/calf-ai/calfkit-sdk/issues/146)) ([05162cc](https://github.com/calf-ai/calfkit-sdk/commit/05162cc2512285e7dfcb64a30c7c8bca2f9fe50d))
+
 ## [0.3.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.1...v0.3.2) (2026-05-21)
 
 

{calfkit-0.3.2 → calfkit-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.3.2
+Version: 0.3.4
 Summary: Build AI workflows and agents as fully-distributed and event-driven microservices.
 Project-URL: Homepage, https://github.com/calf-ai/calf-sdk
 Project-URL: Repository, https://github.com/calf-ai/calf-sdk
@@ -38,6 +38,7 @@ Description-Content-Type: text/markdown
 
 # 🐮 Calfkit SDK
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/calf-ai/calfkit-sdk)
 [![PyPI version](https://img.shields.io/pypi/v/calfkit)](https://pypi.org/project/calfkit/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/calfkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/calfkit)
 [![Python versions](https://img.shields.io/pypi/pyversions/calfkit)](https://pypi.org/project/calfkit/)

{calfkit-0.3.2 → calfkit-0.3.4}/README.md

@@ -1,5 +1,6 @@
 # 🐮 Calfkit SDK
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/calf-ai/calfkit-sdk)
 [![PyPI version](https://img.shields.io/pypi/v/calfkit)](https://pypi.org/project/calfkit/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/calfkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/calfkit)
 [![Python versions](https://img.shields.io/pypi/pyversions/calfkit)](https://pypi.org/project/calfkit/)

calfkit-0.3.4/calfkit/exceptions.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+
+class DeserializationError(Exception):
+    """Raised when client-side output deserialization fails."""
+
+
+class ToolExecutionError(Exception):
+    """The original traceback is not preserved across the Kafka boundary; it is
+    logged at the worker that ran the tool. ``exc_type`` and ``exc_message`` are
+    the only forensic data available at the agent.
+    """
+
+    def __init__(self, *, tool_name: str, tool_call_id: str, exc_type: str, exc_message: str):
+        self.tool_name = tool_name
+        self.tool_call_id = tool_call_id
+        self.exc_type = exc_type
+        self.exc_message = exc_message
+        super().__init__(f"Tool {tool_name!r} (call_id={tool_call_id}) raised {exc_type}: {exc_message}")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Bypass keyword-only ``__init__`` during reconstruction by routing
+        # through a module-level helper that uses ``__new__``. A naive
+        # ``(self.__class__, (), state)`` reduction would call ``__init__()``
+        # with no args and fail because the keyword arguments are required.
+        return (
+            _reconstruct_tool_execution_error,
+            (),
+            {
+                "tool_name": self.tool_name,
+                "tool_call_id": self.tool_call_id,
+                "exc_type": self.exc_type,
+                "exc_message": self.exc_message,
+            },
+        )
+
+    def __setstate__(self, state: dict[str, Any] | None) -> None:
+        # ``__reduce__`` above always provides a dict, but the supertype
+        # signature allows ``None`` (Liskov); treat ``None`` as a no-op so
+        # subclasses constructed without state don't crash.
+        if state is None:
+            return
+        self.tool_name = state["tool_name"]
+        self.tool_call_id = state["tool_call_id"]
+        self.exc_type = state["exc_type"]
+        self.exc_message = state["exc_message"]
+        Exception.__init__(
+            self,
+            f"Tool {self.tool_name!r} (call_id={self.tool_call_id}) raised {self.exc_type}: {self.exc_message}",
+        )
+
+
+def _reconstruct_tool_execution_error() -> "ToolExecutionError":
+    """Create a bare ``ToolExecutionError`` for reconstruction via ``__setstate__``.
+
+    Bypasses the keyword-only ``__init__`` so state restoration can populate
+    fields directly. Must be module-level (not a lambda or local closure) so
+    it can be located by fully-qualified name during deserialization.
+    """
+    return ToolExecutionError.__new__(ToolExecutionError)

{calfkit-0.3.2 → calfkit-0.3.4}/calfkit/models/state.py

@@ -1,16 +1,18 @@
 import logging
 from dataclasses import dataclass, field
-from typing import Annotated, Any, Generic
+from typing import Annotated, Any, ClassVar, Generic, Literal
 
-from pydantic import BaseModel, ConfigDict, Discriminator, Field
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag, field_validator
 from typing_extensions import TypeVar
 
+from calfkit._vendor.pydantic_ai.exceptions import ModelRetry
 from calfkit._vendor.pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
+    RetryPromptPart,
     ToolCallPart,
+    ToolReturn,
 )
-from calfkit._vendor.pydantic_ai.tools import DeferredToolCallResult as ToolCallResult
 from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.payload import ContentPart
 
@@ -58,28 +60,102 @@ class CoreMessageState(BaseAgentActivityState):
         self.uncommitted_message = None
 
 
+class FailedToolCall(BaseModel):
+    """Wire-format representation of a tool that raised on the worker side.
+
+    Stored in ``State.tool_results`` in the same slot a successful ``ToolReturn``
+    would occupy; consumers must handle both shapes. The ``marker_kind`` literal
+    is the discriminator tag consulted by ``_calf_tool_result_discriminator`` so
+    this value reconstructs as a typed instance (rather than a plain ``dict``)
+    when ``State`` round-trips through JSON across the Kafka boundary.
+
+    String fields are clamped to bounded lengths (see ``_MAX_LENGTHS``) rather
+    than rejected for wire-size safety: a tool that raises with an enormous
+    ``str(exc)`` must not itself cause construction to raise inside the worker's
+    ``except Exception`` block (which would prevent the failure reply from ever
+    being published and hang the agent).
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    tool_name: str
+    tool_call_id: str = Field(min_length=1)
+    exc_type: str
+    exc_message: str
+    marker_kind: Literal["calfkit-tool-error"] = "calfkit-tool-error"
+
+    _MAX_LENGTHS: ClassVar[dict[str, int]] = {
+        "tool_name": 256,
+        "tool_call_id": 128,
+        "exc_type": 256,
+        "exc_message": 4096,
+    }
+
+    @field_validator("tool_name", "tool_call_id", "exc_type", "exc_message", mode="before")
+    @classmethod
+    def _clamp_string_fields(cls, v: Any, info: Any) -> Any:
+        if isinstance(v, str):
+            limit = cls._MAX_LENGTHS.get(info.field_name)
+            if limit is not None and len(v) > limit:
+                return v[:limit]
+        return v
+
+
+def _calf_tool_result_discriminator(x: Any) -> str | None:
+    """Tag extractor for the ``CalfToolResult`` discriminated union.
+
+    Mirrors ``calfkit._vendor.pydantic_ai.tools._deferred_tool_call_result_discriminator``
+    with an added ``marker_kind`` branch for ``FailedToolCall``. Without this, a
+    serialized marker arrives as a plain ``dict`` after a Kafka hop because the
+    upstream discriminator only recognizes ``kind`` / ``part_kind``.
+
+    Returns only string tags; non-string values are treated as missing so the
+    union falls through to the ``Any`` arm rather than silently misrouting.
+    Keep this in sync with the upstream helper if a new pydantic-ai tag is added.
+    """
+    for key in ("marker_kind", "kind", "part_kind"):
+        v = x.get(key) if isinstance(x, dict) else getattr(x, key, None)
+        if isinstance(v, str):
+            return v
+    return None
+
+
+CalfToolResult = Annotated[
+    Annotated[ToolReturn, Tag("tool-return")]
+    | Annotated[ModelRetry, Tag("model-retry")]
+    | Annotated[RetryPromptPart, Tag("retry-prompt")]
+    | Annotated[FailedToolCall, Tag("calfkit-tool-error")],
+    Discriminator(_calf_tool_result_discriminator),
+]
+"""Calfkit-side tagged union for values stored in ``State.tool_results``.
+
+Flattens pydantic-ai's ``DeferredToolCallResult`` (``ToolReturn`` / ``ModelRetry``
+/ ``RetryPromptPart``) and adds calfkit's ``FailedToolCall``. Flattening (rather
+than ``DeferredToolCallResult | FailedToolCall``) is required because Pydantic's
+discriminated-union machinery does not compose nested ``Discriminator``
+annotations reliably.
+"""
+
+
 class InFlightToolsState(BaseAgentActivityState):
     """State of all in-progress tool calls and results.
     Tool calls and results are in-progress when all tool calls have not been completed and committed to message history."""  # noqa: E501
 
     model_config = ConfigDict(extra="ignore")
 
-    # Map of tool call IDS to tool calls
     tool_calls: dict[str, ToolCallPart] = Field(default_factory=dict)
 
-    # Map of tool call IDs to tool results
-    tool_results: dict[str, ToolCallResult | Any] = Field(default_factory=dict)
+    tool_results: dict[str, CalfToolResult | Any] = Field(default_factory=dict)
 
     def add_tool_call(self, tool_call: ToolCallPart) -> None:
         self.tool_calls[tool_call.tool_call_id] = tool_call
 
-    def add_tool_result(self, tool_call_id: str, tool_result: ToolCallResult | Any) -> None:
+    def add_tool_result(self, tool_call_id: str, tool_result: CalfToolResult | Any) -> None:
         self.tool_results[tool_call_id] = tool_result
 
     def get_tool_call(self, tool_call_id: str) -> ToolCallPart | None:
         return self.tool_calls.get(tool_call_id)
 
-    def get_tool_result(self, tool_call_id: str) -> ToolCallResult | Any | None:
+    def get_tool_result(self, tool_call_id: str) -> CalfToolResult | Any | None:
         return self.tool_results.get(tool_call_id)
 
     def all_call_ids_complete(self, *call_ids: str) -> bool:
@@ -102,17 +178,6 @@ class State(CoreMessageState, InFlightToolsState):
     overrides: OverridesState | None = None
 
 
-# class State(BaseModel):
-#     """mutable data model to track state of an execution among one or more agents,
-#     sharing correlation id"""
-
-#     model_config = ConfigDict(extra="ignore")
-#     run_state: AgentActivityState = Field(default_factory=AgentActivityState)
-
-
-# ---------------------------------------------------------------------------
-# Experimental PartialState implementation
-# ---------------------------------------------------------------------------
 AgentStateSubsetT = TypeVar("AgentStateSubsetT", CoreMessageState, InFlightToolsState)
 
 PartialState = Annotated[CoreMessageState | InFlightToolsState | Any, Discriminator("kind")]
@@ -135,7 +200,7 @@ class PendingToolBatch:
     base_state: State
 
     # map of tool call IDs to tool call results
-    collected_results: dict[str, ToolCallResult | Any] = field(default_factory=dict)
+    collected_results: dict[str, CalfToolResult | Any] = field(default_factory=dict)
 
     @property
     def is_complete(self) -> bool:

{calfkit-0.3.2 → calfkit-0.3.4}/calfkit/nodes/agent.py

@@ -2,6 +2,8 @@ import logging
 from collections.abc import Callable
 from typing import Any, ClassVar, Generic, cast
 
+from pydantic import ValidationError
+
 from calfkit._protocol import NodeKind
 from calfkit._types import AgentOutputT
 from calfkit._vendor.pydantic_ai import Agent as InternalAgentLoop
@@ -11,19 +13,18 @@ from calfkit._vendor.pydantic_ai.output import OutputSpec
 from calfkit._vendor.pydantic_ai.settings import ModelSettings
 from calfkit._vendor.pydantic_ai.tools import DeferredToolResults
 from calfkit._vendor.pydantic_ai.toolsets.external import ExternalToolset
+from calfkit.exceptions import ToolExecutionError
 from calfkit.models import Call, DataPart, NodeResult, ReturnCall, State, TailCall, TextPart
 from calfkit.models.actions import Silent
 from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.session_context import SessionRunContext
-from calfkit.models.state import PendingToolBatch
+from calfkit.models.state import FailedToolCall, PendingToolBatch
 from calfkit.nodes.base import BaseNodeDef, GateFunction
-from calfkit.nodes.tool import ToolNodeDef
+from calfkit.nodes.tool import BaseToolNodeDef, ToolNodeDef, _safe_exc_message
 from calfkit.providers.pydantic_ai.model_client import PydanticModelClient
 
 logger = logging.getLogger(__name__)
 
-NoneType = type(None)
-
 
 class BaseAgentNodeDef(
     Generic[AgentOutputT],
@@ -85,11 +86,17 @@ class BaseAgentNodeDef(
         elif self.tools:
             tools_registry = {tool.tool_schema.name: tool for tool in self.tools}
 
+        # ``latest_tool_calls()`` walks ``message_history`` in reverse on each call;
+        # cache once for all pre-model uses. The post-model use after
+        # ``result.new_messages()`` is extended into history must re-call to see
+        # the model's new tool calls.
+        latest_tool_calls = ctx.state.latest_tool_calls()
+
         logger.debug(
             "[%s] agent run entered node=%s pending_tool_calls=%d history_len=%d",
             ctx.deps.correlation_id[:8],
             self.name,
-            len(ctx.state.latest_tool_calls()),
+            len(latest_tool_calls),
             len(ctx.state.message_history),
         )
 
@@ -99,7 +106,61 @@ class BaseAgentNodeDef(
             if batch and not batch.is_complete:
                 return Silent()
 
-        latest_tool_calls = ctx.state.latest_tool_calls()
+        # Collect all FailedToolCall results in this turn so operators see every
+        # failure in a parallel batch; raise on the first after logging all.
+        # Also defend against corrupt marker dicts: a payload with the calfkit
+        # marker tag that fails ``FailedToolCall`` validation (e.g. schema drift
+        # during rolling deploy, a required field added without default, a
+        # tampered wire payload) round-trips through the union's ``| Any`` arm
+        # as a plain ``dict``. Synthesize a typed marker so the silent-failure
+        # path closes — operators still see the raise and the corrupt-keys
+        # context.
+        failed_tool_calls: list[FailedToolCall] = []
+        for tc in latest_tool_calls:
+            result = ctx.state.tool_results.get(tc.tool_call_id)
+            if isinstance(result, FailedToolCall):
+                failed_tool_calls.append(result)
+            elif isinstance(result, dict) and result.get("marker_kind") == "calfkit-tool-error":
+                logger.error(
+                    "[%s] corrupt FailedToolCall marker detected node=%s tool_call_id=%s raw_keys=%s; "
+                    "likely schema drift or version skew across the Kafka boundary",
+                    ctx.deps.correlation_id[:8],
+                    self.name,
+                    tc.tool_call_id,
+                    sorted(result.keys()),
+                )
+                # Synthesize a typed marker with sentinel fields known to pass
+                # FailedToolCall's validators. tc.tool_call_id is the LLM-emitted
+                # correlation key; fall back to "<missing>" if it's empty so
+                # ``min_length=1`` doesn't itself raise.
+                raw_tool_name = result.get("tool_name")
+                failed_tool_calls.append(
+                    FailedToolCall(
+                        tool_name=raw_tool_name if isinstance(raw_tool_name, str) and raw_tool_name else "<unknown>",
+                        tool_call_id=tc.tool_call_id or "<missing>",
+                        exc_type="CorruptFailedToolCallMarker",
+                        exc_message=f"Marker dict failed validation as FailedToolCall (likely schema drift); raw_keys={sorted(result.keys())}",
+                    )
+                )
+        if failed_tool_calls:
+            for failure in failed_tool_calls:
+                logger.error(
+                    "[%s] tool execution error detected node=%s tool=%s tool_call_id=%s exc_type=%s exc_message=%s",
+                    ctx.deps.correlation_id[:8],
+                    self.name,
+                    failure.tool_name,
+                    failure.tool_call_id,
+                    failure.exc_type,
+                    failure.exc_message,
+                )
+            first = failed_tool_calls[0]
+            raise ToolExecutionError(
+                tool_name=first.tool_name,
+                tool_call_id=first.tool_call_id,
+                exc_type=first.exc_type,
+                exc_message=first.exc_message,
+            )
+
         tool_results = None
 
         if len(latest_tool_calls) > 0:
@@ -141,14 +202,13 @@ class BaseAgentNodeDef(
             model_settings=run_model_settings,
         )
         if isinstance(result.output, DeferredToolRequests):
-            # The LLM called one or more tools
             logger.debug(
                 "[%s] model returned DeferredToolRequests tool_count=%d node=%s",
                 ctx.deps.correlation_id[:8],
                 len(result.output.calls),
                 self.name,
             )
-            messages = result.new_messages()  # preserve conversation history
+            messages = result.new_messages()
             ctx.state.message_history.extend(messages)
             latest_tool_calls = ctx.state.latest_tool_calls()
 
@@ -166,7 +226,9 @@ class BaseAgentNodeDef(
                             tool_call_id=tool_call.tool_call_id,
                         ),
                     )
-                elif tool_node.subscribe_topics is None:
+                    continue
+
+                if tool_node.subscribe_topics is None:
                     logger.error(
                         "tool=%s is unreachable. No subscribe topics were provided for the tool node.",
                         tool_call.tool_name,
@@ -179,8 +241,89 @@ class BaseAgentNodeDef(
                             tool_call_id=tool_call.tool_call_id,
                         ),
                     )
+                    continue
+
+                # Parse args from the LLM's emission. Applies to ALL dispatch
+                # paths so that malformed-JSON args from override (schema-only)
+                # tools are also surfaced as RetryPromptPart instead of escaping
+                # to the worker's hard FailedToolCall path.
+                #
+                # ``args_as_dict()`` can raise more than just ValueError /
+                # AssertionError: ``pydantic_core.from_json`` raises TypeError
+                # when ``args`` is a non-string/non-bytes value (e.g. an int or
+                # list emitted by an off-spec provider). Catch broadly so any
+                # parse failure surfaces as an LLM-retryable RetryPromptPart
+                # rather than escaping ``run()`` and hanging the caller.
+                try:
+                    args = tool_call.args_as_dict()
+                except Exception as e:
+                    content = f"Malformed tool arguments: {type(e).__name__}: {_safe_exc_message(e)}"
+                    logger.warning(
+                        "[%s] tool=%s args parse failed at dispatch: %s",
+                        ctx.deps.correlation_id[:8],
+                        tool_call.tool_name,
+                        content,
+                        exc_info=True,
+                    )
+                    ctx.state.add_tool_result(
+                        tool_call.tool_call_id,
+                        RetryPromptPart(
+                            content=content,
+                            tool_name=tool_call.tool_name,
+                            tool_call_id=tool_call.tool_call_id,
+                        ),
+                    )
+                    continue
+
+                # Validate against the schema if we have a runtime validator.
+                # Override-mode schemas (BaseToolNodeSchema-only) skip this step
+                # and dispatch unvalidated; this is the documented carve-out.
+                if isinstance(tool_node, BaseToolNodeDef):
+                    try:
+                        tool_node.validate_call_args(args)
+                    except ValidationError as e:
+                        validation_errors = e.errors(include_url=False, include_context=False)
+                        logger.warning(
+                            "[%s] tool=%s arg validation failed at dispatch: %s",
+                            ctx.deps.correlation_id[:8],
+                            tool_call.tool_name,
+                            validation_errors,
+                        )
+                        ctx.state.add_tool_result(
+                            tool_call.tool_call_id,
+                            RetryPromptPart(
+                                content=validation_errors,
+                                tool_name=tool_call.tool_name,
+                                tool_call_id=tool_call.tool_call_id,
+                            ),
+                        )
+                        continue
+                    except Exception as e:
+                        # A user-authored Pydantic ``field_validator`` raised
+                        # something other than ``ValidationError`` (e.g.
+                        # ``RuntimeError``, ``TypeError``, a custom exception).
+                        # Surface as ``RetryPromptPart`` so the LLM can retry
+                        # rather than letting the exception escape ``run()`` and
+                        # silently hang the caller.
+                        validator_content = f"Tool argument validator raised {type(e).__name__}: {_safe_exc_message(e)}"
+                        logger.warning(
+                            "[%s] tool=%s arg validator raised %s; surfacing as RetryPromptPart",
+                            ctx.deps.correlation_id[:8],
+                            tool_call.tool_name,
+                            type(e).__name__,
+                            exc_info=True,
+                        )
+                        ctx.state.add_tool_result(
+                            tool_call.tool_call_id,
+                            RetryPromptPart(
+                                content=validator_content,
+                                tool_name=tool_call.tool_name,
+                                tool_call_id=tool_call.tool_call_id,
+                            ),
+                        )
+                        continue
 
-            if ctx.state.all_call_ids_complete(*[tc.tool_call_id for tc in latest_tool_calls]):  # All tool calls were invalid, we need to retry.
+            if ctx.state.all_call_ids_complete(*[tc.tool_call_id for tc in latest_tool_calls]):
                 # TODO: maybe consider a node retry return type that doesn't require round trip to itself.
                 # Tailcall to itself is a roundtrip.
                 logger.debug("[%s] all tool calls invalid, TailCall retry node=%s", ctx.deps.correlation_id[:8], self.name)