calfkit 0.1.1__py3-none-any.whl

calfkit/nodes/chat_node.py

@@ -0,0 +1,48 @@
+from abc import ABC
+from typing import Any, cast
+
+from pydantic_ai import ModelResponse, ModelSettings
+from pydantic_ai.direct import model_request
+from pydantic_ai.models import Model, ModelRequestParameters
+
+from calfkit.models.event_envelope import EventEnvelope
+from calfkit.nodes.base_node import BaseNode, publish_to, subscribe_to
+
+
+class ChatNode(BaseNode, ABC):
+    """Node defining the llm chat node internal wiring.
+    Separate from any logic for LLM persona or behaviour."""
+
+    _on_enter_topic_name = "ai_prompted"
+    _post_to_topic_name = "ai_generated"
+
+    def __init__(
+        self,
+        model_client: Model | None = None,
+        *,
+        request_parameters: ModelRequestParameters | None = None,
+        **kwargs: Any,
+    ):
+        self.model_client = model_client
+        self.request_parameters = request_parameters
+        super().__init__(**kwargs)
+
+    @subscribe_to(_on_enter_topic_name)
+    @publish_to(_post_to_topic_name)
+    async def _call_llm(self, event_envelope: EventEnvelope) -> EventEnvelope:
+        if self.model_client is None:
+            raise RuntimeError("Unable to handle incoming request because Model client is None.")
+        if event_envelope.latest_message_in_history is None:
+            raise RuntimeError("latest message must not be None")
+        request_parameters = event_envelope.patch_model_request_params or self.request_parameters
+        patch_model_settings = event_envelope.patch_model_settings
+        model_response: ModelResponse = await model_request(
+            model=self.model_client,
+            messages=event_envelope.message_history,
+            model_settings=cast(ModelSettings | None, patch_model_settings),
+            model_request_parameters=request_parameters,
+        )
+        return_envelope = event_envelope.model_copy(
+            update={"kind": "ai_response", "incoming_node_messages": [model_response]}
+        )
+        return return_envelope

calfkit/nodes/registrator.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from calfkit.broker.broker import Broker
+
+
+class Registrator(ABC):
+    @abstractmethod
+    def register_on(self, broker: Broker, *args: Any, **kwargs: Any) -> None:
+        """Function to fluently register a node's handlers onto a broker to serve traffic"""
+        pass

calfkit/providers/__init__.py

@@ -0,0 +1,5 @@
+"""Calf LLM Provider System."""
+
+from calfkit.providers.pydantic_ai import OpenAIModelClient
+
+__all__ = ["OpenAIModelClient"]

calfkit/providers/pydantic_ai/__init__.py

@@ -0,0 +1,3 @@
+from calfkit.providers.pydantic_ai.openai import OpenAIModelClient
+
+__all__ = ["OpenAIModelClient"]

calfkit/providers/pydantic_ai/openai.py

@@ -0,0 +1,61 @@
+from typing import Any
+
+from httpx import Timeout
+from pydantic_ai.models.openai import OpenAIChatModel, OpenAIChatModelSettings
+from pydantic_ai.providers.openai import OpenAIProvider
+
+
+class OpenAIModelClient(OpenAIChatModel):
+    def __init__(
+        self,
+        model_name: str,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        reasoning_effort: str | None = None,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        timeout: float | Timeout | None = None,
+        parallel_tool_calls: bool | None = None,
+        seed: int | None = None,
+        presence_penalty: float | None = None,
+        frequency_penalty: float | None = None,
+        logit_bias: dict[str, int] | None = None,
+        stop_sequences: list[str] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        extra_body: object | None = None,
+        **kwargs: Any,
+    ):
+        settings_kwargs: dict[str, object] = {}
+        if reasoning_effort is not None:
+            settings_kwargs["openai_reasoning_effort"] = reasoning_effort
+        if max_tokens is not None:
+            settings_kwargs["max_tokens"] = max_tokens
+        if temperature is not None:
+            settings_kwargs["temperature"] = temperature
+        if top_p is not None:
+            settings_kwargs["top_p"] = top_p
+        if timeout is not None:
+            settings_kwargs["timeout"] = timeout
+        if parallel_tool_calls is not None:
+            settings_kwargs["parallel_tool_calls"] = parallel_tool_calls
+        if seed is not None:
+            settings_kwargs["seed"] = seed
+        if presence_penalty is not None:
+            settings_kwargs["presence_penalty"] = presence_penalty
+        if frequency_penalty is not None:
+            settings_kwargs["frequency_penalty"] = frequency_penalty
+        if logit_bias is not None:
+            settings_kwargs["logit_bias"] = logit_bias
+        if stop_sequences is not None:
+            settings_kwargs["stop_sequences"] = stop_sequences
+        if extra_headers is not None:
+            settings_kwargs["extra_headers"] = extra_headers
+        if extra_body is not None:
+            settings_kwargs["extra_body"] = extra_body
+        model_settings: OpenAIChatModelSettings = OpenAIChatModelSettings(**settings_kwargs)  # type: ignore[typeddict-item]
+
+        openai_client = OpenAIProvider(base_url=base_url, api_key=api_key)
+        self.model_settings = model_settings
+        super().__init__(model_name, provider=openai_client, settings=model_settings)

