deepcrew-ai 0.1.0__py3-none-any.whl

deepcrew/__init__.py

@@ -0,0 +1,88 @@
+"""
+deepcrew-ai — Multi-agent spawning library.
+
+Quick start::
+
+    from deepcrew import Agent, run_agent, Orchestrator, WorkflowBuilder, tool
+    from deepcrew.mcp import StdioMCP, SSEMCP, HTTPMCP, MCPManager
+
+Single agent::
+
+    agent = Agent(name="assistant", model="openai/gpt-4o",
+                  system_prompt="You are helpful.")
+    result = await run_agent(agent, [{"role": "user", "content": "Hello!"}])
+    print(result.text)
+
+Automated orchestration (router → parallel agents → synthesizer)::
+
+    orch = Orchestrator(
+        agents=[researcher, analyst, writer],
+        router_model="openai/gpt-4o-mini",
+        synthesizer_model="openai/gpt-4o",
+    )
+    result = await orch.run("Explain quantum entanglement")
+
+DAG workflow::
+
+    workflow = (
+        WorkflowBuilder()
+        .add_agent("research", researcher, task="{input}")
+        .add_agent("write", writer, task="Write about:\\n{research}")
+        .then("research", "write")
+    )
+    result = await workflow.run("Quantum computing trends")
+"""
+
+from .agent import Agent
+from .exceptions import (
+    DeepCrewError,
+    MCPError,
+    MaxTurnsError,
+    RouterError,
+    ToolError,
+    WorkflowError,
+)
+from .orchestrator import Orchestrator
+from .runner import run_agent
+from .stream import make_done_event, make_error_event, queue_to_stream
+from .tools import fn_to_tool_def, tool
+from .types import (
+    AgentResult,
+    EventType,
+    OrchestratorResult,
+    StreamEvent,
+    ToolDef,
+    WorkflowResult,
+)
+from .workflow import WorkflowBuilder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Agent",
+    "run_agent",
+    "Orchestrator",
+    "WorkflowBuilder",
+    # Tools
+    "tool",
+    "fn_to_tool_def",
+    # Types
+    "StreamEvent",
+    "EventType",
+    "AgentResult",
+    "WorkflowResult",
+    "OrchestratorResult",
+    "ToolDef",
+    # Streaming
+    "queue_to_stream",
+    "make_done_event",
+    "make_error_event",
+    # Exceptions
+    "DeepCrewError",
+    "MCPError",
+    "ToolError",
+    "MaxTurnsError",
+    "RouterError",
+    "WorkflowError",
+]

deepcrew/agent.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+from .tools import fn_to_tool_def
+from .types import ToolDef
+
+if TYPE_CHECKING:
+    from .mcp.base import MCPClient
+
+
+@dataclass
+class Agent:
+    """
+    Defines a single AI agent: model, system prompt, and its tools.
+
+    Parameters
+    ----------
+    name:
+        Unique identifier used in logs and result objects.
+    model:
+        LiteLLM model string, e.g. ``"openai/gpt-4o"``,
+        ``"anthropic/claude-opus-4-8"``, ``"gemini/gemini-2.0-flash"``.
+    system_prompt:
+        The agent's system/instruction prompt.
+    mcps:
+        MCP clients (StdioMCP, SSEMCP, or HTTPMCP) whose tools this agent
+        can use.
+    tools:
+        Plain Python callables decorated with @tool (or undecorated).
+        Schemas are auto-generated from type hints.
+    max_turns:
+        Maximum LLM→tool→LLM cycles before raising MaxTurnsError.
+    temperature:
+        Sampling temperature forwarded to the LLM. None uses provider default.
+    max_tokens:
+        Maximum output tokens. None uses provider default.
+    extra_params:
+        Any additional kwargs forwarded verbatim to ``litellm.acompletion``.
+    """
+
+    name: str
+    model: str
+    system_prompt: str = ""
+    mcps: list[MCPClient] = field(default_factory=list)
+    tools: list[Callable[..., Any]] = field(default_factory=list)
+    max_turns: int = 10
+    temperature: float | None = None
+    max_tokens: int | None = None
+    extra_params: dict[str, Any] = field(default_factory=dict)
+
+    async def get_tool_defs(self) -> list[ToolDef]:
+        """Discover and merge tools from all attached MCP servers + Python functions."""
+        defs: list[ToolDef] = []
+
+        if self.mcps:
+            results = await asyncio.gather(
+                *[mcp.list_tools() for mcp in self.mcps],
+                return_exceptions=True,
+            )
+            for r in results:
+                if isinstance(r, list):
+                    defs.extend(r)
+
+        for fn in self.tools:
+            defs.append(fn_to_tool_def(fn))
+
+        return defs

