Metadata-Version: 2.4
Name: chatdev
Version: 0.1.0
Summary: Workflow orchestration runtime for ChatDev
Author: ChatDev Team
License: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: <3.14,>=3.12
Requires-Dist: beautifulsoup4
Requires-Dist: cartopy
Requires-Dist: chardet>=5.2.0
Requires-Dist: click<8.3,>=8.1.8
Requires-Dist: ddgs
Requires-Dist: faiss-cpu
Requires-Dist: fastapi==0.124.0
Requires-Dist: fastmcp
Requires-Dist: filelock>=3.20.1
Requires-Dist: google-genai>=1.52.0
Requires-Dist: markdown>=3.10
Requires-Dist: matplotlib
Requires-Dist: mcp
Requires-Dist: networkx
Requires-Dist: numpy>=2.3.5
Requires-Dist: openai
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: pandas>=2.3.3
Requires-Dist: pydantic==2.12.5
Requires-Dist: pygame>=2.6.1
Requires-Dist: pytest
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tenacity
Requires-Dist: uvicorn
Requires-Dist: websockets
Requires-Dist: wsproto
Requires-Dist: xhtml2pdf>=0.2.17
Description-Content-Type: text/markdown

# ChatDev Python SDK

This package is a Python SDK wrapper around the upstream `ChatDev` project. By passing a `yaml_file` path, you can load and execute the multi-agent system defined by the graph and nodes in the YAML file. In Python, you only need to provide `yaml_file` + `task_prompt` (and optionally `api_key` / `model` / etc.) to run the workflow and get results.

## Quick Start

### Installation

From the repository root:

```bash
pip install chatdev
```

### Environment Variables:

Some YAML configurations require `api_key` and `base_url`. You can use `export` to add global environment variables:

```bash
export API_KEY="YOUR_API_KEY"
export BASE_URL="YOUR_BASE_URL"
```

### Test Example:

```python
from chatdev import run_workflow

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="This is a minimal run example",
)

print(result.success)
print(result.final_message)
print(result.output_dir)
```

### Pass configs (default: the first node ID in the YAML file):

```python
result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs=AgentConfig(
        provider="openai",
        model="gpt-4o",
        api_key="YOUR_API_KEY",
        base_url="https://api.openai.com/v1",
        temperature=1.0,
    ),
)
```

### Specify a node ID:

```python
result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs={
        "Programmer Code Review": AgentConfig(
            provider="openai",
            model="gpt-4o",
            api_key="YOUR_API_KEY",
            base_url="https://api.openai.com/v1",
            temperature=1.0,
        ),
    },
)
```

### Tools & Skills registration example:

```python
from chatdev import AgentConfig, register_skill, register_tool, run_workflow

@register_skill(
    name="data_analyzer",
    description="Analyze data and generate a report",
    instructions="Please analyze the input in a structured way and output three conclusions.",
)

@register_tool(name="my_echo", description="Echo input")
def my_echo(text: str) -> str:
    return text

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs={
        "Programmer Code Review": AgentConfig(
            provider="openai",
            model="gpt-4o",
            api_key="YOUR_API_KEY",
            base_url="https://api.openai.com/v1",
            temperature=1.0,
            tools=["my_echo"],
            skills=["data_analyzer"]
        ),
    },
)
```

## SDK API Reference

### `chatdev.run_workflow(...)`

Execute a workflow YAML file and return `ChatDevResult`:

- **yaml_file**: `str | Path` — the workflow YAML path
- **task_prompt**: `str` — your task input
- **attachments**: `list[str | Path] | None` — optional attachment paths (packaged into the execution workspace)
- **variables**: `dict | None`
- **agent_configs**: `AgentConfig | dict[str, AgentConfig] | None`
  - Passing a single `AgentConfig`: automatically attach it to the first node whose `type` is `agent` or `model` (the order of `nodes` in the YAML). If there is no such node, it falls back to the first node with a non-empty `id`.
  - Passing a `dict[node_id, AgentConfig]`: only update the node with that exact `id` (no `"default"` fallback).

### `chatdev.AgentConfig`

Optional parameters for overriding/injecting model configuration (merged into the matched node’s `config`; commonly the `agent` / `model` nodes in YAML):

- **provider**: `"openai"` / `"gemini"` / ...
- **model**: e.g. `"gpt-4o"`
- **api_key**
- **base_url**
- **system_prompt**: overrides the YAML `role`
- **temperature/top_p/max_tokens**
- **skills**: add custom skills
- **tools**: add custom tools

### `chatdev.ChatDevResult`

The return object of `run_workflow` (common fields):

- **success**: whether it succeeded
- **final_message**: the final output text (string)
- **output_dir**: the output directory of this run (`Path`)

## Extensions: Register Tools & Skills (Optional)

You can register tools/skills with decorators:

- `@chatdev.register_tool(name=..., description=...)`
- `@chatdev.register_skill(name=..., description=..., ...)`

## Citation

If you use this project in research or products, please cite ChatDev's GitHub repository:
[`OpenBMB/ChatDev`](https://github.com/OpenBMB/ChatDev)