calfkit/runners/__init__.py

@@ -0,0 +1,14 @@
+"""Calf Agent System.
+
+This module provides runners for deploying agent nodes to a message broker.
+Runners handle the registration and lifecycle of agent nodes within the broker system.
+"""
+
+from calfkit.runners.node_runner import AgentRouterRunner, ChatRunner, NodeRunner, ToolRunner
+
+__all__ = [
+    "NodeRunner",
+    "ChatRunner",
+    "ToolRunner",
+    "AgentRouterRunner",
+]

calfkit/runners/node_runner.py

@@ -0,0 +1,38 @@
+from typing import Any, TypeAlias
+
+from calfkit.broker.broker import Broker
+from calfkit.nodes.base_node import BaseNode
+from calfkit.nodes.registrator import Registrator
+
+
+class NodeRunner(Registrator):
+    """The NodeRunner makes node logic deployable after registering on a broker. (Control plane)"""
+
+    def __init__(self, node: BaseNode, *args: Any, **kwargs: Any):
+        self.node = node
+        super().__init__(*args, **kwargs)
+
+    def register_on(
+        self,
+        broker: Broker,
+        *,
+        max_workers: int | None = None,
+        # group_id explicitly set as to avoid duplicated processing for separate deployments
+        group_id: str = "default",
+        extra_publish_kwargs: dict[str, Any] = {},
+        extra_subscribe_kwargs: dict[str, Any] = {},
+    ) -> None:
+        for handler_fn, topics_dict in self.node.bound_registry.items():
+            pub = topics_dict.get("publish_topic")
+            sub = topics_dict.get("subscribe_topic")
+            if sub is not None:
+                handler_fn = broker.subscriber(
+                    sub, max_workers=max_workers, group_id=group_id, **extra_subscribe_kwargs
+                )(handler_fn)
+            if pub is not None:
+                handler_fn = broker.publisher(pub, **extra_publish_kwargs)(handler_fn)
+
+
+ChatRunner: TypeAlias = NodeRunner
+ToolRunner: TypeAlias = NodeRunner
+AgentRouterRunner: TypeAlias = NodeRunner

calfkit/stores/__init__.py

@@ -0,0 +1,38 @@
+"""Calf Message History Store System.
+
+The message history store provides persistent storage for conversation messages
+in event-driven agent systems. It follows these principles:
+
+* Thread-based: Conversations are identified by a thread_id
+* Strong consistency: Messages are persisted atomically as they flow through the system
+* Pluggable backends: Swap between in-memory, PostgreSQL, Redis, etc.
+* Auto-create: New threads are created automatically on first append
+
+Example:
+    from calfkit.stores import MemoryMessageHistoryStore
+
+    # Deployment-time configuration
+    store = MemoryMessageHistoryStore()
+
+    # Inject into router node
+    router_node = AgentRouterNode(
+        chat_node=chat_node,
+        tool_nodes=[get_weather],
+        message_store=store,
+    )
+
+    # Invocation-time - specify which conversation
+    await router_node.invoke(
+        user_prompt="What's the weather?",
+        broker=broker,
+        thread_id="user-123-conv-456",
+    )
+"""
+
+from calfkit.stores.base import MessageHistoryStore
+from calfkit.stores.in_memory import InMemoryMessageHistoryStore
+
+__all__ = [
+    "MessageHistoryStore",
+    "InMemoryMessageHistoryStore",
+]