deepcrew/exceptions.py

@@ -0,0 +1,22 @@
+class DeepCrewError(Exception):
+    """Base exception for all deepcrew errors."""
+
+
+class MCPError(DeepCrewError):
+    """Raised when an MCP server operation fails."""
+
+
+class ToolError(DeepCrewError):
+    """Raised when a tool call fails or a tool is not found."""
+
+
+class MaxTurnsError(DeepCrewError):
+    """Raised when an agent exceeds its max_turns limit without finishing."""
+
+
+class RouterError(DeepCrewError):
+    """Raised when the orchestrator router fails to parse a routing decision."""
+
+
+class WorkflowError(DeepCrewError):
+    """Raised for invalid workflow configurations (e.g. cycles in the DAG)."""

deepcrew/mcp/__init__.py

@@ -0,0 +1,7 @@
+from .base import MCPClient
+from .http import HTTPMCP
+from .manager import MCPManager
+from .sse import SSEMCP
+from .stdio import StdioMCP
+
+__all__ = ["MCPClient", "StdioMCP", "SSEMCP", "HTTPMCP", "MCPManager"]

deepcrew/mcp/base.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..types import ToolDef
+
+
+class MCPClient(ABC):
+    """
+    Abstract base class for all MCP transport implementations.
+
+    Subclasses implement the three transport types defined by the MCP spec:
+    - :class:`StdioMCP` — subprocess JSON-RPC over stdin/stdout
+    - :class:`SSEMCP` — legacy HTTP/SSE protocol
+    - :class:`HTTPMCP` — modern streamable-HTTP protocol
+
+    All clients support the async context manager protocol::
+
+        async with HTTPMCP("https://example.com/mcp") as mcp:
+            tools = await mcp.list_tools()
+    """
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish the connection and run the MCP initialize handshake."""
+
+    @abstractmethod
+    async def list_tools(self) -> list[ToolDef]:
+        """Return all tools exposed by this MCP server."""
+
+    @abstractmethod
+    async def call_tool(self, name: str, args: dict) -> dict | str:
+        """Invoke a tool and return its result."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Tear down the connection and release resources."""
+
+    async def __aenter__(self) -> MCPClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+
+def _parse_mcp_tool(raw: dict, client: MCPClient) -> ToolDef:
+    """Convert the raw tools/list entry from an MCP server into a ToolDef."""
+    schema = raw.get("inputSchema") or raw.get("input_schema") or {}
+    return ToolDef(
+        name=raw["name"],
+        description=raw.get("description", ""),
+        parameters=schema,
+        _mcp_client=client,
+    )

