dispatch_agents 0.13.3__tar.gz → 0.14.2__tar.gz

{dispatch_agents-0.13.3 → dispatch_agents-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dispatch_agents
-Version: 0.13.3
+Version: 0.14.2
 Summary: Dispatch Agents SDK
 License-File: LICENSE
 License-File: LICENSE-3rdparty.csv

dispatch_agents-0.14.2/README.md

@@ -0,0 +1,182 @@
+# Dispatch Agents SDK
+
+Build and deploy event-driven AI agents with simple Python decorators.
+[dispatchagents.ai](https://dispatchagents.ai/) — currently in public preview.
+
+## Installation
+
+```bash
+uv add git+ssh://git@github.com/datadog-labs/dispatch_agents_sdk.git@vX.Y.Z
+```
+
+Replace `vX.Y.Z` with the latest tag:
+
+```bash
+git ls-remote --tags git@github.com:datadog-labs/dispatch_agents_sdk.git 'v*' \
+  | sort -t'/' -k3 -V | tail -1 | awk -F'/' '{print $3}'
+```
+
+## Core Concepts
+
+### `@on` — Subscribe to events
+
+Handle events published to a topic. The payload is automatically validated
+against your Pydantic model before your handler is called.
+
+```python
+from dispatch_agents import BasePayload, on
+
+class OrderPayload(BasePayload):
+    order_id: str
+    customer_email: str
+
+class OrderResult(BasePayload):
+    status: str
+
+@on(topic="orders.process")
+async def process_order(payload: OrderPayload) -> OrderResult:
+    await send_confirmation(payload.customer_email, payload.order_id)
+    return OrderResult(status="confirmed")
+```
+
+Subscribe to GitHub events by passing a GitHub event class:
+
+```python
+from dispatch_agents import on
+from dispatch_agents.integrations.github.events import PullRequestOpened
+
+@on(github_event=PullRequestOpened)
+async def handle_pr(payload: PullRequestOpened) -> None:
+    print(f"PR opened: {payload.pull_request.title}")
+```
+
+### `@fn` — Expose a callable function
+
+Register a function that other agents can call directly by name using `invoke()`.
+
+```python
+from dispatch_agents import BasePayload, fn
+
+class WeatherRequest(BasePayload):
+    city: str
+
+class WeatherResponse(BasePayload):
+    temperature: float
+    conditions: str
+
+@fn()
+async def get_weather(request: WeatherRequest) -> WeatherResponse:
+    data = await fetch_weather_api(request.city)
+    return WeatherResponse(temperature=data["temp"], conditions=data["sky"])
+```
+
+### `@init` — One-time async setup
+
+Runs once before any events are processed. Use for connecting to databases,
+loading models, or initializing shared state.
+
+```python
+from dispatch_agents import BasePayload, init, on
+
+_client = None
+
+@init
+async def setup():
+    global _client
+    _client = await connect_to_database()
+
+class QueryPayload(BasePayload):
+    user_id: str
+
+@on(topic="users.query")
+async def query_users(payload: QueryPayload) -> QueryResult:
+    rows = await _client.fetch(
+        "select * from users where id = $1",
+        payload.user_id,
+    )
+    return QueryResult(rows=rows)
+```
+
+### `emit_event` — Fire-and-forget publishing
+
+Publish an event without waiting for handlers to process it.
+
+```python
+from dispatch_agents import emit_event, on
+
+@on(topic="orders.process")
+async def process_order(payload: OrderPayload) -> OrderResult:
+    await fulfill(payload)
+    # Notify other agents — returns immediately
+    await emit_event("notifications.send", {"email": payload.customer_email})
+    return OrderResult(status="fulfilled")
+```
+
+### `invoke` — Call another agent directly
+
+Call a `@fn`-decorated function on another agent and wait for the result.
+
+```python
+from dispatch_agents import invoke, on
+
+@on(topic="reports.request")
+async def handle_report(payload: ReportPayload) -> ReportResult:
+    weather = await invoke(
+        agent_name="weather-service",
+        function_name="get_weather",
+        payload={"city": payload.city},
+        response_model=WeatherResponse,
+        timeout=30.0,
+    )
+    return ReportResult(weather=weather.conditions)
+```
+
+## Error Handling
+
+- **`OSError` and subclasses** → automatic retry with exponential backoff
+- **`ValueError` and subclasses** → terminal failure, not retried
+
+```python
+from dispatch_agents import on
+
+@on(topic="data.fetch")
+async def fetch(payload: FetchPayload) -> FetchResult:
+    if not payload.url.startswith("https://"):
+        raise ValueError("Only HTTPS URLs allowed")  # not retried
+
+    # TimeoutError (an OSError subclass) will be retried automatically
+    response = await httpx_client.get(payload.url, timeout=10.0)
+    return FetchResult(data=response.json())
+```
+
+## Payloads
+
+All handler inputs and outputs must inherit from `BasePayload`:
+
+```python
+from dispatch_agents import BasePayload
+from typing import Optional
+
+class TaskPayload(BasePayload):
+    task_id: str
+    priority: int = 1
+    tags: list[str] = []
+    metadata: Optional[dict[str, str]] = None
+```
+
+## Examples
+
+- [`hello_world`](../examples/hello_world/) — typed payloads, error handling, persistent storage
+- [`weather-service`](../examples/weather-service/) + [`weather-assistant`](../examples/weather-assistant/) — inter-agent `invoke()`
+- [`conversational-agent`](../examples/conversational-agent/) — multi-turn LLM chat with memory
+- [`daily-digest`](../examples/daily-digest/) — scheduled agents
+- [`deep-research`](../examples/deep-research/) — parallel supervisor/researcher pattern
+- [`multi-framework`](../examples/multi-framework/) — Claude SDK, OpenAI Agents, LangGraph
+
+## Full Documentation
+
+[dispatchagents.ai/docs/sdk](https://dispatchagents.ai/docs/sdk)
+
+## Support
+
+GitHub Issues: [github.com/datadog-labs/dispatch_agents_sdk/issues](https://github.com/datadog-labs/dispatch_agents_sdk/issues)

dispatch_agents-0.14.2/RELEASE_NOTES.md

@@ -0,0 +1,2 @@
+## Features
+- The logging configuration module is now publicly accessible as `dispatch_agents.logging`, allowing users to directly import and use logging utilities from the top-level package.

dispatch_agents-0.14.2/dispatch_agents/__init__.py

@@ -0,0 +1,58 @@
+"""Dispatch Agents Python SDK.
+
+The root package re-exports the most common agent APIs for convenience:
+
+* ``on``, ``fn``, and ``init`` from :mod:`dispatch_agents.handlers`
+* ``emit_event`` from :mod:`dispatch_agents.events`
+* ``invoke`` from :mod:`dispatch_agents.invocation`
+* ``get_data_dir`` from :mod:`dispatch_agents.storage`
+* ``get_mcp_client`` and ``get_mcp_servers_config`` from :mod:`dispatch_agents.mcp`
+* ``config``, ``memory``, ``llm``, ``context``, and ``models`` as public modules
+
+For canonical API ownership, browse the public submodules below.
+Deprecated compatibility aliases from earlier SDK versions remain importable
+from the root package, but new code should import them from their canonical
+public submodules.
+"""
+
+from __future__ import annotations
+
+from ._deprecated_public_api import install_deprecated_public_aliases
+from ._internal.bootstrap import install_proto_import_path
+from ._internal.dev import install_dev_mode_audit_hook
+
+install_proto_import_path()
+
+from . import context, llm, models
+from .config import config
+from .events import emit_event
+from .handlers import fn, init, on
+from .invocation import invoke
+from .llm import extra_headers
+from .mcp import get_mcp_client, get_mcp_servers_config
+from .memory import memory
+from .models import BasePayload, McpHttpServerConfig
+from .storage import DisallowedWriteError, get_data_dir
+
+__all__ = [
+    "BasePayload",
+    "config",
+    "context",
+    "DisallowedWriteError",
+    "emit_event",
+    "extra_headers",
+    "fn",
+    "get_data_dir",
+    "get_mcp_client",
+    "get_mcp_servers_config",
+    "init",
+    "invoke",
+    "llm",
+    "McpHttpServerConfig",
+    "memory",
+    "models",
+    "on",
+]
+
+install_deprecated_public_aliases()
+install_dev_mode_audit_hook()

dispatch_agents-0.14.2/dispatch_agents/_deprecated_public_api.py

@@ -0,0 +1,132 @@
+"""Deprecated public compatibility aliases.
+
+This module is the single cleanup point for old public import paths that still
+have a current public owner. Do not add aliases that point to ``_internal``.
+"""
+
+from __future__ import annotations
+
+import warnings
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+AliasTargets = dict[str, str]
+
+_STATIC_ALIASES: dict[str, AliasTargets] = {
+    "dispatch_agents": {
+        "HandlerMetadata": "dispatch_agents.models",
+        "InvocationStatus": "dispatch_agents.models",
+        "KVGetResponse": "dispatch_agents.models",
+        "KVListResponse": "dispatch_agents.models",
+        "KVMemoryRecord": "dispatch_agents.models",
+        "LLMFunctionCall": "dispatch_agents.models",
+        "LLMToolCall": "dispatch_agents.models",
+        "MemoryClient": "dispatch_agents.memory",
+        "MemoryWriteResponse": "dispatch_agents.models",
+        "SessionGetResponse": "dispatch_agents.models",
+        "get_extra_llm_headers": "dispatch_agents.llm",
+        "get_handler_metadata": "dispatch_agents.handlers",
+        "get_handler_schemas": "dispatch_agents.handlers",
+    },
+    "dispatch_agents.config": {
+        "DispatchConfig": "dispatch_agents.models",
+        "DomainSelector": "dispatch_agents.models",
+        "EgressConfig": "dispatch_agents.models",
+        "MCPServerConfig": "dispatch_agents.models",
+        "NetworkConfig": "dispatch_agents.models",
+        "ResourceConfig": "dispatch_agents.models",
+        "ResourceLimits": "dispatch_agents.models",
+        "SecretConfig": "dispatch_agents.models",
+        "VolumeConfig": "dispatch_agents.models",
+        "VolumeMode": "dispatch_agents.models",
+    },
+    "dispatch_agents.events": {
+        "BasePayload": "dispatch_agents.models",
+        "HandlerMetadata": "dispatch_agents.models",
+        "fn": "dispatch_agents.handlers",
+        "get_handler_metadata": "dispatch_agents.handlers",
+        "get_handler_schemas": "dispatch_agents.handlers",
+        "init": "dispatch_agents.handlers",
+        "invoke": "dispatch_agents.invocation",
+        "on": "dispatch_agents.handlers",
+    },
+    "dispatch_agents.integrations.github.client": {
+        "GitHubAppToken": "dispatch_agents.models",
+    },
+    "dispatch_agents.invocation": {
+        "InvocationStatus": "dispatch_agents.models",
+    },
+    "dispatch_agents.llm": {
+        "LLMFunctionCall": "dispatch_agents.models",
+        "LLMMessage": "dispatch_agents.models",
+        "LLMResponse": "dispatch_agents.models",
+        "LLMToolCall": "dispatch_agents.models",
+    },
+    "dispatch_agents.mcp": {
+        "McpHttpServerConfig": "dispatch_agents.models",
+    },
+    "dispatch_agents.memory": {
+        "KVGetResponse": "dispatch_agents.models",
+        "KVListResponse": "dispatch_agents.models",
+        "MemoryWriteResponse": "dispatch_agents.models",
+        "SessionGetResponse": "dispatch_agents.models",
+    },
+}
+
+
+# Alias maps keyed by module name, populated by ``install_deprecated_public_aliases``.
+# Held here rather than as a dynamic attribute on each patched module so the lookup
+# stays fully typed (``ModuleType`` has no such attribute slot).
+_INSTALLED_ALIASES: dict[str, AliasTargets] = {}
+
+
+class _DeprecatedAliasModule(ModuleType):
+    def __getattribute__(self, name: str) -> object:
+        module_name = ModuleType.__getattribute__(self, "__name__")
+        target_module = _INSTALLED_ALIASES.get(module_name, {}).get(name)
+        if target_module is not None:
+            return _resolve_deprecated_alias(module_name, name, target_module)
+        return ModuleType.__getattribute__(self, name)
+
+
+def install_deprecated_public_aliases() -> None:
+    """Install all deprecated public import aliases."""
+    for module_name, aliases in _all_aliases().items():
+        module = import_module(module_name)
+        _INSTALLED_ALIASES[module_name] = dict(aliases)
+        module.__class__ = _DeprecatedAliasModule
+        _extend_all(module, aliases)
+
+
+def _all_aliases() -> dict[str, AliasTargets]:
+    aliases = {module: dict(names) for module, names in _STATIC_ALIASES.items()}
+    github_events = import_module("dispatch_agents.integrations.github.events")
+    aliases["dispatch_agents.integrations.github"] = {
+        name: "dispatch_agents.integrations.github.events"
+        for name in github_events.__all__
+        if name != "GitHubAppToken"
+    }
+    return aliases
+
+
+def _resolve_deprecated_alias(
+    module_name: str,
+    name: str,
+    target_module: str,
+) -> Any:
+    warnings.warn(
+        f"{module_name}.{name} is deprecated; use {target_module}.{name} instead.",
+        FutureWarning,
+        stacklevel=3,
+    )
+    return getattr(import_module(target_module), name)
+
+
+def _extend_all(module: ModuleType, aliases: AliasTargets) -> None:
+    all_names = getattr(module, "__all__", None)
+    if not isinstance(all_names, list):
+        return
+    for name in aliases:
+        if name not in all_names:
+            all_names.append(name)

dispatch_agents-0.14.2/dispatch_agents/_internal/__init__.py

@@ -0,0 +1,16 @@
+"""Internal implementation packages for Dispatch Agents.
+
+Anything under this package is private to the SDK implementation and carries no
+backwards-compatibility guarantee. The public surface is the top-level
+``dispatch_agents`` package and its documented modules.
+
+Import policy:
+
+- First-party packages in this monorepo (``backend``, ``cli``) MAY import from
+  ``dispatch_agents._internal``. They version-lock with the SDK and share its
+  internal wire/orchestration contracts; this coupling is deliberate, not a leak.
+- External agent code MUST NOT import from ``_internal``. Use the public surface
+  (``dispatch_agents`` and ``dispatch_agents.models``). The ``examples/`` agents
+  serve as the proxy for external usage and are guarded by a test that forbids
+  any ``_internal`` import there.
+"""

{dispatch_agents-0.13.3/dispatch_agents → dispatch_agents-0.14.2/dispatch_agents/_internal}/agent_service.py

@@ -10,10 +10,6 @@ from agentservice.v1 import (
     service_pb2_grpc,
 )
 
-__all__ = [
-    "AgentServiceClient",
-]
-
 
 class AgentServiceClient:
     """Async gRPC client for the AgentService.

dispatch_agents-0.14.2/dispatch_agents/_internal/bootstrap.py

@@ -0,0 +1,11 @@
+"""SDK import-time bootstrap helpers."""
+
+import sys
+from pathlib import Path
+
+
+def install_proto_import_path() -> None:
+    """Add the SDK root so generated protobuf packages can be imported."""
+    sdk_root = str(Path(__file__).parents[2])
+    if sdk_root not in sys.path:
+        sys.path.insert(0, sdk_root)