deepcrew-ai 0.1.0__tar.gz

deepcrew_ai-0.1.0/.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "docs",
+      "runtimeExecutable": "python",
+      "runtimeArgs": ["-m", "http.server", "4242", "--directory", "docs"],
+      "port": 4242
+    }
+  ]
+}

deepcrew_ai-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

deepcrew_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `deepcrew-ai` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-06-21
+
+### Added
+
+#### Core
+- `Agent` dataclass — define name, model (litellm string), system prompt, MCP clients, Python function tools, temperature, max tokens, and arbitrary `extra_params` forwarded to litellm
+- `run_agent()` — async agentic loop: LLM → parallel tool execution → LLM, repeating until no tool calls or `max_turns` exceeded; streams `StreamEvent` objects to an optional `asyncio.Queue`
+- `MaxTurnsError` raised when an agent exhausts its turn budget
+
+#### Orchestrator (automated mode)
+- `Orchestrator` — three-stage pipeline: router LLM decides single-agent vs. parallel fan-out, agents run via `asyncio.gather`, synthesizer LLM merges results
+- `Orchestrator.run()` — returns `OrchestratorResult` with final text, per-agent results, and token counts
+- `Orchestrator.stream()` — async generator yielding `StreamEvent` objects in real time
+- Built-in router and synthesizer system prompts; both overridable
+- `max_parallel_agents` cap to bound fan-out
+
+#### Workflow Builder (explicit DAG mode)
+- `WorkflowBuilder` — fluent API to declare agent nodes and dependency edges
+- `.add_agent(name, agent, task)` — add a node with a string template (`{input}`, `{node_name}`) or callable task
+- `.then(predecessor, successor)` — declare ordering constraint
+- `.run()` / `.stream()` — execute the DAG; independent nodes at each topological level run in parallel via `asyncio.gather`
+- `WorkflowResult` with per-node `AgentResult` outputs and aggregate token counts
+- `WorkflowError` on cycle detection or unknown node references
+
+#### Python Function Tools
+- `@tool` decorator — marks any callable as an agent tool; optional `name` and `description` overrides
+- `fn_to_tool_def()` — converts any Python function to a `ToolDef` with JSON Schema generated from type hints (`str`, `int`, `float`, `bool`, `list[X]`, `dict[str, X]`, `Optional[X]`, `Union`, `Literal`)
+- Google-style docstring parameter descriptions extracted automatically
+
+#### MCP Integration
+- `MCPClient` abstract base class with `connect()`, `list_tools()`, `call_tool()`, `close()`, and async context manager support
+- `StdioMCP` — spawns a subprocess and communicates via JSON-RPC over stdin/stdout; supports MCP `2024-11-05` initialize handshake
+- `HTTPMCP` — modern streamable-HTTP MCP transport with `Mcp-Session-Id` session management, automatic session re-initialization on `400/401`, and exponential-backoff retries
+- `SSEMCP` — legacy SSE transport; connects to `/sse`, receives the `endpoint` event, posts JSON-RPC to the resolved URL
+- `MCPManager` — aggregates multiple MCP clients; discovers tools in parallel and maintains a routing table for `call_tool()` dispatch; implements `MCPClient` interface so it can be passed directly to `Agent.mcps`
+
+#### Streaming
+- `StreamEvent` dataclass with `event` (`EventType` enum), `agent_id`, and `data` dict
+- `StreamEvent.to_sse()` — produces a ready-to-stream Server-Sent Event string
+- `queue_to_stream()` — drains an `asyncio.Queue[StreamEvent | None]` as an async generator
+- `EventType` values: `agent_start`, `text_delta`, `thinking_delta`, `tool_call`, `tool_result`, `agent_done`, `step_start`, `step_done`, `error`, `done`
+
+#### Types & Exceptions
+- `AgentResult`, `WorkflowResult`, `OrchestratorResult`, `ToolDef`
+- `DeepCrewError`, `MCPError`, `ToolError`, `MaxTurnsError`, `RouterError`, `WorkflowError`
+
+#### Package
+- `pyproject.toml` with hatchling build backend; Python ≥ 3.11 required
+- Dependencies: `litellm>=1.63.0`, `httpx>=0.27.0`, `httpx-sse>=0.4.0`, `pydantic>=2.0.0`, `anyio>=4.4.0`, `typing-extensions>=4.9.0`
+- 37 unit tests (pytest-asyncio); all passing on Python 3.13
+- 4 runnable examples: `simple_agent.py`, `workflow_example.py`, `automated_example.py`, `mcp_example.py`
+
+[0.1.0]: https://github.com/deepcrew-ai/deepcrew-ai/releases/tag/v0.1.0

