Metadata-Version: 2.4
Name: pydantic-team
Version: 0.1.0
Summary: Type-safe team orchestration for pydantic-ai Agents
Project-URL: Homepage, https://github.com/etiqa/pydantic-team
Project-URL: Source, https://github.com/etiqa/pydantic-team
Author-email: Fabio Pulvirenti <fabio@etiqa.it>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pydantic-ai>=1.0
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.12
Description-Content-Type: text/markdown

# pydantic-team

Type-safe team orchestration for [`pydantic-ai`](https://ai.pydantic.dev) Agents.

v1 focuses on **hierarchical** (leader + specialists) teams — the same idea as Agno's
`TeamMode.coordinate` and pydantic-ai
[agent delegation](https://ai.pydantic.dev/multi-agent-applications/), without hiding
usage/token tracking.

For **sequential**, branching, or stateful pipelines, use
[`pydantic-graph`](https://ai.pydantic.dev/graph/) (already pulled in by `pydantic-ai`).

## Install

```bash
uv add pydantic-team
# or from a checkout:
uv sync --group lint --group dev
```

Requires Python 3.10+.

## Documentation

Full guides and API reference (MkDocs + mkdocstrings):

```bash
uv sync --group docs
make docs-serve   # http://127.0.0.1:8000
make docs         # build into site/
```

## HierarchicalTeam

The leader registers each member as a tool and passes `usage=ctx.usage` on nested runs
so `TeamResult.usage` includes every agent involved.

```python
import asyncio

from pydantic_ai import Agent
from pydantic_team import HierarchicalTeam

researcher = Agent(
    'openai:gpt-4o',
    name='researcher',
    instructions='Research the topic and return concise notes.',
)
writer = Agent(
    'openai:gpt-4o',
    name='writer',
    instructions='Turn research notes into a short article.',
)

team = HierarchicalTeam(
    leader_model='openai:gpt-4o',
    members=[researcher, writer],
    system_prompt_override=(
        'Delegate to researcher or writer based on the task, then synthesize a final answer.'
    ),
)


async def main() -> None:
    result = await team.run('Explain pydantic-ai agent delegation briefly.')
    print(result.data)
    print(result.usage)


asyncio.run(main())
```

You can also pass an existing `leader_agent=` instead of `leader_model=`. Nested
`HierarchicalTeam` instances are valid members (set `name=` for a clear tool id).

See the [hierarchical teams guide](docs/hierarchical.md) for nested teams, usage
details, and `TestModel` testing.

### Result type

```python
from pydantic_team import TeamResult

# result: TeamResult
# result.data  — final leader output
# result.usage — aggregated RunUsage (requests + tokens)
```

## Sequential / complex control flow

Use [`pydantic-graph`](https://ai.pydantic.dev/graph/) when you need an ordered pipeline,
branches, loops, or shared state. This library intentionally does **not** reimplement that.

## Development

```bash
make install      # uv sync + pre-commit
make format
make lint
make typecheck
make test         # pytest with --cov-fail-under=100
make ci           # format + lint + test
make ci-strict    # lint + typecheck + test
make docs         # MkDocs build (needs --group docs)
make docs-serve
```

Unit tests use pydantic-ai `TestModel` only — no live LLM calls.

## License

MIT
