calfkit 0.2.4__tar.gz → 0.2.5__tar.gz

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

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

{calfkit-0.2.4 → calfkit-0.2.5}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.5](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.4...v0.2.5) (2026-04-11)
+
+
+### Features
+
+* add serializable node schemas and runtime tool overrides ([#121](https://github.com/calf-ai/calfkit-sdk/issues/121)) ([e464c08](https://github.com/calf-ai/calfkit-sdk/commit/e464c08e4f179e0cd622789a067718fdbd043c1f))
+
 ## [0.2.4](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.3...v0.2.4) (2026-04-08)
 
 

{calfkit-0.2.4 → calfkit-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.2.4
+Version: 0.2.5
 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

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/client/base.py

@@ -20,6 +20,7 @@ from calfkit.models.session_context import (
     SessionRunContext,
     WorkflowState,
 )
+from calfkit.models.state import OverridesState
 
 logger = logging.getLogger(__name__)
 
@@ -111,6 +112,7 @@ class BaseClient:
         reply_topic: str,
         correlation_id: str,
         state: State,
+        overrides: OverridesState | None = None,
         run_args: Sequence[Any] | None = None,
         deps: dict[str, Any] | None = None,
         output_type: type[Any] = _UNSET,
@@ -136,7 +138,7 @@ class BaseClient:
             await self._connection.start()
 
         call_stack = CallFrameStack()
-        call_stack.push(CallFrame(target_topic=topic, callback_topic=reply_topic, input_args=run_args))
+        call_stack.push(CallFrame(target_topic=topic, callback_topic=reply_topic, input_args=run_args, overrides=overrides))
 
         envelope = Envelope(
             internal_workflow_state=WorkflowState(call_stack=call_stack),

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/client/client.py

@@ -12,6 +12,8 @@ from calfkit.client.deserialize import _UNSET
 from calfkit.client.invocation_handle import InvocationHandle
 from calfkit.client.node_result import NodeResult
 from calfkit.models import State
+from calfkit.models.node_schema import BaseToolNodeSchema
+from calfkit.models.state import OverridesState
 
 
 class Client(BaseClient):
@@ -30,6 +32,7 @@ class Client(BaseClient):
         topic: str,
         *,
         output_type: type[OutputT],
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -44,6 +47,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -57,6 +61,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = None,
         output_type: type[Any] = _UNSET,
         reply_topic: str | None = None,
         correlation_id: str | None = None,
@@ -74,6 +79,7 @@ class Client(BaseClient):
         Args:
             user_prompt: The user message to send to the agent node.
             topic: The Kafka topic the target node subscribes to.
+            tool_overrides: Runtime agent tool overrides.
             output_type: The expected Python type for deserializing the agent's
                 output. When omitted, auto-detection is used (``DataPart`` →
                 ``TextPart`` fallback).
@@ -82,7 +88,7 @@ class Client(BaseClient):
             correlation_id: Unique identifier to correlate this request with its
                 reply. Auto-generated (uuid7) when ``None``.
             temp_instructions: Optional system-level instructions injected into
-                the user prompt as a one-shot override.
+                the user prompt as a temporary prompt addition.
             message_history: Prior conversation messages to include for
                 multi-turn context. Defaults to an empty history.
             run_args: Positional arguments forwarded to the node's ``run()``
@@ -107,6 +113,7 @@ class Client(BaseClient):
             correlation_id=correlation_id,
             run_args=run_args,
             state=state,
+            overrides=OverridesState(override_agent_tools=tool_overrides) if tool_overrides is not None else None,
             deps=deps,
             output_type=output_type,
         )
@@ -118,6 +125,7 @@ class Client(BaseClient):
         topic: str,
         *,
         output_type: type[OutputT],
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -133,6 +141,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -147,6 +156,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = None,
         output_type: type[Any] = _UNSET,
         reply_topic: str | None = None,
         correlation_id: str | None = None,
@@ -168,6 +178,7 @@ class Client(BaseClient):
         Args:
             user_prompt: The user message to send to the agent node.
             topic: The Kafka topic the target node subscribes to.
+            tool_overrides: Runtime agent tool overrides.
             output_type: The expected Python type for deserializing the agent's
                 output. When omitted, auto-detection is used.
             reply_topic: Topic the node should publish its reply to.
@@ -175,7 +186,7 @@ class Client(BaseClient):
             correlation_id: Unique identifier to correlate this request with its
                 reply. Auto-generated (uuid7) when ``None``.
             temp_instructions: Optional system-level instructions injected into
-                the user prompt as a one-shot override.
+                the user prompt as a temporary prompt addition.
             message_history: Prior conversation messages to include for
                 multi-turn context. Defaults to an empty history.
             run_args: Positional arguments forwarded to the node's ``run()``
@@ -195,6 +206,7 @@ class Client(BaseClient):
         handle = await self.invoke_node(
             user_prompt,
             topic,
+            tool_overrides=tool_overrides,
             output_type=output_type,
             reply_topic=reply_topic,
             correlation_id=correlation_id,

calfkit-0.2.5/calfkit/models/node_schema.py

@@ -0,0 +1,21 @@
+from dataclasses import KW_ONLY, dataclass
+
+from calfkit._vendor.pydantic_ai.tools import ToolDefinition
+
+
+@dataclass
+class BaseNodeSchema:
+    _: KW_ONLY
+    node_id: str
+    subscribe_topics: list[str]
+    publish_topic: str | None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.subscribe_topics, (list, tuple)):
+            self.subscribe_topics = [self.subscribe_topics]
+
+
+@dataclass
+class BaseToolNodeSchema(BaseNodeSchema):
+    _: KW_ONLY
+    tool_schema: ToolDefinition

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/models/session_context.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from calfkit._types import DepsT, StackItemT, StateT
 from calfkit.models.actions import _Call
-from calfkit.models.state import State
+from calfkit.models.state import OverridesState, State
 
 
 @dataclass
@@ -36,6 +36,7 @@ class CallFrame:
     callback_topic: str  # return address
     input_args: Sequence[Any] | None = field(default=None)
     frame_id: str = field(default_factory=lambda: uuid_utils.uuid7().hex)
+    overrides: OverridesState | None = field(default=None)
 
 
 CallFrameStack = Stack[CallFrame]

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/models/state.py

@@ -11,6 +11,7 @@ from calfkit._vendor.pydantic_ai.messages import (
     ToolCallPart,
 )
 from calfkit._vendor.pydantic_ai.tools import DeferredToolCallResult as ToolCallResult
+from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.payload import ContentPart
 
 
@@ -18,6 +19,13 @@ class BaseAgentActivityState(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
 
+class OverridesState(BaseAgentActivityState):
+    """State for storing any override objects"""
+
+    model_config = ConfigDict(extra="ignore")
+    override_agent_tools: list[BaseToolNodeSchema] | None
+
+
 class CoreMessageState(BaseAgentActivityState):
     """The state for committed messages and structured objects"""
 
@@ -90,6 +98,7 @@ class State(CoreMessageState, InFlightToolsState):
         default=None,
         description="Additional data that can be accessed programmatically by the application but is not sent to the LLM.",  # noqa: E501
     )
+    overrides: OverridesState | None = None
 
 
 # class State(BaseModel):

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/nodes/agent.py

@@ -11,6 +11,7 @@ from calfkit._vendor.pydantic_ai.tools import DeferredToolResults
 from calfkit._vendor.pydantic_ai.toolsets.external import ExternalToolset
 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.nodes.base import BaseNodeDef
@@ -44,6 +45,9 @@ class BaseAgentNodeDef(
         self.sequential_only_mode = sequential_only_mode
         self._pending_batches: dict[str, PendingToolBatch] = dict()
 
+        if not isinstance(subscribe_topics, (list, tuple)):
+            subscribe_topics = [subscribe_topics]
+
         super().__init__(node_id=node_id, subscribe_topics=subscribe_topics, publish_topic=publish_topic)
 
         self._agent_loop: InternalAgentLoop[dict[str, Any], AgentOutputT | DeferredToolRequests] = InternalAgentLoop(
@@ -64,7 +68,11 @@ class BaseAgentNodeDef(
                 del self._pending_batches[ctx.deps.correlation_id]
 
     async def run(self, ctx: SessionRunContext) -> NodeResult[State]:
-        tools_registry = {tool.tool_schema.name: tool for tool in self.tools} if self.tools else dict[str, ToolNodeDef]()
+        tools_registry = dict[str, BaseToolNodeSchema]()
+        if ctx.state.overrides is not None and ctx.state.overrides.override_agent_tools is not None:
+            tools_registry = {tool.tool_schema.name: tool for tool in ctx.state.overrides.override_agent_tools}
+        elif self.tools:
+            tools_registry = {tool.tool_schema.name: tool for tool in self.tools}
 
         logger.debug(
             "[%s] agent run entered node=%s pending_tool_calls=%d history_len=%d",

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/nodes/base.py

@@ -17,6 +17,7 @@ from calfkit.models import (
     TailCall,
 )
 from calfkit.models.envelope import Envelope
+from calfkit.models.node_schema import BaseNodeSchema
 from calfkit.models.session_context import SessionRunContext
 
 logger = logging.getLogger(__name__)
@@ -27,7 +28,7 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 
 
-class BaseNodeDef:
+class BaseNodeDef(BaseNodeSchema):
     _run_accepts_input: bool
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
@@ -37,21 +38,6 @@ class BaseNodeDef:
         # If > 2, the subclass declared an input parameter (any name).
         cls._run_accepts_input = len(sig.parameters) > 2
 
-    def __init__(
-        self,
-        node_id: str,
-        *,
-        subscribe_topics: str | list[str],
-        publish_topic: str | None,
-    ):
-        self._node_id = node_id
-        if isinstance(subscribe_topics, str):
-            self.subscribe_topics = [subscribe_topics]
-        elif subscribe_topics is not None:
-            self.subscribe_topics = list(subscribe_topics)
-        self.publish_topic = publish_topic
-        self._return_topic = f"{node_id}.private.return"
-
     # TODO: consider multiple abstract methods per node based on the incoming communication pattern,
     # like a delgation or emit. So the communication-specific handler can properly handle it
     @abstractmethod
@@ -77,6 +63,8 @@ class BaseNodeDef:
 
     async def prepare_context(self, envelope: Envelope) -> SessionRunContext:
         ctx = envelope.context.model_copy(deep=True)
+        if envelope.internal_workflow_state.current_frame.overrides:
+            ctx.state.overrides = envelope.internal_workflow_state.current_frame.overrides
         return ctx
 
     async def _publish_action(self, output: NodeResult[State], envelope: Envelope, correlation_id: str, broker: BrokerAnnotation) -> Envelope:
@@ -107,7 +95,7 @@ class BaseNodeDef:
                 internal_workflow_state=envelope.internal_workflow_state,
             )
             target_topic = envelope.internal_workflow_state.current_frame.target_topic
-            logger.debug("[%s] Call target=%s frame_pushed node=%s", correlation_id[:8], target_topic, self._node_id)
+            logger.debug("[%s] Call target=%s frame_pushed node=%s", correlation_id[:8], target_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=target_topic,
@@ -121,7 +109,7 @@ class BaseNodeDef:
                 context=SessionRunContext(state=output.state, deps=envelope.context.deps),
                 internal_workflow_state=envelope.internal_workflow_state,
             )
-            logger.debug("[%s] ReturnCall callback=%s node=%s", correlation_id[:8], frame.callback_topic, self._node_id)
+            logger.debug("[%s] ReturnCall callback=%s node=%s", correlation_id[:8], frame.callback_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=frame.callback_topic,
@@ -138,7 +126,7 @@ class BaseNodeDef:
                 internal_workflow_state=envelope.internal_workflow_state,
             )
             target_topic = envelope.internal_workflow_state.current_frame.target_topic
-            logger.debug("[%s] TailCall target=%s node=%s", correlation_id[:8], target_topic, self._node_id)
+            logger.debug("[%s] TailCall target=%s node=%s", correlation_id[:8], target_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=target_topic,
@@ -164,21 +152,25 @@ class BaseNodeDef:
         correlation_id: Annotated[str, Context()],
         broker: BrokerAnnotation,
     ) -> Envelope:
-        logger.debug("[%s] handler entered node=%s", correlation_id[:8], self._node_id)
+        logger.debug("[%s] handler entered node=%s", correlation_id[:8], self.node_id)
         ctx = await self.prepare_context(envelope)
         if self._run_accepts_input and envelope.internal_workflow_state.current_frame.input_args is not None:
             output = await self.run(ctx, *envelope.internal_workflow_state.current_frame.input_args)
         else:
             output = await self.run(ctx)
 
-        logger.debug("[%s] run() returned action=%s node=%s", correlation_id[:8], type(output).__name__, self._node_id)
+        logger.debug("[%s] run() returned action=%s node=%s", correlation_id[:8], type(output).__name__, self.node_id)
 
         return await self._publish_action(output, envelope, correlation_id, broker)
 
     @property
     def id(self) -> str:
-        return self._node_id
+        return self.node_id
 
     @property
     def name(self) -> str:
-        return self._node_id
+        return self.node_id
+
+    @property
+    def _return_topic(self) -> str:
+        return f"{self.node_id}.private.return"

{calfkit-0.2.4 → calfkit-0.2.5}/calfkit/nodes/tool.py

@@ -1,30 +1,37 @@
 import logging
-from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
-from typing import Any, cast
+from dataclasses import dataclass
+from typing import Any
 
-from calfkit._vendor.pydantic_ai import Tool, ToolDefinition
+from typing_extensions import Self
+
+from calfkit._vendor.pydantic_ai import Tool
 from calfkit._vendor.pydantic_ai.messages import ToolReturn
 from calfkit.models import SessionRunContext, Silent, State, ToolContext
 from calfkit.models.actions import NodeResult, ReturnCall
+from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.nodes.base import BaseNodeDef
 
 logger = logging.getLogger(__name__)
 
 
-class BaseToolNodeDef(BaseNodeDef, ABC):
-    @property
-    @abstractmethod
-    def tool_schema(self) -> ToolDefinition: ...
+@dataclass
+class BaseToolNodeDef(BaseToolNodeSchema, BaseNodeDef):
+    _tool: Tool
 
 
 class ToolNodeDef(BaseToolNodeDef):
-    def __init__(self, func: Callable[..., Any], subscribe_topics: str | list[str], publish_topic: str):
-        self._tool = Tool(func)
-        super().__init__(
+    @classmethod
+    def create_tool_node(cls, func: Callable[..., Any], subscribe_topics: str | list[str], publish_topic: str) -> Self:
+        if not isinstance(subscribe_topics, (list, tuple)):
+            subscribe_topics = [subscribe_topics]
+        tool = Tool(func)
+        return cls(
             node_id=f"tool_{func.__name__}",
+            tool_schema=tool.tool_def,
             subscribe_topics=subscribe_topics,
             publish_topic=publish_topic,
+            _tool=tool,
         )
 
     async def run(self, ctx: SessionRunContext, tool_call_id: str, source_node_name: str) -> NodeResult[State]:
@@ -78,15 +85,11 @@ class ToolNodeDef(BaseToolNodeDef):
         logger.debug("[%s] tool completed tool=%s", ctx.deps.correlation_id[:8], self.name)
         return ReturnCall[State](state=ctx.state)
 
-    @property
-    def tool_schema(self) -> ToolDefinition:
-        return cast(ToolDefinition, self._tool.tool_def)
-
 
 def agent_tool(func: Callable[..., Any] | Callable[..., Awaitable[Any]]) -> ToolNodeDef:
     """Decorator to turn a function into a deployable tool node that agents can call"""
     subscribe_topic = f"tool.{func.__name__}.input"
     publish_topic = f"tool.{func.__name__}.output"
-    tool_node = ToolNodeDef(func=func, subscribe_topics=subscribe_topic, publish_topic=publish_topic)
+    tool_node = ToolNodeDef.create_tool_node(func=func, subscribe_topics=subscribe_topic, publish_topic=publish_topic)
 
     return tool_node

{calfkit-0.2.4 → calfkit-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "calfkit"
-version = "0.2.4"
+version = "0.2.5"
 description = "Build AI workflows and agents as fully-distributed and event-driven microservices."
 readme = "README.md"
 license = "Apache-2.0"