deepcrew_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepCrew AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepcrew_ai-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: deepcrew-ai
+Version: 0.1.0
+Summary: Multi-agent spawning library with litellm, MCP tools, and parallel workflows
+Project-URL: Homepage, https://github.com/deepcrew-ai/deepcrew-ai
+Project-URL: Repository, https://github.com/deepcrew-ai/deepcrew-ai
+Project-URL: Issues, https://github.com/deepcrew-ai/deepcrew-ai/issues
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,litellm,llm,mcp,multi-agent,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.4.0
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: litellm>=1.63.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# deepcrew-ai
+
+Multi-agent spawning library for Python. Build parallel AI workflows using any LLM provider, with MCP tool integration and SSE streaming — all with minimal boilerplate.
+
+```bash
+pip install deepcrew-ai
+```
+
+---
+
+## Features
+
+- **100+ LLM providers** via [LiteLLM](https://github.com/BerriAI/litellm) — OpenAI, Anthropic, Gemini, Bedrock, Azure, and more
+- **Two orchestration modes** — explicit DAG workflows or automated AI-driven routing
+- **Parallel execution** — independent agents always run concurrently via `asyncio.gather`
+- **MCP tool integration** — stdio (subprocess), SSE (legacy), and streamable-HTTP transports
+- **Python function tools** — decorate any function with `@tool`, schema auto-generated from type hints
+- **SSE streaming** — stream events as they happen, compatible with FastAPI `StreamingResponse`
+- **PyPI-ready** — clean package structure, no extra config needed
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from deepcrew import Agent, run_agent, tool
+
+@tool
+def get_weather(city: str) -> dict:
+    "Get current weather."
+    return {"city": city, "temp": 22, "condition": "sunny"}
+
+async def main():
+    agent = Agent(
+        name="assistant",
+        model="openai/gpt-4o",
+        system_prompt="You are a helpful assistant.",
+        tools=[get_weather],
+    )
+    result = await run_agent(agent, [{"role": "user", "content": "Weather in Paris?"}])
+    print(result.text)
+
+asyncio.run(main())
+```
+
+---
+
+## Orchestration Modes
+
+### 1. Workflow Builder (explicit DAG)
+
+Define agents and their dependencies. Independent nodes run in parallel automatically.
+
+```python
+from deepcrew import Agent, WorkflowBuilder
+
+researcher = Agent("researcher", model="openai/gpt-4o-mini",
+                   system_prompt="Research the topic thoroughly.")
+critic     = Agent("critic",     model="openai/gpt-4o-mini",
+                   system_prompt="Find gaps and weaknesses in the research.")
+writer     = Agent("writer",     model="openai/gpt-4o",
+                   system_prompt="Write a polished report.")
+
+workflow = (
+    WorkflowBuilder()
+    .add_agent("research", researcher, task="{input}")
+    .add_agent("critique", critic,     task="Critique this research:\n{research}")
+    .add_agent("report",   writer,     task="Write a report using:\n{research}\n\nCritique:\n{critique}")
+    .then("research", "critique")  # critique waits for research
+    .then("research", "report")    # report waits for research
+    .then("critique", "report")    # report waits for critique
+)
+
+# research runs first, then critique + expand in PARALLEL, then report
+result = await workflow.run("The future of renewable energy")
+print(result.final_output.text)
+print(f"Total tokens: {result.total_tokens}")
+```
+
+### 2. Automated Orchestrator (AI-driven routing)
+
+The router LLM decides at runtime: use one agent, or fan out to multiple in parallel.
+
+```python
+from deepcrew import Agent, Orchestrator
+
+agents = [
+    Agent("researcher", model="openai/gpt-4o-mini", system_prompt="Research specialist."),
+    Agent("analyst",    model="openai/gpt-4o-mini", system_prompt="Data analyst."),
+    Agent("writer",     model="openai/gpt-4o-mini", system_prompt="Content writer."),
+]
+
+orch = Orchestrator(
+    agents=agents,
+    router_model="openai/gpt-4o-mini",
+    synthesizer_model="openai/gpt-4o",
+)
+
+# Non-streaming
+result = await orch.run("Summarize the state of quantum computing")
+print(result.final_text)
+
+# Streaming (yields StreamEvent objects)
+async for event in orch.stream("Summarize the state of quantum computing"):
+    print(event.to_sse(), end="")  # ready for FastAPI StreamingResponse
+```
+
+---
+
+## MCP Tools
+
+### Stdio MCP (subprocess)
+
+```python
+from deepcrew import Agent, run_agent
+from deepcrew.mcp import StdioMCP
+
+async with StdioMCP("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]) as mcp:
+    agent = Agent("file_agent", model="openai/gpt-4o", mcps=[mcp])
+    result = await run_agent(agent, [{"role": "user", "content": "List files here"}])
+```
+
+### HTTP MCP (streamable-HTTP, modern)
+
+```python
+from deepcrew.mcp import HTTPMCP
+
+async with HTTPMCP("https://my-mcp.example.com/mcp",
+                   headers={"Authorization": "Bearer sk-..."}) as mcp:
+    agent = Agent("agent", model="openai/gpt-4o", mcps=[mcp])
+```
+
+### SSE MCP (legacy)
+
+```python
+from deepcrew.mcp import SSEMCP
+
+async with SSEMCP("http://localhost:3000") as mcp:
+    agent = Agent("agent", model="openai/gpt-4o", mcps=[mcp])
+```
+
+### MCPManager (multiple servers)
+
+```python
+from deepcrew.mcp import MCPManager, StdioMCP, HTTPMCP
+
+async with MCPManager([
+    StdioMCP("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]),
+    HTTPMCP("https://search-mcp.example.com/mcp"),
+]) as manager:
+    tools = await manager.discover_tools()
+    agent = Agent("agent", model="openai/gpt-4o", mcps=[manager])
+```
+
+---
+
+## Python Function Tools
+
+```python
+from deepcrew import tool, fn_to_tool_def
+
+@tool
+def calculate(expression: str) -> float:
+    """Evaluate a mathematical expression.
+
+    Args:
+        expression (str): A Python math expression like '2 ** 10'.
+    """
+    return eval(expression)  # noqa: S307 — replace with safe parser in production
+
+# Or without decorator (schema still auto-generated):
+def search_db(query: str, limit: int = 10) -> list:
+    ...
+
+agent = Agent("agent", model="openai/gpt-4o", tools=[calculate, search_db])
+```
+
+---
+
+## Streaming with FastAPI
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+from deepcrew import Orchestrator, Agent
+
+app = FastAPI()
+orch = Orchestrator([Agent("assistant", model="openai/gpt-4o")])
+
+@app.post("/chat")
+async def chat(query: str):
+    async def event_stream():
+        async for event in orch.stream(query):
+            yield event.to_sse()
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+```
+
+---
+
+## Stream Events
+
+All events have `event`, `agent_id`, and a `data` dict:
+
+| Event | Data keys | Meaning |
+|---|---|---|
+| `agent_start` | `model` | Agent loop begins |
+| `text_delta` | `chunk` | Incremental text from LLM |
+| `thinking_delta` | `chunk`, `tokens` | Thinking/reasoning text |
+| `tool_call` | `tool`, `args` | Tool about to be called |
+| `tool_result` | `tool`, `result` | Tool call completed |
+| `agent_done` | `input_tokens`, `output_tokens` | Agent finished |
+| `step_start` | `node` | Workflow node beginning |
+| `step_done` | `node` | Workflow node completed |
+| `error` | `message` | An error occurred |
+| `done` | `final_text` | Entire run complete |
+
+---
+
+## Agent Configuration
+
+```python
+Agent(
+    name="my_agent",
+    model="anthropic/claude-opus-4-8",   # any litellm model string
+    system_prompt="You are...",
+    mcps=[mcp1, mcp2],                   # MCP tool servers
+    tools=[my_fn, another_fn],           # Python function tools
+    max_turns=10,                         # LLM→tool→LLM cycles
+    temperature=0.7,
+    max_tokens=4096,
+    extra_params={"thinking": {"type": "enabled", "budget_tokens": 5000}},
+)
+```
+
+---
+
+## Provider Examples
+
+```python
+# OpenAI
+Agent("a", model="openai/gpt-4o")
+Agent("a", model="openai/gpt-4o-mini")
+
+# Anthropic
+Agent("a", model="anthropic/claude-opus-4-8")
+Agent("a", model="anthropic/claude-haiku-4-5-20251001")
+
+# Google
+Agent("a", model="gemini/gemini-2.0-flash")
+Agent("a", model="gemini/gemini-2.5-pro")
+
+# AWS Bedrock
+Agent("a", model="bedrock/anthropic.claude-opus-4-8-20250514-v1:0")
+
+# Azure OpenAI
+Agent("a", model="azure/gpt-4o", extra_params={"api_base": "https://..."})
+
+# Local (Ollama)
+Agent("a", model="ollama/llama3.2")
+```
+
+---
+
+## Installation
+
+```bash
+pip install deepcrew-ai
+```
+
+With development dependencies:
+
+```bash
+pip install deepcrew-ai[dev]
+```
+
+Requires Python 3.11+.
+
+---
+
+## License
+
+MIT