deepcrew/mcp/http.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+
+from ..exceptions import MCPError
+from ..types import ToolDef
+from .base import MCPClient, _parse_mcp_tool
+
+
+class HTTPMCP(MCPClient):
+    """
+    MCP client using the modern streamable-HTTP transport (MCP spec 2024-11-05+).
+
+    Performs an initialize handshake to obtain a ``Mcp-Session-Id`` header,
+    then uses that session ID for all subsequent requests. Supports automatic
+    session re-initialization on 400/401 responses and exponential-backoff
+    retries.
+
+    Parameters
+    ----------
+    url:
+        Full URL of the MCP server endpoint, e.g. ``"https://example.com/mcp"``.
+    headers:
+        Extra HTTP headers (e.g. ``{"Authorization": "Bearer token"}``).
+    timeout:
+        Request timeout in seconds.
+    retries:
+        Number of retry attempts on transient errors.
+
+    Example
+    -------
+    ::
+
+        async with HTTPMCP("https://my-mcp.example.com/mcp",
+                           headers={"Authorization": "Bearer sk-..."}) as mcp:
+            tools = await mcp.list_tools()
+            result = await mcp.call_tool("search", {"query": "hello"})
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        timeout: int = 30,
+        retries: int = 2,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self._extra_headers: dict[str, str] = headers or {}
+        self._timeout = timeout
+        self._retries = retries
+        self._session_id: str | None = None
+        self._http: httpx.AsyncClient | None = None
+        self._tool_cache: list[ToolDef] | None = None
+        self._msg_id = 0
+
+    def _headers(self) -> dict[str, str]:
+        h = {"Content-Type": "application/json", **self._extra_headers}
+        if self._session_id:
+            h["Mcp-Session-Id"] = self._session_id
+        return h
+
+    async def connect(self) -> None:
+        self._http = httpx.AsyncClient(timeout=self._timeout)
+        await self._initialize()
+
+    async def _initialize(self) -> None:
+        self._msg_id += 1
+        resp = await self._raw_post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._msg_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "deepcrew", "version": "0.1.0"},
+                },
+            },
+            skip_session=True,
+        )
+        self._session_id = resp.headers.get("mcp-session-id") or resp.headers.get("Mcp-Session-Id")
+        body = resp.json()
+        if "error" in body:
+            raise MCPError(f"MCP initialize error: {body['error']}")
+
+        # Send notifications/initialized (fire-and-forget)
+        if self._http:
+            try:
+                await self._http.post(
+                    self.url,
+                    json={"jsonrpc": "2.0", "method": "notifications/initialized"},
+                    headers=self._headers(),
+                )
+            except Exception:
+                pass
+
+    async def _raw_post(
+        self, payload: dict[str, Any], skip_session: bool = False
+    ) -> httpx.Response:
+        if self._http is None:
+            raise MCPError("HTTPMCP is not connected. Call connect() first.")
+        headers = {"Content-Type": "application/json", **self._extra_headers}
+        if not skip_session and self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        resp = await self._http.post(self.url, json=payload, headers=headers)
+        return resp
+
+    async def _post(self, payload: dict[str, Any], attempt: int = 0) -> dict[str, Any]:
+        try:
+            resp = await self._raw_post(payload)
+            if resp.status_code in (400, 401):
+                # Session expired — re-initialize and retry once
+                self._session_id = None
+                self._tool_cache = None
+                await self._initialize()
+                if attempt < self._retries:
+                    return await self._post(payload, attempt + 1)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as exc:
+            if attempt < self._retries:
+                await asyncio.sleep(2**attempt)
+                return await self._post(payload, attempt + 1)
+            raise MCPError(f"HTTPMCP request failed: {exc}") from exc
+        except httpx.RequestError as exc:
+            if attempt < self._retries:
+                await asyncio.sleep(2**attempt)
+                return await self._post(payload, attempt + 1)
+            raise MCPError(f"HTTPMCP connection error: {exc}") from exc
+
+    async def list_tools(self) -> list[ToolDef]:
+        if self._tool_cache is not None:
+            return self._tool_cache
+        self._msg_id += 1
+        body = await self._post({"jsonrpc": "2.0", "id": self._msg_id, "method": "tools/list", "params": {}})
+        if "error" in body:
+            raise MCPError(f"tools/list failed: {body['error']}")
+        raw_tools: list[dict] = body.get("result", {}).get("tools", [])
+        self._tool_cache = [_parse_mcp_tool(t, self) for t in raw_tools]
+        return self._tool_cache
+
+    async def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any] | str:
+        self._msg_id += 1
+        body = await self._post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._msg_id,
+                "method": "tools/call",
+                "params": {"name": name, "arguments": args},
+            }
+        )
+        if "error" in body:
+            raise MCPError(f"Tool {name!r} call failed: {body['error']}")
+        result = body.get("result", {})
+        if isinstance(result, dict) and "content" in result:
+            contents = result["content"]
+            if contents and isinstance(contents[0], dict):
+                return contents[0].get("text", json.dumps(result))
+        return result
+
+    async def close(self) -> None:
+        if self._http:
+            await self._http.aclose()
+            self._http = None

deepcrew/mcp/manager.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ..exceptions import MCPError
+from ..types import ToolDef
+from .base import MCPClient
+
+
+class MCPManager:
+    """
+    Aggregates multiple MCP clients into a single interface.
+
+    Discovers tools from all attached clients in parallel and maintains a
+    routing table so that tool calls are automatically dispatched to the
+    correct server.
+
+    Parameters
+    ----------
+    clients:
+        Any combination of StdioMCP, SSEMCP, and HTTPMCP instances.
+
+    Example
+    -------
+    ::
+
+        manager = MCPManager([
+            StdioMCP("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]),
+            HTTPMCP("https://my-search-mcp.example.com/mcp"),
+        ])
+        await manager.connect_all()
+        tools = await manager.discover_tools()
+
+        # Pass manager as a single MCP to an Agent
+        agent = Agent("assistant", model="openai/gpt-4o", mcps=[manager])
+    """
+
+    def __init__(self, clients: list[MCPClient]) -> None:
+        self._clients = clients
+        self._routing: dict[str, MCPClient] = {}
+
+    async def connect_all(self) -> None:
+        """Connect all clients in parallel."""
+        await asyncio.gather(*[c.connect() for c in self._clients], return_exceptions=True)
+
+    async def discover_tools(self) -> list[ToolDef]:
+        """
+        Fetch tools from all servers in parallel and build the routing table.
+        Tools from earlier clients take precedence if names collide.
+        """
+        all_tools: list[ToolDef] = []
+        results = await asyncio.gather(
+            *[c.list_tools() for c in self._clients],
+            return_exceptions=True,
+        )
+        for r in results:
+            if isinstance(r, list):
+                for td in r:
+                    if td.name not in self._routing:
+                        self._routing[td.name] = td._mcp_client  # type: ignore[assignment]
+                    all_tools.append(td)
+        return all_tools
+
+    async def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any] | str:
+        client = self._routing.get(name)
+        if not client:
+            raise MCPError(
+                f"No MCP server owns tool {name!r}. "
+                "Did you call discover_tools() before calling call_tool()?"
+            )
+        return await client.call_tool(name, args)
+
+    async def list_tools(self) -> list[ToolDef]:
+        """Implement the MCPClient interface so MCPManager can be passed as an MCP."""
+        return await self.discover_tools()
+
+    async def close_all(self) -> None:
+        """Close all clients, ignoring individual errors."""
+        await asyncio.gather(*[c.close() for c in self._clients], return_exceptions=True)
+
+    async def __aenter__(self) -> MCPManager:
+        await self.connect_all()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close_all()

deepcrew/mcp/sse.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+from ..exceptions import MCPError
+from ..types import ToolDef
+from .base import MCPClient, _parse_mcp_tool
+
+
+class SSEMCP(MCPClient):
+    """
+    MCP client for the legacy Server-Sent Events transport.
+
+    This transport was used by early MCP servers (pre-2024-11-05). It
+    connects to a ``/sse`` endpoint to receive an event that tells it which
+    URL to POST requests to.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of the MCP server, e.g. ``"http://localhost:3000"``.
+        The client appends ``/sse`` for the event stream and uses the
+        ``endpoint`` event to discover the POST URL.
+    headers:
+        Extra HTTP headers forwarded with every request.
+
+    Example
+    -------
+    ::
+
+        async with SSEMCP("http://localhost:3000") as mcp:
+            tools = await mcp.list_tools()
+    """
+
+    def __init__(self, base_url: str, headers: dict[str, str] | None = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._extra_headers: dict[str, str] = headers or {}
+        self._post_url: str | None = None
+        self._http: httpx.AsyncClient | None = None
+        self._tool_cache: list[ToolDef] | None = None
+        self._msg_id = 0
+
+    async def connect(self) -> None:
+        self._http = httpx.AsyncClient(timeout=60.0)
+        await self._sse_handshake()
+        await self._initialize()
+
+    async def _sse_handshake(self) -> None:
+        """Subscribe to /sse until we receive the 'endpoint' event."""
+        try:
+            from httpx_sse import aconnect_sse
+        except ImportError as exc:
+            raise MCPError(
+                "httpx-sse is required for SSEMCP. Install it with: pip install httpx-sse"
+            ) from exc
+
+        if self._http is None:
+            raise MCPError("SSEMCP not connected")
+
+        sse_url = f"{self.base_url}/sse"
+        async with aconnect_sse(
+            self._http, "GET", sse_url, headers=self._extra_headers
+        ) as event_source:
+            async for event in event_source.aiter_sse():
+                if event.event == "endpoint":
+                    data = event.data.strip()
+                    if data.startswith("http"):
+                        self._post_url = data
+                    else:
+                        self._post_url = urljoin(self.base_url, data)
+                    return
+
+        raise MCPError("SSE stream closed before receiving 'endpoint' event")
+
+    async def _post(self, payload: dict[str, Any]) -> dict[str, Any]:
+        if self._http is None or self._post_url is None:
+            raise MCPError("SSEMCP is not connected. Call connect() first.")
+        resp = await self._http.post(
+            self._post_url, json=payload, headers=self._extra_headers
+        )
+        resp.raise_for_status()
+        try:
+            return resp.json()
+        except Exception:
+            return {"result": resp.text}
+
+    async def _initialize(self) -> None:
+        self._msg_id += 1
+        body = await self._post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._msg_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "deepcrew", "version": "0.1.0"},
+                },
+            }
+        )
+        if "error" in body:
+            raise MCPError(f"SSEMCP initialize error: {body['error']}")
+
+        # Fire-and-forget notification
+        try:
+            if self._http and self._post_url:
+                await self._http.post(
+                    self._post_url,
+                    json={"jsonrpc": "2.0", "method": "notifications/initialized"},
+                    headers=self._extra_headers,
+                )
+        except Exception:
+            pass
+
+    async def list_tools(self) -> list[ToolDef]:
+        if self._tool_cache is not None:
+            return self._tool_cache
+        self._msg_id += 1
+        body = await self._post(
+            {"jsonrpc": "2.0", "id": self._msg_id, "method": "tools/list", "params": {}}
+        )
+        if "error" in body:
+            raise MCPError(f"tools/list failed: {body['error']}")
+        raw_tools: list[dict] = body.get("result", {}).get("tools", [])
+        self._tool_cache = [_parse_mcp_tool(t, self) for t in raw_tools]
+        return self._tool_cache
+
+    async def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any] | str:
+        self._msg_id += 1
+        body = await self._post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._msg_id,
+                "method": "tools/call",
+                "params": {"name": name, "arguments": args},
+            }
+        )
+        if "error" in body:
+            raise MCPError(f"Tool {name!r} call failed: {body['error']}")
+        result = body.get("result", {})
+        if isinstance(result, dict) and "content" in result:
+            contents = result["content"]
+            if contents and isinstance(contents[0], dict):
+                return contents[0].get("text", json.dumps(result))
+        return result
+
+    async def close(self) -> None:
+        if self._http:
+            await self._http.aclose()
+            self._http = None