calfkit 0.1.1__tar.gz → 0.1.2__tar.gz

calfkit-0.1.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ryan-yuuu

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

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

{calfkit-0.1.1 → calfkit-0.1.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.1.1...v0.1.2) (2026-02-04)
+
+
+### Bug Fixes
+
+* invoke function on unstarted broker + doc: readme quickstart examples ([#30](https://github.com/calf-ai/calfkit-sdk/issues/30)) ([bad4216](https://github.com/calf-ai/calfkit-sdk/commit/bad4216a779fe785f76bc627d4c61a98df800922))
+
 ## [0.1.1](https://github.com/calf-ai/calf-sdk/compare/v0.1.0...v0.1.1) (2026-02-03)
 
 

calfkit-0.1.2/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: calfkit
+Version: 0.1.2
+Summary: Event-driven SDK for building AI workflows on Kafka
+Project-URL: Homepage, https://github.com/calf-ai/calf-sdk
+Project-URL: Repository, https://github.com/calf-ai/calf-sdk
+Project-URL: Issues, https://github.com/calf-ai/calf-sdk/issues
+Author: Ryan Yu
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,decoupled,distributed,event-driven,kafka,llm,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: faststream[kafka]>=0.6.6
+Requires-Dist: pydantic-ai>=1.47.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: uuid-utils>=0.14.0
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Calfkit SDK
+
+The SDK to build AI agents that scale. Calfkit lets you compose agents from independent services—chat, tools, routing—that communicate through events, not API calls. Add capabilities without coordination. Scale each component independently. Stream agent outputs to any downstream system.
+
+## Why Event-Driven Agents?
+
+Building agents like traditional web applications—with tight coupling and direct API calls—creates the same scalability problems that plagued early microservices.
+
+When agents connect through APIs and RPC:
+- **Tight coupling** — Changing one tool breaks dependent agents
+- **Scaling bottlenecks** — Everything must scale together
+- **Siloed outputs** — Agent responses stay trapped in your AI layer
+
+Event-driven architecture provides the solution. Instead of direct API calls between components, agents interact through asynchronous event streams. Each component runs independently, scales horizontally, and outputs can flow anywhere—CRMs, data warehouses, analytics platforms, other agents.
+
+## Why use Calfkit?
+
+Calfkit is a Python SDK that makes event-driven agents simple. You get the benefits of a distributed system—loose coupling, horizontal scalability, durability—without the complexity of managing Kafka infrastructure yourself.
+
+- **Distributed agents out of the box** — Build event-driven, multi-service agents without writing orchestration code or managing infrastructure
+- **Add tools without touching existing code** — Deploy new capabilities as independent services that other agents discover automatically
+- **Scale what you need, when you need it** — Chat handling, tool execution, and routing each scale independently based on demand
+- **Nothing gets lost** — Event persistence ensures reliable message delivery—even during failures or restarts
+- **Real-time responses** — Low-latency event processing enables agents to react instantly to incoming data
+- **Team independence** — Different teams can develop and deploy chat, tools, and routing concurrently without coordination overhead
+- **Universal data flow** — Decoupling enables data to flow freely in both directions. Downstream, agent outputs integrate with any system (CRMs, CDPs, warehouses). Upstream, tools wrap data sources and deploy independently—no coordination needed.
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# Kafka (single command via Docker)
+docker run -d -p 9092:9092 apache/kafka:latest
+
+# Python 3.10+
+python --version
+
+# OpenAI API key
+export OPENAI_API_KEY=sk-...
+```
+
+### Install
+
+```bash
+pip install git+https://github.com/calf-ai/calf-sdk.git
+```
+
+### Deploy the Tool Node
+
+Define and deploy a tool as an independent service.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool
+from calfkit.broker import Broker
+from calfkit.runners import ToolRunner
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    ToolRunner(get_weather).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Deploy the Chat Node
+
+Deploy the LLM chat handler as its own service.
+
+```python
+import asyncio
+from calfkit.nodes import ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.broker import Broker
+from calfkit.runners import ChatRunner
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-5-nano")
+    chat_node = ChatNode(model_client)
+    ChatRunner(chat_node).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Deploy the Agent Router Node
+
+Deploy the router that orchestrates chat and tools.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool, AgentRouterNode, ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.stores import InMemoryMessageHistoryStore
+from calfkit.broker import Broker
+from calfkit.runners import AgentRouterRunner
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-4o")
+    router_node = AgentRouterNode(
+        chat_node=ChatNode(model_client),
+        tool_nodes=[get_weather],
+        system_prompt="You are a helpful assistant",
+        message_history_store=InMemoryMessageHistoryStore(),
+    )
+    AgentRouterRunner(router_node).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Invoke the Agent
+
+Send a request and receive the response.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool, AgentRouterNode, ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.stores import InMemoryMessageHistoryStore
+from calfkit.broker import Broker
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-5-nano")
+
+    router_node = AgentRouterNode(
+        chat_node=ChatNode(model_client),
+        tool_nodes=[get_weather],
+        system_prompt="You are a helpful assistant",
+        message_history_store=InMemoryMessageHistoryStore(),
+    )
+
+    correlation_id = await router_node.invoke(
+        user_prompt="What's the weather in Tokyo?",
+        broker=broker,
+        final_response_topic="final_response",
+    )
+    print(f"Request started: {correlation_id}")
+
+asyncio.run(main())
+```
+
+## License
+
+Apache-2.0

calfkit-0.1.2/README.md

@@ -0,0 +1,164 @@
+# Calfkit SDK
+
+The SDK to build AI agents that scale. Calfkit lets you compose agents from independent services—chat, tools, routing—that communicate through events, not API calls. Add capabilities without coordination. Scale each component independently. Stream agent outputs to any downstream system.
+
+## Why Event-Driven Agents?
+
+Building agents like traditional web applications—with tight coupling and direct API calls—creates the same scalability problems that plagued early microservices.
+
+When agents connect through APIs and RPC:
+- **Tight coupling** — Changing one tool breaks dependent agents
+- **Scaling bottlenecks** — Everything must scale together
+- **Siloed outputs** — Agent responses stay trapped in your AI layer
+
+Event-driven architecture provides the solution. Instead of direct API calls between components, agents interact through asynchronous event streams. Each component runs independently, scales horizontally, and outputs can flow anywhere—CRMs, data warehouses, analytics platforms, other agents.
+
+## Why use Calfkit?
+
+Calfkit is a Python SDK that makes event-driven agents simple. You get the benefits of a distributed system—loose coupling, horizontal scalability, durability—without the complexity of managing Kafka infrastructure yourself.
+
+- **Distributed agents out of the box** — Build event-driven, multi-service agents without writing orchestration code or managing infrastructure
+- **Add tools without touching existing code** — Deploy new capabilities as independent services that other agents discover automatically
+- **Scale what you need, when you need it** — Chat handling, tool execution, and routing each scale independently based on demand
+- **Nothing gets lost** — Event persistence ensures reliable message delivery—even during failures or restarts
+- **Real-time responses** — Low-latency event processing enables agents to react instantly to incoming data
+- **Team independence** — Different teams can develop and deploy chat, tools, and routing concurrently without coordination overhead
+- **Universal data flow** — Decoupling enables data to flow freely in both directions. Downstream, agent outputs integrate with any system (CRMs, CDPs, warehouses). Upstream, tools wrap data sources and deploy independently—no coordination needed.
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# Kafka (single command via Docker)
+docker run -d -p 9092:9092 apache/kafka:latest
+
+# Python 3.10+
+python --version
+
+# OpenAI API key
+export OPENAI_API_KEY=sk-...
+```
+
+### Install
+
+```bash
+pip install git+https://github.com/calf-ai/calf-sdk.git
+```
+
+### Deploy the Tool Node
+
+Define and deploy a tool as an independent service.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool
+from calfkit.broker import Broker
+from calfkit.runners import ToolRunner
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    ToolRunner(get_weather).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Deploy the Chat Node
+
+Deploy the LLM chat handler as its own service.
+
+```python
+import asyncio
+from calfkit.nodes import ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.broker import Broker
+from calfkit.runners import ChatRunner
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-5-nano")
+    chat_node = ChatNode(model_client)
+    ChatRunner(chat_node).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Deploy the Agent Router Node
+
+Deploy the router that orchestrates chat and tools.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool, AgentRouterNode, ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.stores import InMemoryMessageHistoryStore
+from calfkit.broker import Broker
+from calfkit.runners import AgentRouterRunner
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-4o")
+    router_node = AgentRouterNode(
+        chat_node=ChatNode(model_client),
+        tool_nodes=[get_weather],
+        system_prompt="You are a helpful assistant",
+        message_history_store=InMemoryMessageHistoryStore(),
+    )
+    AgentRouterRunner(router_node).register_on(broker)
+    await broker.run_app()
+
+asyncio.run(main())
+```
+
+### Invoke the Agent
+
+Send a request and receive the response.
+
+```python
+import asyncio
+from calfkit.nodes import agent_tool, AgentRouterNode, ChatNode
+from calfkit.providers import OpenAIModelClient
+from calfkit.stores import InMemoryMessageHistoryStore
+from calfkit.broker import Broker
+
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-5-nano")
+
+    router_node = AgentRouterNode(
+        chat_node=ChatNode(model_client),
+        tool_nodes=[get_weather],
+        system_prompt="You are a helpful assistant",
+        message_history_store=InMemoryMessageHistoryStore(),
+    )
+
+    correlation_id = await router_node.invoke(
+        user_prompt="What's the weather in Tokyo?",
+        broker=broker,
+        final_response_topic="final_response",
+    )
+    print(f"Request started: {correlation_id}")
+
+asyncio.run(main())
+```
+
+## License
+
+Apache-2.0

{calfkit-0.1.1 → calfkit-0.1.2}/calfkit/broker/middleware.py

@@ -1,6 +1,7 @@
+from collections.abc import Awaitable, Callable
 from typing import Any
 
-from faststream import BaseMiddleware
+from faststream import BaseMiddleware, PublishCommand
 from faststream.message import StreamMessage
 from faststream.types import AsyncFuncAny
 
@@ -13,3 +14,10 @@ class ContextInjectionMiddleware(BaseMiddleware):
     ) -> Any:
         with self.context.scope("correlation_id", msg.correlation_id):
             return await super().consume_scope(call_next, msg)
+
+    async def publish_scope(
+        self,
+        call_next: Callable[[PublishCommand], Awaitable[Any]],
+        cmd: PublishCommand,
+    ) -> Any:
+        return await call_next(cmd)

{calfkit-0.1.1 → calfkit-0.1.2}/calfkit/models/types.py

@@ -57,6 +57,7 @@ class CompactBaseModel(BaseModel):
     def model_dump(self, **kwargs: Any) -> dict[str, Any]:
         kwargs.setdefault("exclude_unset", True)
         kwargs.setdefault("exclude_none", True)
+        kwargs.setdefault("mode", "json")  # Converts datetime, etc. to JSON-serializable types
         return super().model_dump(**kwargs)
 
     def model_dump_json(self, **kwargs: Any) -> str:

{calfkit-0.1.1 → calfkit-0.1.2}/calfkit/nodes/agent_router_node.py

@@ -1,4 +1,4 @@
-from typing import Annotated, Any
+from typing import Annotated, Any, overload
 
 import uuid_utils
 from faststream import Context
@@ -23,16 +23,84 @@ class AgentRouterNode(BaseNode):
     _router_sub_topic_name = "agent_router.input"
     _router_pub_topic_name = "agent_router.output"
 
+    @overload
     def __init__(
         self,
         chat_node: BaseNode,
+        *,
+        system_prompt: str,
         tool_nodes: list[BaseToolNode],
+        handoff_nodes: list[type[BaseNode]] = [],
+        message_history_store: MessageHistoryStore,
+        **kwargs: Any,
+    ): ...
+
+    @overload
+    def __init__(
+        self,
+        chat_node: BaseNode,
+        *,
         system_prompt: str | None = None,
+        tool_nodes: list[BaseToolNode] = [],
+        handoff_nodes: list[type[BaseNode]] = [],
+        message_history_store: MessageHistoryStore | None = None,
+        **kwargs: Any,
+    ): ...
+
+    @overload
+    def __init__(self) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        system_prompt: str | None = None,
+        tool_nodes: list[BaseToolNode] = [],
+        handoff_nodes: list[type[BaseNode]] = [],
+    ): ...
+
+    def __init__(
+        self,
+        chat_node: BaseNode | None = None,
+        *,
+        system_prompt: str | None = None,
+        tool_nodes: list[BaseToolNode] = [],
         handoff_nodes: list[type[BaseNode]] = [],
         message_history_store: MessageHistoryStore | None = None,
-        *args: Any,
         **kwargs: Any,
     ):
