calfkit 0.5.2__tar.gz → 0.5.4__tar.gz

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

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

{calfkit-0.5.2 → calfkit-0.5.4}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.4](https://github.com/calf-ai/calfkit-sdk/compare/v0.5.3...v0.5.4) (2026-06-06)
+
+
+### Features
+
+* agent-POV message-history projection for multi-agent channels ([#154](https://github.com/calf-ai/calfkit-sdk/issues/154)) ([#185](https://github.com/calf-ai/calfkit-sdk/issues/185)) ([86e69c5](https://github.com/calf-ai/calfkit-sdk/commit/86e69c5436369d088c8cf02122135adecda43759))
+
+## [0.5.3](https://github.com/calf-ai/calfkit-sdk/compare/v0.5.2...v0.5.3) (2026-06-06)
+
+
+### Features
+
+* CLI add `calfkit run` to run nodes without Worker boilerplate ([#181](https://github.com/calf-ai/calfkit-sdk/issues/181)) ([6c1e38e](https://github.com/calf-ai/calfkit-sdk/commit/6c1e38e006f1481016dc132e502fa4eeb734d9ef))
+
 ## [0.5.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.5.1...v0.5.2) (2026-06-06)
 
 

{calfkit-0.5.2 → calfkit-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.5.2
+Version: 0.5.4
 Summary: Build AI workflows and agents as fully-distributed and event-driven microservices.
 Project-URL: Homepage, https://github.com/calf-ai/calfkit-sdk
 Project-URL: Repository, https://github.com/calf-ai/calfkit-sdk
@@ -36,9 +36,11 @@ Requires-Dist: typing-inspection>=0.4.0
 Requires-Dist: uuid-utils>=0.14.0
 Provides-Extra: cli
 Requires-Dist: typer>=0.12; extra == 'cli'
+Requires-Dist: watchfiles>=0.21; extra == 'cli'
 Provides-Extra: dev
 Provides-Extra: mcp-codegen
 Requires-Dist: typer>=0.12; extra == 'mcp-codegen'
+Requires-Dist: watchfiles>=0.21; extra == 'mcp-codegen'
 Description-Content-Type: text/markdown
 
 # 🐮 Calfkit SDK
@@ -100,9 +102,11 @@ Calfkit is a Python SDK that builds event-stream agents out-the-box. You get the
 ### 1. Install
 
 ```bash
-pip install calfkit
+pip install "calfkit[cli]"
 ```
 
+The `[cli]` extra adds the `calfkit` command used below to run nodes during development. (The library itself is just `pip install calfkit`.)
+
 <br>
 
 ### 2. Start a Calfkit Broker
@@ -140,10 +144,11 @@ You will be provided a Calfkit broker API to deploy your agents instead of setti
 > created on first use. Most hardened/managed brokers have that **disabled**, in
 > which case producers and consumers silently stall on a missing topic. Calfkit
 > ships an **EXPERIMENTAL, opt-in** topic provisioner (off by default) for the
-> dev/CI case: `Client.connect("localhost:9092", provisioning=ProvisioningConfig(enabled=True))`.
-> It is a development convenience (`replication_factor=1`, no ACLs) — **review it
-> before production**, where topic creation is typically ops-governed. See
-> [`docs/topic-provisioning.md`](docs/topic-provisioning.md).
+> dev/CI case — pass `--provision` to `calfkit run` below (or
+> `Client.connect("localhost:9092", provisioning=ProvisioningConfig(enabled=True))`
+> in code). It is a development convenience (`replication_factor=1`, no ACLs) —
+> **review it before production**, where topic creation is typically ops-governed.
+> See [`docs/topic-provisioning.md`](docs/topic-provisioning.md).
 
 <br>
 
@@ -153,30 +158,19 @@ Define and deploy a tool as an independent service. Tools are not owned by or co
 
 ```python
 # weather_tool.py
-import asyncio
 from calfkit.nodes import agent_tool
-from calfkit.client import Client
-from calfkit.worker import Worker
 
 # Define a tool — the @agent_tool decorator turns any function into a deployable tool node
 @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():
-    client = Client.connect("localhost:9092")  # Connect to Kafka broker
-    worker = Worker(client, nodes=[get_weather])  # Initialize a worker with the tool node
-    await worker.run()  # (Blocking call) Deploy the service to start serving traffic
-
-if __name__ == "__main__":
-    asyncio.run(main())
 ```
 
-Run the file to deploy the tool service:
+Deploy the tool as a service. `calfkit run` points at a `module:attr` target and starts a worker for you — no `Client`/`Worker` wiring required:
 
 ```shell
-python weather_tool.py
+calfkit run weather_tool:get_weather
 ```
 
 <br>
@@ -187,11 +181,8 @@ Deploy the agent as its own service. The `Agent` handles LLM chat, tool orchestr
 
 ```python
 # agent_service.py
-import asyncio
 from calfkit.nodes import Agent
 from calfkit.providers import OpenAIResponsesModelClient
-from calfkit.client import Client
-from calfkit.worker import Worker
 from weather_tool import get_weather  # Import the tool definition (reusable)
 
 agent = Agent(
@@ -201,14 +192,6 @@ agent = Agent(
     model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-nano"),
     tools=[get_weather],  # Register tool definitions with the agent
 )
-
-async def main():
-    client = Client.connect("localhost:9092")  # Connect to Kafka broker
-    worker = Worker(client, nodes=[agent])  # Initialize a worker with the agent node
-    await worker.run()  # (Blocking call) Deploy the service to start serving traffic
-
-if __name__ == "__main__":
-    asyncio.run(main())
 ```
 
 Set your OpenAI API key:
@@ -217,10 +200,10 @@ Set your OpenAI API key:
 export OPENAI_API_KEY=sk-...
 ```
 
-Run the file to deploy the agent service:
+Deploy the agent as its own service (run it alongside the tool service from step 3):
 
 ```shell
-python agent_service.py
+calfkit run agent_service:agent
 ```
 
 <br>
@@ -240,7 +223,7 @@ async def main():
     # Send a request and await the response
     result = await client.execute_node(
         "What's the weather in Tokyo?",
-        "agent.input",  # The topic the agent subscribes to
+        "weather_agent.input",  # The topic the agent subscribes to
     )
     print(f"Assistant: {result.output}")
 
@@ -256,6 +239,34 @@ python invoke.py
 
 <br>
 
+### Deploying to production
+
+`calfkit run` is a **development** convenience — it imports your module and starts a worker for you (and `--reload` restarts it on edits). For production, deploy each node with an explicit `Worker` so startup, scaling, and topic governance stay under your control:
+
+```python
+# serve_tool.py — deploy the tool as its own service
+import asyncio
+from calfkit.client import Client
+from calfkit.worker import Worker
+from weather_tool import get_weather
+
+async def main():
+    client = Client.connect("localhost:9092")  # Connect to Kafka broker
+    worker = Worker(client, nodes=[get_weather])  # One service per node
+    await worker.run()  # (Blocking) serve until stopped
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+```shell
+python serve_tool.py
+```
+
+See the **[CLI reference](docs/cli.md)** for every `calfkit run` flag (`--host`, `--provision`, `--reload`, `--app-dir`, …) and the other `calfkit` commands (`mcp`, `topics`).
+
+<br>
+
 ### Structured Outputs (Optional)
 
 Agents can be deployed with a `final_output_type` to enforce structured output from the LLM. The output is type-safe and deserialized automatically on the client side.
@@ -310,6 +321,8 @@ result = await client.execute_node(
 )
 ```
 
+The same `message_history` can carry turns from *multiple* agents — see [`examples/multi_agent_panel/`](examples/multi_agent_panel/) for a multi-agent discussion over one shared transcript.
+
 **Runtime dependency injection** — pass runtime data to tools via the `deps` parameter:
 
 ```python
@@ -468,7 +481,11 @@ See [`docs/mcp-overview.md`](docs/mcp-overview.md) for the quickstart, deploymen
 
 ## Documentation
 
-Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.
+Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit. Deeper guides live in [`docs/`](docs/):
+
+- [CLI reference](docs/cli.md) — `calfkit run`, `mcp`, and `topics` commands
+- [MCP adaptor](docs/mcp-overview.md) — expose MCP servers as calfkit tools
+- [Topic provisioning](docs/topic-provisioning.md) — experimental dev topic auto-creation
 
 Deep-dive guides:
 

{calfkit-0.5.2 → calfkit-0.5.4}/README.md

@@ -57,9 +57,11 @@ Calfkit is a Python SDK that builds event-stream agents out-the-box. You get the
 ### 1. Install
 
 ```bash
-pip install calfkit
+pip install "calfkit[cli]"
 ```
 
+The `[cli]` extra adds the `calfkit` command used below to run nodes during development. (The library itself is just `pip install calfkit`.)
+
 <br>
 
 ### 2. Start a Calfkit Broker
@@ -97,10 +99,11 @@ You will be provided a Calfkit broker API to deploy your agents instead of setti
 > created on first use. Most hardened/managed brokers have that **disabled**, in
 > which case producers and consumers silently stall on a missing topic. Calfkit
 > ships an **EXPERIMENTAL, opt-in** topic provisioner (off by default) for the
-> dev/CI case: `Client.connect("localhost:9092", provisioning=ProvisioningConfig(enabled=True))`.
-> It is a development convenience (`replication_factor=1`, no ACLs) — **review it
-> before production**, where topic creation is typically ops-governed. See
-> [`docs/topic-provisioning.md`](docs/topic-provisioning.md).
+> dev/CI case — pass `--provision` to `calfkit run` below (or
+> `Client.connect("localhost:9092", provisioning=ProvisioningConfig(enabled=True))`
+> in code). It is a development convenience (`replication_factor=1`, no ACLs) —
+> **review it before production**, where topic creation is typically ops-governed.
+> See [`docs/topic-provisioning.md`](docs/topic-provisioning.md).
 
 <br>
 
@@ -110,30 +113,19 @@ Define and deploy a tool as an independent service. Tools are not owned by or co
 
 ```python
 # weather_tool.py
-import asyncio
 from calfkit.nodes import agent_tool
-from calfkit.client import Client
-from calfkit.worker import Worker
 
 # Define a tool — the @agent_tool decorator turns any function into a deployable tool node
 @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():
-    client = Client.connect("localhost:9092")  # Connect to Kafka broker
-    worker = Worker(client, nodes=[get_weather])  # Initialize a worker with the tool node
-    await worker.run()  # (Blocking call) Deploy the service to start serving traffic
-
-if __name__ == "__main__":
-    asyncio.run(main())
 ```
 
-Run the file to deploy the tool service:
+Deploy the tool as a service. `calfkit run` points at a `module:attr` target and starts a worker for you — no `Client`/`Worker` wiring required:
 
 ```shell
-python weather_tool.py
+calfkit run weather_tool:get_weather
 ```
 
 <br>
@@ -144,11 +136,8 @@ Deploy the agent as its own service. The `Agent` handles LLM chat, tool orchestr
 
 ```python
 # agent_service.py
-import asyncio
 from calfkit.nodes import Agent
 from calfkit.providers import OpenAIResponsesModelClient
-from calfkit.client import Client
-from calfkit.worker import Worker
 from weather_tool import get_weather  # Import the tool definition (reusable)
 
 agent = Agent(
@@ -158,14 +147,6 @@ agent = Agent(
     model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-nano"),
     tools=[get_weather],  # Register tool definitions with the agent
 )
-
-async def main():
-    client = Client.connect("localhost:9092")  # Connect to Kafka broker
-    worker = Worker(client, nodes=[agent])  # Initialize a worker with the agent node
-    await worker.run()  # (Blocking call) Deploy the service to start serving traffic
-
-if __name__ == "__main__":
-    asyncio.run(main())
 ```
 
 Set your OpenAI API key:
@@ -174,10 +155,10 @@ Set your OpenAI API key:
 export OPENAI_API_KEY=sk-...
 ```
 
-Run the file to deploy the agent service:
+Deploy the agent as its own service (run it alongside the tool service from step 3):
 
 ```shell
-python agent_service.py
+calfkit run agent_service:agent
 ```
 
 <br>
@@ -197,7 +178,7 @@ async def main():
     # Send a request and await the response
     result = await client.execute_node(
         "What's the weather in Tokyo?",
-        "agent.input",  # The topic the agent subscribes to
+        "weather_agent.input",  # The topic the agent subscribes to
     )
     print(f"Assistant: {result.output}")
 
@@ -213,6 +194,34 @@ python invoke.py
 
 <br>
 
+### Deploying to production
+
+`calfkit run` is a **development** convenience — it imports your module and starts a worker for you (and `--reload` restarts it on edits). For production, deploy each node with an explicit `Worker` so startup, scaling, and topic governance stay under your control:
+
+```python
+# serve_tool.py — deploy the tool as its own service
+import asyncio
+from calfkit.client import Client
+from calfkit.worker import Worker
+from weather_tool import get_weather
+
+async def main():
+    client = Client.connect("localhost:9092")  # Connect to Kafka broker
+    worker = Worker(client, nodes=[get_weather])  # One service per node
+    await worker.run()  # (Blocking) serve until stopped
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+```shell
+python serve_tool.py
+```
+
+See the **[CLI reference](docs/cli.md)** for every `calfkit run` flag (`--host`, `--provision`, `--reload`, `--app-dir`, …) and the other `calfkit` commands (`mcp`, `topics`).
+
+<br>
+
 ### Structured Outputs (Optional)
 
 Agents can be deployed with a `final_output_type` to enforce structured output from the LLM. The output is type-safe and deserialized automatically on the client side.
@@ -267,6 +276,8 @@ result = await client.execute_node(
 )
 ```
 
+The same `message_history` can carry turns from *multiple* agents — see [`examples/multi_agent_panel/`](examples/multi_agent_panel/) for a multi-agent discussion over one shared transcript.
+
 **Runtime dependency injection** — pass runtime data to tools via the `deps` parameter:
 
 ```python
@@ -425,7 +436,11 @@ See [`docs/mcp-overview.md`](docs/mcp-overview.md) for the quickstart, deploymen
 
 ## Documentation
 
-Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.
+Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit. Deeper guides live in [`docs/`](docs/):
+
+- [CLI reference](docs/cli.md) — `calfkit run`, `mcp`, and `topics` commands
+- [MCP adaptor](docs/mcp-overview.md) — expose MCP servers as calfkit tools
+- [Topic provisioning](docs/topic-provisioning.md) — experimental dev topic auto-creation
 
 Deep-dive guides:
 

{calfkit-0.5.2 → calfkit-0.5.4}/ROADMAP.md

@@ -7,6 +7,7 @@ An index of potential features and changes under consideration for Calf SDK. Eac
 - [Deps-as-dict refactor](docs/deps-as-dict-refactor.md) — `ctx.deps`/`result.deps` are plain dicts and `correlation_id` is a top-level context attribute (closes #144; breaking)
 - [Fire-and-forget emit](docs/fire-and-forget-emit.md) — true one-way Client.emit_to_node; nullable callback terminal; opt-in reply TTL (closes #132)
 - [Topic Provisioning](docs/topic-provisioning.md) — EXPERIMENTAL opt-in `ProvisioningConfig` to best-effort create Kafka topics for dev/CI (off by default; review for prod)
+- [Agent-POV History Projection](docs/agent-pov-projection.md) — always-on POV projection over `message_history` + `ModelResponse.name` stamping for shared-channel multi-agent; portable content-prefix attribution (PR #185; closes #154)
 
 ## Proposed
 

{calfkit-0.5.2 → calfkit-0.5.4}/calfkit/cli/__init__.py

@@ -1,8 +1,9 @@
 """calfkit top-level CLI entry point.
 
 Mounts subcommands as typer sub-apps: ``mcp`` (with ``mcp codegen`` /
-``mcp schema``) and ``topics`` (with ``topics provision``). Future
-subcommands land alongside via the same mounting pattern.
+``mcp schema``) and ``topics`` (with ``topics provision``), plus the
+top-level ``run`` command. Future subcommands land alongside via the same
+mounting pattern.
 
 Invoked via the ``calfkit`` console script registered in pyproject.toml's
 ``[project.scripts]``.
@@ -27,11 +28,13 @@ def _build_app() -> Any:
         raise SystemExit("The calfkit CLI requires the 'cli' optional extra. Install with: pip install calfkit[cli]") from e
 
     from calfkit.cli.mcp import app as mcp_app
+    from calfkit.cli.run import run as run_command
     from calfkit.cli.topics import app as topics_app
 
     app = typer.Typer(name="calfkit", help="Calfkit SDK command-line tools.", no_args_is_help=True)
     app.add_typer(mcp_app, name="mcp")
     app.add_typer(topics_app, name="topics")
+    app.command(name="run")(run_command)
     return app
 
 

calfkit-0.5.4/calfkit/cli/_loader.py

@@ -0,0 +1,165 @@
+"""Shared node loader for the calfkit CLI.
+
+Resolves ``module:attr`` specs into a flat list of node objects. Used by both
+``calfkit topics provision`` (``--nodes module:attr``) and ``calfkit run``
+(positional ``module:attr`` targets).
+
+Each ``attr`` may resolve to a single node or an iterable of nodes; iterables
+are expanded. ``McpServer`` instances are treated as scalars even though they
+are iterable (their ``__iter__`` yields tool defs) so a directly-resolved MCP
+server is preserved rather than splatted.
+
+Requires the ``cli`` optional extra (typer). If typer is not installed, the
+import raises with a clear remediation message rather than silently failing.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from collections.abc import Iterable
+from typing import Any
+
+try:
+    import typer
+except ImportError as e:  # pragma: no cover -- exercised manually
+    raise ImportError("the calfkit CLI requires the 'cli' optional extra. Install with: pip install calfkit[cli]") from e
+
+
+def resolve_specs(specs: list[str], *, app_dir: str | None = None, source_label: str = "target") -> list[Any]:
+    """Resolve ``module:attr`` specs into a flat list of resolved objects.
+
+    Each ``attr`` may be a single object or an iterable of objects; iterables
+    (other than ``str``/``bytes`` and ``McpServer``) are expanded. Results are
+    concatenated in the order the specs were supplied.
+
+    Args:
+        specs: ``module:attr`` strings.
+        app_dir: Optional directory inserted at ``sys.path[0]`` before importing
+            so targets are resolvable relative to it (e.g. the project root the
+            user runs the command from). The path is absolutised; duplicates are
+            not re-inserted.
+        source_label: How to name the spec source in error messages (e.g.
+            ``"target"`` for ``calfkit run`` or ``"--nodes"`` for
+            ``calfkit topics provision``).
+
+    Raises:
+        typer.Exit: (code 2) on a malformed spec, an import failure, or a
+            missing attribute.
+    """
+    from calfkit.mcp._server import McpServer
+
+    if app_dir is not None:
+        abs_dir = os.path.abspath(app_dir)
+        if abs_dir not in sys.path:
+            sys.path.insert(0, abs_dir)
+
+    resolved: list[Any] = []
+    for spec in specs:
+        module_path, sep, attr = spec.partition(":")
+        if not sep or not module_path or not attr:
+            typer.echo(
+                f"Error: {source_label} must be in 'module:attr' form, got {spec!r}.",
+                err=True,
+            )
+            raise typer.Exit(2)
+        try:
+            module = importlib.import_module(module_path)
+        except (ModuleNotFoundError, ImportError) as e:
+            # The module (or one of its imports) does not exist / cannot load.
+            typer.echo(f"Error: cannot import module {module_path!r}: {e}", err=True)
+            raise typer.Exit(2) from e
+        except Exception as e:  # noqa: BLE001 -- side-effect code at import time failed
+            # The module exists but its top-level code raised when executed.
+            typer.echo(
+                f"Error: module {module_path!r} raised during import (side-effect code failed): {e}",
+                err=True,
+            )
+            raise typer.Exit(2) from e
+        try:
+            obj = getattr(module, attr)
+        except AttributeError as e:
+            typer.echo(f"Error: module {module_path!r} has no attribute {attr!r}.", err=True)
+            raise typer.Exit(2) from e
+
+        # A single node has ``subscribe_topics`` but is not itself a plain
+        # iterable of nodes. Strings/bytes are iterable too; an McpServer is
+        # iterable (its ``__iter__`` yields tool defs) but must be kept whole.
+        # Treat all three as scalars; expand everything else iterable.
+        if isinstance(obj, (str, bytes, McpServer)) or not isinstance(obj, Iterable):
+            resolved.append(obj)
+        else:
+            resolved.extend(obj)
+    return resolved
+
+
+def validate_nodes(objs: list[Any], *, source_label: str = "target") -> None:
+    """Ensure every object is a node or an ``McpServer``.
+
+    A node is duck-typed by the attributes the worker wiring relies on
+    (``subscribe_topics`` and ``_return_topic``). ``McpServer`` instances are
+    allowed through unconditionally — the worker expands them into per-tool
+    bridges at startup.
+
+    Args:
+        objs: Resolved objects to validate.
+        source_label: How to name the spec source in error messages.
+
+    Raises:
+        typer.Exit: (code 2) if any object is neither a node nor an McpServer.
+    """
+    from calfkit.mcp._server import McpServer
+
+    for obj in objs:
+        if isinstance(obj, McpServer):
+            continue
+        missing = [attr for attr in ("subscribe_topics", "_return_topic") if not hasattr(obj, attr)]
+        if missing:
+            typer.echo(
+                f"Error: resolved object {obj!r} is not a node "
+                f"(missing {', '.join(missing)}). {source_label} must point at a "
+                "BaseNodeDef or McpServer (or an iterable of them).",
+                err=True,
+            )
+            raise typer.Exit(2)
+
+
+def load_nodes(targets: list[str], *, app_dir: str | None = None, source_label: str = "target") -> list[Any]:
+    """Resolve, validate, and de-duplicate ``targets`` into a non-empty node list.
+
+    The composition used by ``calfkit run`` for both the inline (no-reload) path
+    and the parent-side pre-flight before the reload supervisor starts. Raising
+    on an empty result means a misconfigured run fails fast and loud (exit 2)
+    instead of starting an idle worker.
+
+    Raises:
+        typer.Exit: (code 2) on a bad spec, import failure, non-node object, or
+            if ``targets`` resolve to zero nodes.
+    """
+    objs = resolve_specs(targets, app_dir=app_dir, source_label=source_label)
+    validate_nodes(objs, source_label=source_label)
+    nodes = dedupe_by_node_id(objs)
+    if not nodes:
+        typer.echo("Error: no nodes resolved from the given target(s).", err=True)
+        raise typer.Exit(2)
+    return nodes
+
+
+def dedupe_by_node_id(objs: list[Any]) -> list[Any]:
+    """Drop duplicate nodes by ``node_id``, preserving first-seen order.
+
+    Objects without a ``node_id`` (e.g. ``McpServer``) are keyed by identity so
+    they are always retained.
+    """
+    seen: set[Any] = set()
+    out: list[Any] = []
+    for obj in objs:
+        key = getattr(obj, "node_id", None)
+        if key is None:
+            key = id(obj)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(obj)
+    return out