Metadata-Version: 2.3
Name: crewmaster
Version: 2.0.2b0
Summary: A powerful and flexible framework for building, orchestrating, and deploying multi-agent systems.
Keywords: ai,llm,agent
Author: Imolko
Author-email: info@imolko.com
Requires-Python: >=3.12.3,<3.14
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: deepeval (>=2.3.8,<3.0.0)
Requires-Dist: fastapi (>=0.139.0,<0.140.0)
Requires-Dist: google (>=3.0.0,<4.0.0)
Requires-Dist: google-api-python-client (>=2.161.0,<3.0.0)
Requires-Dist: google-auth-httplib2 (>=0.2.0,<0.3.0)
Requires-Dist: google-auth-oauthlib (>=1.2.1,<2.0.0)
Requires-Dist: langchain-core (>=0.3.35,<0.4.0)
Requires-Dist: langfuse (>=4.13.2,<5.0.0)
Requires-Dist: langgraph (>=0.2.71,<0.3.0)
Requires-Dist: mkdocs-mermaid2-plugin (>=1.2.2,<2.0.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pydantic-settings (>=2.7.1,<3.0.0)
Requires-Dist: pytest (>=8.3.4,<9.0.0)
Requires-Dist: pytest-asyncio (>=0.25.3,<0.26.0)
Requires-Dist: pytest-mock (>=3.14.0,<4.0.0)
Requires-Dist: pytest-watcher (>=0.4.3,<0.5.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: setuptools (>=75.8.0,<76.0.0)
Requires-Dist: structlog (>=25.1.0,<26.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Description-Content-Type: text/markdown

![crewmaster](docs/images/crewmaster-logo-512.png)

# CrewMaster v2.0.0 — The Ultimate Framework for Building AI Teams 🚀

CrewMaster is a **framework-agnostic** Python library for building, orchestrating,
and evaluating **type-safe multi-agent systems**. Define Operations, wire them
into DAGs, and execute with structured, streaming output — without being locked
into a single LLM framework.

---

## Why CrewMaster v2.0.0?

v2.0.0 is a complete redesign built on lessons learned from v1. Every concept
has been rethought for developer ergonomics, type safety, and framework
independence.

| v1 (legacy) | v2.0.0 |
|---|---|
| `AgentBase`, `Skill`, `Team`, `Crew` | `Operation`, `AgentConfig`, `ExecutionPlan` |
| LangChain only | Pluggable `RuntimeDriver` (PydanticAI, LangChain, bring your own) |
| Ad-hoc data flow | Typed DAG with `produces`/`consumes` |
| No prompt management | `PromptEngine` + `BlockStore` with Jinja2 templates |
| No evaluation | Built-in evaluation framework with snapshots, datasets, criteria |

---

## Quick Example

```python
import asyncio
from pydantic import BaseModel
from crewmaster import execute
from crewmaster.agents.agent import AgentConfig
from crewmaster.agents.context.store import ContextStore
from crewmaster.operations.operation import Operation
from crewmaster.execution.runtime import FakeDriver


class Greeting(BaseModel):
    message: str


# 1. Define an agent
greeter = AgentConfig(
    name="greeter",
    identity_blocks=["blocks://greeter/identity"],
)

# 2. Define an operation
say_hello = Operation(
    name="say_hello",
    produces=Greeting,
    kind="artifact",
    agent=greeter,
    task_blocks=["blocks://greeter/task"],
)

# 3. Execute with FakeDriver (no API key needed)
async def main():
    result = await execute(
        operation=say_hello,
        context_store=ContextStore(),
        default_runtime=FakeDriver(),
    )
    print(result.message)


asyncio.run(main())
```

---

## Key Concepts

- **Operation** — Typed, recursive unit of work that declares `produces`/`consumes`
- **AgentConfig** — Persistent agent identity with prompt blocks, tool scope, context projections
- **ExecutionPlan** — DAG resolved automatically from Operation trees via `resolve_plan()`
- **ContextStore** — Type-keyed container of domain objects
- **PromptEngine + BlockStore** — Jinja2-based prompt composition from `blocks://` URIs
- **ToolRegistry** — Scoped tool storage with semantic retrieval at runtime (`request_capability`)
- **RuntimeDriver** — Async protocol for LLM backends (PydanticAI, LangChain, custom)
- **execute / execute_stream** — Top-level entry points for blocking and streaming execution

---

## Installation

```bash
pip install crewmaster
```

### With extras

```bash
# PydanticAI runtime driver (recommended)
pip install "crewmaster[pydantic-ai]"

# Sandbox UI for interactive evaluation
pip install "crewmaster[sandbox-ui]"
```

### Environment

```bash
# For PydanticAIDriver
export OPENAI_API_KEY=<your-api-key>
```

See the [installation guide](https://crewmaster-2cc7a6.gitlab.io/getting-started/installation/)
for full details.

---

## Framework-Agnostic

Swap drivers without changing your code:

```python
from crewmaster.execution.drivers.pydantic_ai import PydanticAIDriver

driver = PydanticAIDriver(model_name="openai:gpt-4o")

result = await execute(
    operation=my_op,
    default_runtime=driver,  # just swap the driver
    ...
)
```

---

## Built-in Collaboration & Conversation

```python
# Sequential multi-agent channel
from crewmaster.conversation.channel import channel_dispatch

# Human-agent dialogue with structured clarification
from crewmaster.conversation.dialogue import dialogue, AgentOutputClarification

# Grill-me: structured critique-and-revision cycles
from crewmaster.collaboration.protocol import GrillMeProtocol
```

---

## Evaluation

CrewMaster v2.0.0 includes a complete evaluation framework:

- **Snapshots** — Version your operations with expected inputs/outputs
- **Datasets** — Define test data in YAML
- **Criteria** — Write evaluation criteria as `Operation` nodes producing `Score` objects
- **Reports** — Aggregate results with per-criterion averages and global scores

---

## Sandbox

CrewMaster ships with a built-in **sandbox** — a FastAPI application that lets
you explore, test, and evaluate operations interactively without writing code:

```bash
pip install "crewmaster[sandbox-ui]"
python -m crewmaster.sandbox.ui.app
```

Open `http://localhost:8080` to access:

- **Execute** — Run operations with real or fake drivers
- **Stream** — Watch multi-node DAGs execute in real-time via SSE
- **Evaluate** — Run evaluation scenarios against datasets and criteria
- **Pre-built scenarios** — Channel, dialogue, DAG pipeline, error recovery,
  grill-me collaboration, and evaluation examples

---

## Documentation

[**Full documentation →**](https://crewmaster-2cc7a6.gitlab.io/)

| Section | |
|---|---|
| [Getting Started](https://crewmaster-2cc7a6.gitlab.io/getting-started/installation/) | Installation and core concepts |
| [Tutorials](https://crewmaster-2cc7a6.gitlab.io/tutorials/my-first-operation/) | Step-by-step with FakeDriver |
| [How-to Guides](https://crewmaster-2cc7a6.gitlab.io/how-to-guides/agent-with-tool/) | Agent with tool, HTTP serving, pipelines, channels, dialogue, collaboration, evaluation |
| [API Reference](https://crewmaster-2cc7a6.gitlab.io/reference/api/) | Per-module API docs from docstrings |
| [Migration](https://crewmaster-2cc7a6.gitlab.io/migration-v2/) | v1 → v2.0.0 migration guide |

---

## Development

```bash
# Install dev dependencies
poetry install

# Run tests (674+ and counting)
poetry run pytest

# Build docs
poetry run mkdocs build --strict
```

---

## License

MIT — see [LICENSE](LICENSE) for details.

