python-package-management

name	python-package-management
description	Guide for managing packages in the Agent Framework Python monorepo, including creating new connector packages, versioning, and the lazy-loading pattern. Use this when adding, modifying, or releasing packages.

Python Package Management

Monorepo Structure

python/
├── pyproject.toml              # Root package (agent-framework)
├── packages/
│   ├── core/                   # agent-framework-core (main package)
│   ├── foundry/                # agent-framework-foundry
│   ├── anthropic/              # agent-framework-anthropic
│   └── ...                     # Other connector packages

• agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
• Provider packages extend core with specific integrations
• Root agent-framework depends on agent-framework-core[all]

Dependency Management

Uses uv for dependency management and poethepoet for task automation.

# Full setup (venv + install + prek hooks)
uv run poe setup

# Install dependencies from lockfile (frozen resolution with prerelease policy)
uv run poe install

# Create venv with specific Python version
uv run poe venv --python 3.12

# Intentionally upgrade a specific dependency to reduce lockfile conflicts
uv lock --upgrade-package <dependency-name> && uv run poe install

# Refresh exact development dependency-group pins, lockfile, and validation in one run
uv run poe upgrade-dev-dependencies

# Release cuts: refresh uv.lock and probe changed packages at both bound extremes.
# The release probe has a shared five-minute deadline.
uv run poe validate-python-release --base-ref upstream/main


uv run poe validate-dependency-bounds-test

uv run poe validate-dependency-bounds-test --package core


uv run poe validate-dependency-bounds-project --mode both --package core --dependency 


uv run poe validate-dependency-bounds-project --mode upper --package 


uv run poe add-dependency-and-validate-bounds --package core --dependency