Metadata-Version: 2.4
Name: agent-framework-lab
Version: 1.0.0b260910
Summary: Experimental modules for Microsoft Agent Framework
Author-email: Microsoft <af-support@microsoft.com>
Project-URL: homepage, https://aka.ms/agent-framework
Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
Project-URL: issues, https://github.com/microsoft/agent-framework/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agent-framework-core<2,>=1.13.0
Provides-Extra: gaia
Requires-Dist: pydantic>=2.0.0; extra == "gaia"
Requires-Dist: opentelemetry-api>=1.39.0; extra == "gaia"
Requires-Dist: opentelemetry-sdk<2,>=1.39.0; extra == "gaia"
Requires-Dist: tqdm>=4.60.0; extra == "gaia"
Requires-Dist: huggingface-hub>=0.20.0; extra == "gaia"
Requires-Dist: orjson<4,>=3.10.7; extra == "gaia"
Requires-Dist: pyarrow>=18.0.0; extra == "gaia"
Provides-Extra: lightning
Requires-Dist: agentlightning<0.4.0,>=0.2.0; extra == "lightning"
Provides-Extra: tau2
Requires-Dist: pydantic>=2.0.0; extra == "tau2"
Requires-Dist: tiktoken>=0.11.0; extra == "tau2"
Requires-Dist: loguru>=0.7.3; extra == "tau2"
Requires-Dist: numpy; extra == "tau2"
Provides-Extra: math
Requires-Dist: sympy>=1.13.0; extra == "math"
Dynamic: license-file

# Agent Framework Lab

This is the experimental package for Microsoft Agent Framework, `agent-framework-lab`, which contains
various lab modules built on top of the core framework.
Lab modules are not part of the core framework and may experience breaking changes or be deprecated in the future.

## What are Lab Modules?

Lab modules are extensions to the core Agent Framework that fall into
one of the following categories:

1. Incubation of new features that may get incorporated by the core framework.
2. Research prototypes built on the core framework.
3. Benchmarks and experimentation tools.

## Lab Modules

- [**gaia**](./gaia/): Evaluate your agents using the GAIA benchmark for general assistant tasks
- [**tau2**](./tau2/): Evaluate your agents using the TAU2 benchmark for customer support tasks
- [**lightning**](./lightning/): RL training for agents using Agent Lightning

## Repository Structure

```
agent-framework-lab/
├── pyproject.toml          # Single package configuration for agent-framework-lab
├── uv.lock                 # Standalone Lab dependency resolution
├── README.md               # This file
├── LICENSE                 # License file
├── namespace/              # Centralized namespace package files
│   └── agent_framework/
│       └── lab/
│           ├── gaia/       # Re-exports from agent_framework_lab_gaia
│           ├── lightning/  # Re-exports from agent_framework_lab_lightning
│           └── tau2/       # Re-exports from agent_framework_lab_tau2
├── gaia/                   # GAIA module implementation
│   └── agent_framework_lab_gaia/
├── lightning/              # Lightning module implementation
│   └── agent_framework_lab_lightning/
└── tau2/                   # TAU2 module implementation
    └── agent_framework_lab_tau2/
```

This structure maintains a single PyPI package `agent-framework-lab` while supporting modular imports through the namespace package mechanism.

## Installation

To install each lab module, use the extras syntax with `pip`:

```bash
pip install "agent-framework-lab[gaia]"
pip install "agent-framework-lab[tau2]"
pip install "agent-framework-lab[lightning]"
```

## Usage

Import and use lab modules from the `agent_framework.lab` namespace.
For example, to use the GAIA module:

```python
# Using GAIA module
from agent_framework.lab.gaia import GAIA
```

## Running Tests Locally

Lab is excluded from the root Python uv workspace so its experimental dependencies do not constrain released
packages. It resolves released Core and provider distributions by default. Create its environment and run its checks
from this directory:

```bash
cd python/packages/lab
uv sync --all-extras --all-groups
uv run poe test
uv run poe pyright
```

Lightning observability tests intentionally exercise heavier tracing paths and are marked as `resource_intensive`:

```bash
uv run pytest lightning/tests/test_lightning.py -m "resource_intensive" -q
```

Lab-only dependency changes update this directory's `uv.lock`, not the root Python workspace lock.

### Depending on new framework APIs

Lab cannot consume unreleased APIs directly from the root workspace. For a change that spans Lab and another Agent
Framework package:

1. Merge and release the Core or provider change first.
2. Update the relevant dependency floor in this `pyproject.toml` after that release is available.
3. Refresh the Lab lock with `uv lock --upgrade-package <distribution-name>`.
4. Implement and validate the Lab change against the published dependency.

For example, release `agent-framework-openai` before using a new OpenAI adapter API from Lab, then update the Lab
dependency and run:

```bash
uv lock --upgrade-package agent-framework-openai
uv sync --all-extras --all-groups
```

Do not add local-path or root-workspace source overrides as a shortcut. Those overrides would make root package
metadata changes affect the Lab lock and reintroduce the dependency coupling this standalone project avoids.

## Should I consume Lab Modules?

If you are looking for stable and production-ready features, you should not use lab modules. Stick to the core framework.

If you are looking for experimentation, research, or want to
benchmark different approaches -- most importantly, if you don't mind breaking changes and potential deprecations --
then lab modules are for you.

## Contributing to Lab Modules

### Microsoft-maintained modules

For Microsoft-maintained modules in this repository, please follow standard contribution guidelines and submit pull requests directly to this repository.

### Community modules

If you want to contribute a community-maintained lab module:

1. Create a new repository on GitHub for your module
2. Tag your repository with `agent-framework-lab` for discoverability
3. Submit a PR to add a link to your repository in the [Lab Modules](#lab-modules) section above
4. Use the PR title format: `[New Lab Module] Your Module Name`

We will review your submission based on the guidelines below.

### Guidelines

1. **Purpose**: Community modules should fit into one of the three categories of lab modules (incubation, research, benchmarks)
2. **Namespace**: Community modules should avoid the `agent_framework.lab` namespace (reserved for modules maintained in this repository)
3. **Dependencies**: Minimize external dependencies, always include `agent-framework` as a base dependency
4. **Documentation**: Include comprehensive README with installation instructions and usage examples
5. **Tests**: Write comprehensive tests with good coverage
6. **Type hints**: Always include type hints and a `py.typed` file
7. **Versioning**: Use semantic versioning, start with `0.1.0` for initial releases