calfkit/stores/base.py

@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from pydantic_ai.messages import ModelMessage
+
+
+class MessageHistoryStore(ABC):
+    """Abstract store for conversation message history.
+
+    Designed for strong consistency in event-driven agent systems.
+    Messages are persisted atomically as they flow through the agent graph.
+    """
+
+    @abstractmethod
+    async def get(self, thread_id: str) -> list[ModelMessage]:
+        """Load message history for a thread.
+
+        Args:
+            thread_id: Unique identifier for the conversation thread.
+
+        Returns:
+            List of messages in the thread. Returns empty list if thread
+            doesn't exist (auto-create behavior).
+        """
+        ...
+
+    @abstractmethod
+    async def append(self, thread_id: str, message: ModelMessage) -> None:
+        """Append a single message to history.
+
+        This is the primary method for strong consistency - each message
+        is persisted immediately before the next step in the agentic loop.
+
+        Args:
+            thread_id: Unique identifier for the conversation thread.
+            message: The message to append.
+        """
+        ...
+
+    async def append_many(self, thread_id: str, messages: Sequence[ModelMessage]) -> None:
+        """Append multiple messages to history.
+
+        Default implementation calls append() for each message.
+        Override for batch optimization if needed.
+
+        Args:
+            thread_id: Unique identifier for the conversation thread.
+            messages: List of messages to append.
+        """
+        for message in messages:
+            await self.append(thread_id, message)
+
+    @abstractmethod
+    async def delete(self, thread_id: str) -> None:
+        """Delete all messages for a thread.
+
+        Args:
+            thread_id: Unique identifier for the conversation thread.
+        """
+        ...

calfkit/stores/in_memory.py

@@ -0,0 +1,29 @@
+from collections import defaultdict
+
+from pydantic_ai.messages import ModelMessage
+
+from calfkit.stores.base import MessageHistoryStore
+
+
+class InMemoryMessageHistoryStore(MessageHistoryStore):
+    """In-memory message history store.
+
+    Useful for testing and development. Not suitable for production
+    as data is lost when the process exits.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty in-memory store."""
+        self._messages: dict[str, list[ModelMessage]] = defaultdict(list)
+
+    async def get(self, thread_id: str) -> list[ModelMessage]:
+        """Load message history for a thread."""
+        return list(self._messages.get(thread_id, []))
+
+    async def append(self, thread_id: str, message: ModelMessage) -> None:
+        """Append a single message to history."""
+        self._messages[thread_id].append(message)
+
+    async def delete(self, thread_id: str) -> None:
+        """Delete all messages for a thread."""
+        self._messages.pop(thread_id, None)

calfkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: calfkit
+Version: 0.1.1
+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,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[cli]>=0.6.0
+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
+
+# Calf SDK
+
+Event-driven AI agents that scale like microservices. Build loosely-coupled, distributed agent systems where tools, chats, and workflows each run as independent services—communicating through events.
+
+## 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.
+
+## What Calf Gives You
+
+Calf 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.
+
+| Benefit | What It Means for You |
+|---------|----------------------|
+| **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
+```
+
+### Create and Run an Agent
+
+```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 ChatRunner, ToolRunner, AgentRouterRunner
+
+# 1. Define a tool
+@agent_tool
+def get_weather(location: str) -> str:
+    """Get the current weather at a location"""
+    return f"It's sunny in {location}"
+
+# 2. Setup broker and nodes
+async def main():
+    broker = Broker(bootstrap_servers="localhost:9092")
+    model_client = OpenAIModelClient(model_name="gpt-4o")
+
+    # Deploy chat node
+    chat_node = ChatNode(model_client)
+    ChatRunner(chat_node).register_on(broker)
+
+    # Deploy tool node
+    ToolRunner(get_weather).register_on(broker)
+
+    # Deploy router node
+    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)
+
+    # Run broker and invoke
+    await broker.run_app()
+    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.dist-info/RECORD