+        """Initialize an AgentRouterNode.
+
+        The AgentRouterNode supports multiple initialization patterns depending on use case:
+
+        1. **Deployable Router Service** (with required parameters):
+           Use when deploying the router as a service with all dependencies explicitly provided.
+           Requires: chat_node, system_prompt (str), tool_nodes, message_history_store
+
+        2. **Deployable Router Service** (with optional parameters):
+           Use when deploying with optional or runtime-configurable dependencies.
+           Requires: chat_node
+           Optional: system_prompt, tool_nodes, handoff_nodes, message_history_store
+
+        3. **Minimal Client**:
+           Use when creating a client to invoke an already-deployed router service.
+           No parameters needed - connects to the deployed service via the broker.
+
+        4. **Client with Runtime Patches**:
+           Use when creating a client that provides its own tools/system prompt at runtime,
+           overriding or supplementing what the deployed router service provides.
+           Optional: system_prompt, tool_nodes, handoff_nodes
+
+        Args:
+            chat_node: The chat node for LLM interactions. Required for deployable services.
+            system_prompt: Optional system prompt to override the default. Must be str for
+                deployable service, optional for client with runtime patches.
+            tool_nodes: List of tool nodes that the agent can call. Optional for all forms.
+            handoff_nodes: List of node types for agent handoff scenarios. Optional.
+            message_history_store: Store for persisting conversation history across requests.
+                Required for deployable service, optional otherwise.
+            **kwargs: Additional keyword arguments passed to BaseNode.
+        """
         self.chat = chat_node
         self.tools = tool_nodes
         self.handoffs = handoff_nodes
