calfkit 0.3.0__tar.gz → 0.3.2__tar.gz

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

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

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

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.3.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.1...v0.3.2) (2026-05-21)
+
+
+### Bug Fixes
+
+* route tool returns to private inbox to prevent co-tenant leak ([#142](https://github.com/calf-ai/calfkit-sdk/issues/142)) ([197463f](https://github.com/calf-ai/calfkit-sdk/commit/197463f2f7f338bae53bf144e3a86cf27373e350))
+
+
+### Documentation
+
+* integrate DX review into v1 design and add reviewer artifact ([#138](https://github.com/calf-ai/calfkit-sdk/issues/138)) ([29a7961](https://github.com/calf-ai/calfkit-sdk/commit/29a7961d5c2d4e46fcb7e2e4a81f43116c34feb3))
+
+## [0.3.1](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.0...v0.3.1) (2026-05-19)
+
+
+### Features
+
+* add ConsumerNodeDef and expose State on NodeResult ([#137](https://github.com/calf-ai/calfkit-sdk/issues/137)) ([aa139c7](https://github.com/calf-ai/calfkit-sdk/commit/aa139c74fe7e0d1baa0a016b5db423ebdc6e65ad))
+* add runtime model_settings to Agent and Client ([#134](https://github.com/calf-ai/calfkit-sdk/issues/134)) ([47d64b2](https://github.com/calf-ai/calfkit-sdk/commit/47d64b286b3ca151cc40022dfab22b4862d06b04))
+
+
+### Documentation
+
+* add ROADMAP.md index pointing to design docs ([#135](https://github.com/calf-ai/calfkit-sdk/issues/135)) ([5fa2a1a](https://github.com/calf-ai/calfkit-sdk/commit/5fa2a1af731341e3d9bef71be42e30841451058a))
+
 ## [0.3.0](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.6...v0.3.0) (2026-05-18)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -356,6 +356,57 @@ For tool-node gating, pass `gates=[...]` to `ToolNodeDef.create_tool_node(...)`
 
 <br>
 
+### Consumer Nodes (Optional)
+
+A **consumer node** is a terminal sink — it subscribes to one or more topics and runs arbitrary Python logic against every event flowing through. Consumers receive the same `NodeResult` that `Client.execute_node()` returns, including the full session state (`tool_calls`, `tool_results`, `message_history`, `metadata`).
+
+Deploy a consumer as its own service. Wire it to an agent's `publish_topic` (or any topic carrying calfkit envelopes) to observe outputs from agents, tools, and intermediate hops:
+
+```python
+# weather_sink.py
+import asyncio
+from calfkit.client import Client, NodeResult
+from calfkit.nodes import consumer
+from calfkit.worker import Worker
+
+@consumer(subscribe_topics="weather_agent.output")
+async def log_weather(result: NodeResult) -> None:
+    if result.output is None:
+        return  # intermediate hop — no final output yet
+    print(f"[{result.correlation_id[:8]}] {result.output}")
+
+async def main():
+    client = Client.connect("localhost:9092")
+    worker = Worker(client, nodes=[log_weather])  # Deploy the consumer node
+    await worker.run()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run alongside the agent service:
+
+```shell
+python weather_sink.py
+```
+
+An agent's `publish_topic` emits on **every** state transition — intermediate hops, tool completions, and terminals — so `result.output` is `None` on hops without final output parts. Filter via a gate if you only want agent terminals:
+
+```python
+@consumer(
+    subscribe_topics="weather_agent.output",
+    gates=[lambda ctx: bool(ctx.state.final_output_parts)],
+)
+async def save_final(result: NodeResult) -> None:
+    await db.save(result.output)  # always populated here
+```
+
+**Upstream requirement**: the upstream agent or tool must have a `publish_topic` set for consumers to tap (e.g. add `publish_topic="weather_agent.output"` to the agent in step 4).
+
+**Error policy**: exceptions from the consumer function are logged and swallowed by default so a single bad event can't poison-pill the Kafka offset. Pass `re_raise=True` to fail loud during development.
+
+<br>
+
 ## Documentation
 
 Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.

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

@@ -318,6 +318,57 @@ For tool-node gating, pass `gates=[...]` to `ToolNodeDef.create_tool_node(...)`
 
 <br>
 
+### Consumer Nodes (Optional)
+
+A **consumer node** is a terminal sink — it subscribes to one or more topics and runs arbitrary Python logic against every event flowing through. Consumers receive the same `NodeResult` that `Client.execute_node()` returns, including the full session state (`tool_calls`, `tool_results`, `message_history`, `metadata`).
+
+Deploy a consumer as its own service. Wire it to an agent's `publish_topic` (or any topic carrying calfkit envelopes) to observe outputs from agents, tools, and intermediate hops:
+
+```python
+# weather_sink.py
+import asyncio
+from calfkit.client import Client, NodeResult
+from calfkit.nodes import consumer
+from calfkit.worker import Worker
+
+@consumer(subscribe_topics="weather_agent.output")
+async def log_weather(result: NodeResult) -> None:
+    if result.output is None:
+        return  # intermediate hop — no final output yet
+    print(f"[{result.correlation_id[:8]}] {result.output}")
+
+async def main():
+    client = Client.connect("localhost:9092")
+    worker = Worker(client, nodes=[log_weather])  # Deploy the consumer node
+    await worker.run()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run alongside the agent service:
+
+```shell
+python weather_sink.py
+```
+
+An agent's `publish_topic` emits on **every** state transition — intermediate hops, tool completions, and terminals — so `result.output` is `None` on hops without final output parts. Filter via a gate if you only want agent terminals:
+
+```python
+@consumer(
+    subscribe_topics="weather_agent.output",
+    gates=[lambda ctx: bool(ctx.state.final_output_parts)],
+)
+async def save_final(result: NodeResult) -> None:
+    await db.save(result.output)  # always populated here
+```
+
+**Upstream requirement**: the upstream agent or tool must have a `publish_topic` set for consumers to tap (e.g. add `publish_topic="weather_agent.output"` to the agent in step 4).
+
+**Error policy**: exceptions from the consumer function are logged and swallowed by default so a single bad event can't poison-pill the Kafka offset. Pass `re_raise=True` to fail loud during development.
+
+<br>
+
 ## Documentation
 
 Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.

calfkit-0.3.2/ROADMAP.md

@@ -0,0 +1,9 @@
+# Roadmap
+
+An index of potential features and changes under consideration for Calf SDK. Each entry links to a detailed design document in `docs/`. Inclusion here does not imply commitment — items may be reshaped, deferred, or dropped after review.
+
+## Proposed
+
+- [Calfkit 1.0](docs/calfkit-v1-design.md) — 1.0 rewrite proposal covering node, agent, and result shape changes
+- [Hook System](docs/hooks-design.md) — two-layer middleware proposal for pre/post-run extensibility on nodes
+- [Durable Fan-Out Aggregator](docs/durable-fanout-aggregator.md) — replace in-process `_pending_batches` with a Kafka-backed compacted-state aggregator for parallel tool calls

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/__init__.py

@@ -2,7 +2,7 @@ from importlib.metadata import version
 
 from calfkit.client import Client, InvocationHandle, NodeResult
 from calfkit.models import ToolContext
-from calfkit.nodes import Agent, BaseNodeDef, GateFunction, NodeDef, ToolNodeDef, agent_tool
+from calfkit.nodes import Agent, BaseNodeDef, ConsumerFn, ConsumerNodeDef, GateFunction, NodeDef, ToolNodeDef, agent_tool, consumer
 from calfkit.providers import AnthropicModelClient, OpenAIModelClient, OpenAIResponsesModelClient
 from calfkit.worker import Worker
 
@@ -18,10 +18,13 @@ __all__ = [
     # nodes
     "Agent",
     "BaseNodeDef",
+    "ConsumerFn",
+    "ConsumerNodeDef",
     "GateFunction",
     "NodeDef",
     "ToolNodeDef",
     "agent_tool",
+    "consumer",
     # providers
     "AnthropicModelClient",
     "OpenAIModelClient",

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/_protocol.py

@@ -8,7 +8,7 @@ Do not add imports from ``calfkit.*`` to this module.
 
 from typing import Any, Literal
 
-NodeKind = Literal["node", "agent", "tool", "client"]
+NodeKind = Literal["node", "agent", "tool", "client", "consumer"]
 """Closed value space for the ``x-calf-emitter-kind`` Kafka header. Subclasses of
 ``BaseNodeDef`` declare their kind via ``_node_kind: ClassVar[NodeKind]``; the
 client publishes with ``CLIENT_KIND`` directly.

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/client/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from collections.abc import Sequence
 from typing import Any, overload
 
@@ -7,6 +8,7 @@ import uuid_utils
 
 from calfkit._types import OutputT
 from calfkit._vendor.pydantic_ai.messages import ModelMessage, ModelRequest
+from calfkit._vendor.pydantic_ai.settings import ModelSettings
 from calfkit.client.base import BaseClient
 from calfkit.client.deserialize import _UNSET
 from calfkit.client.invocation_handle import InvocationHandle
@@ -39,6 +41,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = ...,
         run_args: Sequence[Any] | None = ...,
         deps: dict[str, Any] | None = ...,
+        model_settings: ModelSettings | dict[str, Any] | None = ...,
     ) -> InvocationHandle[OutputT]: ...
 
     @overload
@@ -54,6 +57,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = ...,
         run_args: Sequence[Any] | None = ...,
         deps: dict[str, Any] | None = ...,
+        model_settings: ModelSettings | dict[str, Any] | None = ...,
     ) -> InvocationHandle[Any]: ...
 
     async def invoke_node(
@@ -69,6 +73,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = None,
         run_args: Sequence[Any] | None = None,
         deps: dict[str, Any] | None = None,
+        model_settings: ModelSettings | dict[str, Any] | None = None,
     ) -> InvocationHandle[Any]:
         """Invoke an agent node asynchronously and return a handle for the reply.
 
@@ -95,11 +100,21 @@ class Client(BaseClient):
                 method.
             deps: A mapping of dependency keys to values, made available to
                 the node's tools at runtime via the session context.
+            model_settings: Per-call model settings (e.g. ``{"temperature": 0.0}``)
+                that merge over the agent's constructor defaults, which in turn
+                merge over the model client's defaults. Must be JSON-serializable
+                since it travels over Kafka.
 
         Returns:
             An :class:`InvocationHandle` whose ``result()`` resolves to a
             :class:`NodeResult`.
         """
+        if model_settings is not None:
+            try:
+                json.dumps(model_settings, allow_nan=False)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"model_settings is not JSON-serializable: {exc}. Payload: {model_settings!r}") from exc
+
         if correlation_id is None:
             correlation_id = uuid_utils.uuid7().hex
         if reply_topic is None:
@@ -107,13 +122,21 @@ class Client(BaseClient):
 
         state = State(message_history=message_history or list(), temp_instructions=temp_instructions)
         state.stage_message(ModelRequest.user_text_prompt(user_prompt))
+        overrides = (
+            OverridesState(
+                override_agent_tools=tool_overrides,
+                model_settings=dict(model_settings) if model_settings is not None else None,
+            )
+            if tool_overrides is not None or model_settings is not None
+            else None
+        )
         return await self._invoke(
             topic=topic,
             reply_topic=reply_topic,
             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,
+            overrides=overrides,
             deps=deps,
             output_type=output_type,
         )
@@ -132,6 +155,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = ...,
         run_args: Sequence[Any] | None = ...,
         deps: dict[str, Any] | None = ...,
+        model_settings: ModelSettings | dict[str, Any] | None = ...,
         timeout: float | None = ...,
     ) -> NodeResult[OutputT]: ...
 
@@ -148,6 +172,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = ...,
         run_args: Sequence[Any] | None = ...,
         deps: dict[str, Any] | None = ...,
+        model_settings: ModelSettings | dict[str, Any] | None = ...,
         timeout: float | None = ...,
     ) -> NodeResult[Any]: ...
 
@@ -164,6 +189,7 @@ class Client(BaseClient):
         message_history: list[ModelMessage] | None = None,
         run_args: Sequence[Any] | None = None,
         deps: dict[str, Any] | None = None,
+        model_settings: ModelSettings | dict[str, Any] | None = None,
         timeout: float | None = None,
     ) -> NodeResult[Any]:
         """Invoke an agent node and await the reply in a single call.
@@ -193,6 +219,10 @@ class Client(BaseClient):
                 method.
             deps: A mapping of dependency keys to values, made available to
                 the node's tools at runtime via the session context.
+            model_settings: Per-call model settings (e.g. ``{"temperature": 0.0}``)
+                that merge over the agent's constructor defaults, which in turn
+                merge over the model client's defaults. Must be JSON-serializable
+                since it travels over Kafka.
             timeout: Maximum seconds to wait for the reply. ``None`` means
                 wait indefinitely.
 
@@ -214,5 +244,6 @@ class Client(BaseClient):
             message_history=message_history,
             run_args=run_args,
             deps=deps,
+            model_settings=model_settings,
         )
         return await handle.result(timeout=timeout)

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/client/deserialize.py

@@ -15,6 +15,9 @@ _UNSET: Any = object()
 def deserialize_to_node_result(
     envelope: Envelope,
     output_type: type[Any] = _UNSET,
+    *,
+    strict: bool = True,
+    type_adapter: TypeAdapter[Any] | None = None,
 ) -> NodeResult[Any]:
     """Project an ``Envelope`` into a client-facing ``NodeResult``.
 
@@ -26,41 +29,57 @@ def deserialize_to_node_result(
               (returned as a raw dict), fall back to ``TextPart.text`` (str).
             * ``str``: extract the first ``TextPart.text``.
             * **anything else**: extract the first ``DataPart.data`` and validate
-              it through ``TypeAdapter(output_type)``.
+              it through ``TypeAdapter(output_type)`` (or *type_adapter* if
+              provided).
+        strict: When ``True`` (default — client semantics), raises
+            :class:`DeserializationError` if ``final_output_parts`` is empty or
+            doesn't contain the expected part type. When ``False`` (consumer
+            semantics), returns ``output=None`` for an empty
+            ``final_output_parts`` (intermediate hop / tool completion);
+            validation errors on *present* parts still propagate.
+        type_adapter: An optional pre-built :class:`pydantic.TypeAdapter` to
+            use for validating ``DataPart.data`` against *output_type*. When
+            ``None`` (default), a new adapter is constructed per call.
+            Consumers pre-build at wiring time so schema-generation errors
+            surface once at construction rather than per envelope.
 
     Returns:
-        A ``NodeResult`` whose ``.output`` is typed according to *output_type*.
+        A ``NodeResult`` whose ``.output`` is typed according to *output_type*
+        (or ``None`` when ``strict=False`` and no parts are present).
 
     Raises:
         DeserializationError: If the expected content part is not found in
-            ``final_output_parts``.
+            ``final_output_parts`` (and either ``strict=True`` or the parts
+            list is non-empty but lacks the expected shape).
+        pydantic.ValidationError: If ``output_type`` is provided and the
+            matching ``DataPart.data`` doesn't validate against it.
+        pydantic.PydanticSchemaGenerationError: If ``type_adapter`` is ``None``
+            and ``output_type`` cannot be schematized by :class:`TypeAdapter`.
     """
     state = envelope.context.state
-    output_parts = state.final_output_parts
-    message_history = state.message_history
-    metadata = state.metadata
     correlation_id = envelope.context.deps.correlation_id
 
-    output = _extract_output(output_parts, output_type)
+    if not state.final_output_parts and not strict:
+        output: Any = None
+    else:
+        output = _extract_output(state.final_output_parts, output_type, type_adapter=type_adapter)
 
     return NodeResult(
         output=output,
-        output_parts=output_parts,
-        message_history=message_history,
-        metadata=metadata,
+        state=state,
         correlation_id=correlation_id,
         emitter_node_id=envelope.context.emitter_node_id,
         emitter_node_kind=envelope.context.emitter_node_kind,
     )
 
 
-def _extract_output(parts: list[Any], output_type: type[Any]) -> Any:
+def _extract_output(parts: list[Any], output_type: type[Any], type_adapter: TypeAdapter[Any] | None = None) -> Any:
     """Extract and optionally deserialize the output from content parts."""
     if output_type is _UNSET:
         return _extract_auto(parts)
     if output_type is str:
         return _extract_text(parts)
-    return _extract_data(parts, output_type)
+    return _extract_data(parts, output_type, type_adapter=type_adapter)
 
 
 def _extract_auto(parts: list[Any]) -> Any:
@@ -82,10 +101,15 @@ def _extract_text(parts: list[Any]) -> str:
     raise DeserializationError("No TextPart found in final_output_parts; expected output_type=str.")
 
 
-def _extract_data(parts: list[Any], output_type: type[Any]) -> Any:
-    """Extract the first DataPart.data and validate via TypeAdapter."""
+def _extract_data(parts: list[Any], output_type: type[Any], type_adapter: TypeAdapter[Any] | None = None) -> Any:
+    """Extract the first DataPart.data and validate via TypeAdapter.
+
+    Uses *type_adapter* if provided; otherwise constructs a new one (which may
+    raise :class:`pydantic.PydanticSchemaGenerationError` if *output_type* is
+    unschematizable).
+    """
     for part in parts:
         if isinstance(part, DataPart):
-            adapter: TypeAdapter[Any] = TypeAdapter(output_type)
+            adapter = type_adapter if type_adapter is not None else TypeAdapter(output_type)
             return adapter.validate_python(part.data)
     raise DeserializationError(f"No DataPart found in final_output_parts; expected output_type={getattr(output_type, '__name__', str(output_type))}.")

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/client/invocation_handle.py

@@ -30,7 +30,13 @@ class InvocationHandle(Generic[OutputT]):
         Raises:
             asyncio.TimeoutError: If *timeout* elapses before a reply arrives.
             RuntimeError: If this handle was created without a future (fire-and-forget).
-            DeserializationError: If the expected output part type is missing.
+            DeserializationError: If the expected output part type is missing
+                from ``final_output_parts``.
+            pydantic.ValidationError: If ``output_type`` is provided and the
+                reply's ``DataPart.data`` doesn't validate against it.
+            pydantic.PydanticSchemaGenerationError: If ``output_type`` cannot
+                be schematized by :class:`pydantic.TypeAdapter` (e.g. an
+                unsupported generic or non-type value).
         """
         if self._future is None:
             raise RuntimeError("This handle has no associated future — was the client's reply dispatcher configured?")

calfkit-0.3.2/calfkit/client/node_result.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic
+
+from calfkit._types import OutputT
+from calfkit._vendor.pydantic_ai.messages import ModelMessage
+from calfkit.models import ContentPart, State
+
+
+@dataclass(frozen=True)
+class NodeResult(Generic[OutputT]):
+    """Client-facing projection of the session state after a node returns.
+
+    A ``NodeResult`` is what callers receive in two places:
+
+    * :meth:`Client.execute_node` / :meth:`InvocationHandle.result` — the
+      final reply from an agent invocation.
+    * The user function of a :class:`ConsumerNodeDef` — one per envelope on
+      every subscribed topic, including intermediate hops.
+
+    The ``state`` field is the full session :class:`~calfkit.models.State` at
+    the moment this envelope was published, exposing message history, in-flight
+    tool calls/results, application metadata, runtime overrides, and any other
+    state fields. ``message_history``, ``output_parts``, and ``metadata`` are
+    convenience properties that read through ``state``.
+
+    Treat ``NodeResult`` and its ``state`` as read-only. The dataclass is
+    frozen, but ``state`` is a mutable Pydantic model:
+
+    * **Consumer path**: the consumer never republishes (no ``publish_topic``),
+      so mutations have no observable downstream effect. They can still
+      surprise other code holding the same ``NodeResult`` instance.
+    * **Client path** (:meth:`Client.execute_node` / :meth:`InvocationHandle.result`):
+      the caller's lifetime owns the instance — mutations are caller-visible
+      and may corrupt any other code holding a parallel reference (caches,
+      retry layers, etc.).
+
+    ``NodeResult`` is intentionally unhashable (``__hash__ = None``): the
+    underlying ``state`` field is a mutable Pydantic model and cannot be
+    placed in a set or used as a dict key safely. Use ``correlation_id`` if
+    you need a hashable identifier.
+    """
+
+    output: OutputT | None
+    """Deserialized final output (typed via ``output_type``).
+
+    ``None`` on intermediate hops — envelopes whose ``state.final_output_parts``
+    is empty (e.g. agent hops mid-tool-call, tool completions). Populated when
+    the upstream node emitted a terminal envelope with final output parts.
+    Client-side strict-mode results (the default) always have ``output``
+    populated; consumer-side results may not.
+    """
+
+    state: State
+    """Full session state at this hop. Includes:
+
+    * ``message_history`` — cumulative conversation
+    * ``final_output_parts`` — agent's structured/text output (empty on
+      intermediate hops)
+    * ``tool_calls`` / ``tool_results`` — in-flight tool batch (keyed by
+      ``tool_call_id``)
+    * ``metadata`` — application-level metadata
+    * ``overrides`` — agent tool overrides applied to this invocation (or
+      ``None`` if unset)
+    * ``uncommitted_message`` / ``temp_instructions`` — agent-loop scratch;
+      usually ``None`` on terminal hops, may be populated mid-loop and is not
+      part of the public contract
+    """
+
+    correlation_id: str
+    """The correlation ID that ties this result to its invocation."""
+
+    emitter_node_id: str | None = None
+    """Node id of the node that emitted this reply (sourced from the
+    ``x-calf-emitter`` Kafka header). May be ``None`` if the upstream
+    producer didn't stamp the header (e.g. a non-calfkit publisher)."""
+
+    emitter_node_kind: str | None = None
+    """Coarse classification of the emitter (one of ``NodeKind``), sourced
+    from the ``x-calf-emitter-kind`` Kafka header. May be ``None`` if not
+    stamped."""
+
+    # NodeResult holds a mutable Pydantic model (state); the dataclass-
+    # synthesized __hash__ would recursively try to hash unhashable fields and
+    # raise at use-time. Declare unhashability explicitly so static type
+    # checkers and runtime introspection agree.
+    __hash__ = None  # type: ignore[assignment]
+
+    @property
+    def output_parts(self) -> list[ContentPart]:
+        """Convenience: ``state.final_output_parts``."""
+        return self.state.final_output_parts
+
+    @property
+    def message_history(self) -> list[ModelMessage]:
+        """Convenience: ``state.message_history``."""
+        return self.state.message_history
+
+    @property
+    def metadata(self) -> Any:
+        """Convenience: ``state.metadata``."""
+        return self.state.metadata

calfkit-0.3.2/calfkit/models/node_schema.py

@@ -0,0 +1,32 @@
+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]
+        # Reject empty subscribe_topics for every node kind (Agent, Consumer,
+        # Tool, …). Lives here rather than in ``BaseNodeDef.__init__`` because
+        # ``@dataclass`` subclasses like ``BaseToolNodeDef`` get an
+        # auto-generated ``__init__`` that bypasses ``BaseNodeDef.__init__``
+        # entirely; ``__post_init__`` is the one hook every subclass runs.
+        # Without this guard, ``Worker.register_handlers`` would still add
+        # ``_return_topic`` to the subscriber set (issue #141 fix), so the
+        # node would "register" successfully but have no public inbox — a
+        # silent zombie consumer.
+        if not self.subscribe_topics:
+            raise ValueError(f"node {self.node_id!r} requires at least one subscribe_topic; got empty list")
+
+
+@dataclass
+class BaseToolNodeSchema(BaseNodeSchema):
+    _: KW_ONLY
+    tool_schema: ToolDefinition

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

@@ -23,7 +23,8 @@ class OverridesState(BaseAgentActivityState):
     """State for storing any override objects"""
 
     model_config = ConfigDict(extra="ignore")
-    override_agent_tools: list[BaseToolNodeSchema] | None
+    override_agent_tools: list[BaseToolNodeSchema] | None = None
+    model_settings: dict[str, Any] | None = None
 
 
 class CoreMessageState(BaseAgentActivityState):

{calfkit-0.3.0 → calfkit-0.3.2}/calfkit/nodes/__init__.py

@@ -1,5 +1,6 @@
 from calfkit.nodes.agent import Agent, BaseAgentNodeDef
 from calfkit.nodes.base import BaseNodeDef, GateFunction
+from calfkit.nodes.consumer import ConsumerFn, ConsumerNodeDef, consumer
 from calfkit.nodes.node import NodeDef
 from calfkit.nodes.tool import BaseToolNodeDef, ToolNodeDef, agent_tool
 
@@ -8,8 +9,11 @@ __all__ = [
     "BaseAgentNodeDef",
     "BaseNodeDef",
     "BaseToolNodeDef",
+    "ConsumerFn",
+    "ConsumerNodeDef",
     "GateFunction",
     "NodeDef",
     "ToolNodeDef",
     "agent_tool",
+    "consumer",
 ]

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

@@ -1,6 +1,6 @@
 import logging
 from collections.abc import Callable
-from typing import Any, ClassVar, Generic
+from typing import Any, ClassVar, Generic, cast
 
 from calfkit._protocol import NodeKind
 from calfkit._types import AgentOutputT
@@ -8,6 +8,7 @@ from calfkit._vendor.pydantic_ai import Agent as InternalAgentLoop
 from calfkit._vendor.pydantic_ai import DeferredToolRequests
 from calfkit._vendor.pydantic_ai.messages import RetryPromptPart
 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.models import Call, DataPart, NodeResult, ReturnCall, State, TailCall, TextPart
@@ -42,6 +43,7 @@ class BaseAgentNodeDef(
         model_client: PydanticModelClient,
         final_output_type: OutputSpec[AgentOutputT] = str,  # type: ignore[assignment]
         sequential_only_mode: bool = False,
+        model_settings: ModelSettings | dict[str, Any] | None = None,
     ):
         self.final_output_type = final_output_type
         self.system_prompt = system_prompt
@@ -55,7 +57,12 @@ class BaseAgentNodeDef(
         super().__init__(node_id=node_id, subscribe_topics=subscribe_topics, publish_topic=publish_topic, gates=gates)
 
         self._agent_loop: InternalAgentLoop[dict[str, Any], AgentOutputT | DeferredToolRequests] = InternalAgentLoop(
-            model_client, name=self.name, output_type=[final_output_type, DeferredToolRequests], deps_type=dict, instructions=system_prompt
+            model_client,
+            name=self.name,
+            output_type=[final_output_type, DeferredToolRequests],
+            deps_type=dict,
+            instructions=system_prompt,
+            model_settings=cast(ModelSettings | None, model_settings),
         )
 
     def _parallel_state_aggregation(self, ctx: SessionRunContext) -> None:
@@ -124,12 +131,14 @@ class BaseAgentNodeDef(
         if ctx.state.uncommitted_message is not None:
             ctx.state.commit_message_to_history()
 
+        run_model_settings = cast(ModelSettings | None, ctx.state.overrides.model_settings) if ctx.state.overrides is not None else None
         result = await self._agent_loop.run(
             message_history=ctx.state.message_history,
             instructions=ctx.state.temp_instructions,
             toolsets=[ExternalToolset([tool.tool_schema for tool in tools_registry.values()])],
             deps=ctx.deps.provided_deps,  # None valid when AgentDepsT=NoneType
             deferred_tool_results=tool_results,
+            model_settings=run_model_settings,
         )
         if isinstance(result.output, DeferredToolRequests):
             # The LLM called one or more tools
@@ -175,7 +184,7 @@ class BaseAgentNodeDef(
                 # 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)
-                return TailCall[State](target_topic=self.subscribe_topics[0], state=ctx.state)
+                return TailCall[State](target_topic=self._return_topic, state=ctx.state)
 
             pending_tool_calls = [tc for tc in latest_tool_calls if tc.tool_call_id not in ctx.state.tool_results]