@@ -0,0 +1,28 @@
+calfkit/__init__.py,sha256=TNjZ-vfuYWSFldFQniKQvb0XRB55YzNqgLHyAKQcYrg,99
+calfkit/broker/__init__.py,sha256=35HCFxzWmmh0hhBf7bf7Ix7XPUJaS-GQjAKwDpZ-EnI,63
+calfkit/broker/broker.py,sha256=9s8RbkxItA5NcuQX6U7lXqaL2WYrQ8JIZAusD_YARxs,996
+calfkit/broker/deployable.py,sha256=mzvYllCbh4m3lMCdbMsVlOyQ2jTHlx92RYjkHgry1zQ,122
+calfkit/broker/middleware.py,sha256=X9Ta4gLYkivOTTNjLzDXNIJSwLPUOlojvz2SmxgIHco,458
+calfkit/experimental/rpc_worker.py,sha256=_FeUmcS4aFY4IRaz-qrMelFXCGNKdEySE0BSWTOzudE,1439
+calfkit/messages/__init__.py,sha256=4Wv45OrQMI0opPK70D1IyysbjxwdxJP4y56PkkEEtq0,309
+calfkit/messages/util.py,sha256=EamqjS74LlHRBzOgER5o2VWwQFkcxt9Kwtd6QE4pqNw,3295
+calfkit/models/event_envelope.py,sha256=zd10sQ51LgqxroZsxrm3kNkB5hWRtou73iLRdWeig6Y,1607
+calfkit/models/types.py,sha256=PQBJFeiwsoY5najanNkL6IymM3mZYv2voFQR9smcObs,1989
+calfkit/nodes/__init__.py,sha256=nWU-r76xj_cxQ9W6RXs5IDhvXAwsMDAVrx_ZuxRmLgI,457
+calfkit/nodes/agent_router_node.py,sha256=Zo1jApqLdnm2BPQD101Ay9UUVwSg2ADBRFti9V5Ts8A,7362
+calfkit/nodes/base_node.py,sha256=sEynWeQejGV-jmConBTY09fMIfTsnYnvtCIYZOp-vlk,2147
+calfkit/nodes/base_tool_node.py,sha256=t1epxURAkGiqSCcnmPp1f41TacF9mwYnuShngX_7hfQ,2000
+calfkit/nodes/chat_node.py,sha256=F3pBvJxiKcWNdviGtpYtWZFQn3ffc4Ka-mh8yIBw_PQ,1943
+calfkit/nodes/registrator.py,sha256=WJLiZ-aIJ8w9nFHNd0ya6pux4zKaZASDT6MIRCXLpa8,331
+calfkit/providers/__init__.py,sha256=NwS6wYfpJXledImfWVQKAgDsrNJAxzJYde3avdNiBDE,126
+calfkit/providers/pydantic_ai/__init__.py,sha256=5zVl-r7Cj7nQUnIQ41zSDzRYCKi8GwDgT-PXNw8M4OQ,100
+calfkit/providers/pydantic_ai/openai.py,sha256=8fKLvYpiqUzDOBrZxTdxtsB0tDhCUniv_N-FRFeBNvE,2604
+calfkit/runners/__init__.py,sha256=4CHTwdPpkFa-Z3vA1PR1S17F9phsaBRXs_SyFO-9Xgo,379
+calfkit/runners/node_runner.py,sha256=bJ8wk4gPADX2ctmyoXgslwGItOxG2fH2MKk3ORPtLNI,1411
+calfkit/stores/__init__.py,sha256=JIaqYv5OnddLdf3l3KO6ET2Wsd0sOGwxIFiUPRjKn_U,1167
+calfkit/stores/base.py,sha256=hPR0V2HAzrOGO5HNUfZSQ82YEoCKKHfY3EQVpHODpa0,1900
+calfkit/stores/in_memory.py,sha256=ZKGfPdLUxri8Q3otzVsWqaDYFYvDpBjYgWRDRoF2C70,1002
+calfkit-0.1.1.dist-info/METADATA,sha256=tG8BXjPadC5KFUz8vsLzEQYxzH0jxGKAe_5TYxs0WY4,5018
+calfkit-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+calfkit-0.1.1.dist-info/licenses/LICENSE,sha256=nSECZEo9kht4X50TajtlnrVg21bXN4PVs5mSi5ihAGs,11338
+calfkit-0.1.1.dist-info/RECORD,,

calfkit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any