@@ -52,7 +120,7 @@ class AgentRouterNode(BaseNode):
 
         self.tool_response_topics = [tool.publish_to_topic for tool in self.tools]
 
-        super().__init__(*args, **kwargs)
+        super().__init__(**kwargs)
 
     @subscribe_to(_router_sub_topic_name)
     @publish_to(_router_pub_topic_name)
@@ -148,7 +216,7 @@ class AgentRouterNode(BaseNode):
         )
         await broker.publish(
             event_envelope,
-            topic=self.chat.subscribed_topic,
+            topic=self.chat.subscribed_topic,  # type: ignore
             correlation_id=correlation_id,
             reply_to=self.subscribed_topic,
         )
@@ -172,12 +240,16 @@ class AgentRouterNode(BaseNode):
         Returns:
             str: The correlation ID for this request
         """
-        patch_model_request_params = ModelRequestParameters(
-            function_tools=[tool.tool_schema() for tool in self.tools]
+
+        patch_model_request_params = (
+            ModelRequestParameters(function_tools=[tool.tool_schema() for tool in self.tools])
+            if self.tools
+            else None
         )
         if correlation_id is None:
             correlation_id = uuid_utils.uuid7().hex
         new_node_messages = [ModelRequest.user_text_prompt(user_prompt)]
+        await broker.start()
         await broker.publish(
             EventEnvelope(
                 kind="user_prompt",

calfkit-0.1.2/examples/real_broker/chat_node.py

@@ -0,0 +1,68 @@
+import asyncio
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from calfkit.broker.broker import Broker
+from calfkit.nodes.chat_node import ChatNode
+from calfkit.providers.pydantic_ai.openai import OpenAIModelClient
+from calfkit.runners.node_runner import ChatRunner
+
+load_dotenv()
+
+# Check for API key
+if not os.getenv("OPENAI_API_KEY"):
+    print("ERROR: OPENAI_API_KEY environment variable is not set")
+    print("Please set it before running:")
+    print(" export OPENAI_API_KEY='your-api-key'")
+    sys.exit(1)
+
+
+# Chat Node - Deploys the LLM chat worker.
+
+# This runs independently and handles all LLM inference requests.
+
+# Usage:
+#     uv run python examples/real_broker/chat_node.py
+
+# Prerequisites:
+#     - Kafka broker running at localhost:9092
+#     - OPENAI_API_KEY environment variable set
+
+
+async def main():
+    print("=" * 50)
+    print("Chat Node Deployment")
+    print("=" * 50)
+
+    # Connect to the real Kafka broker
+    print("\nConnecting to Kafka broker at localhost:9092...")
+    broker = Broker(bootstrap_servers="localhost:9092")
+
+    # Configure the LLM model
+    print("Configuring OpenAI model client...")
+    model_client = OpenAIModelClient(
+        model_name="gpt-5-nano",
+    )
+
+    # Deploy the chat node
+    print("Registering chat node...")
+    chat_node = ChatNode(model_client)
+    chat_runner = ChatRunner(node=chat_node)
+    chat_runner.register_on(broker)
+    print("  - ChatNode registered")
+    print(f"    Subscribe topic: {chat_node.subscribed_topic}")
+    print(f"    Publish topic: {chat_node.publish_to_topic}")
+
+    print("\nChat node ready. Waiting for requests...")
+
+    # Run the broker app (this blocks)
+    await broker.run_app()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\nChat node stopped.")