How ai-agent-book Manages Dependencies with uv and pyproject.toml Optional-Dependencies

The ai-agent-book project leverages PEP 621-style pyproject.toml to declare modular optional-dependency groups (extras) that the uv package manager resolves into platform-specific lockfiles, enabling lightweight core installations and reproducible chapter-level environments.

The bojieli/ai-agent-book repository demonstrates modern Python dependency management by combining standardized project metadata with high-performance tooling. Instead of maintaining multiple requirements.txt files, the project centralizes its dependency graph in a single pyproject.toml while using uv to handle complex resolution scenarios. This architecture allows readers to install only the libraries required for specific chapters or experiments.

Core and Optional Dependency Structure

The project's pyproject.toml defines runtime requirements using PEP 621 fields, separating minimal core dependencies from feature-specific extras.

Core Requirements

The [project] dependencies array lists packages essential for all functionality. According to lines 19-30 of pyproject.toml, these include openai, pydantic, python-dotenv, and requests. These dependencies install by default with any package consumption method.

Optional Dependency Groups

Under [project.optional-dependencies], the project organizes related libraries into semantic groups:

• viz: Visualization libraries including matplotlib, pandas, and seaborn (lines 60-70)
• docs: Document processing tools such as pypdf, PyPDF2, and python-docx (lines 72-84)
• media: Image and video handling via pillow and opencv-python (lines 87-91)
• web: HTTP operations with aiohttp, beautifulsoup4, and playwright (lines 94-102)
• browser: Browser automation agents that depend on the web extra (lines 105-110)
• serve: FastAPI service dependencies (lines 112-117)

Composable Chapter Aggregates

The project creates higher-level aggregates that reference multiple base extras for specific chapters. For example, ch1 requires only visualization and document handling, while ch2 pulls in visualization, documents, web, serving, and ML providers:

[project.optional-dependencies]
ch1 = ["agentbook[viz,docs]"]
ch2 = ["agentbook[viz,docs,web,serve,providers,tokens,torch]"]

This composability prevents dependency bloat while maintaining explicit chapter-level contracts.

How uv Resolves and Locks Dependencies

The uv tool reads configuration from the [tool.uv] section to generate deterministic lockfiles that respect platform constraints and package incompatibilities.

Handling Package Conflicts

The repository explicitly declares that the unsloth extra (for Linux GPU fine-tuning) cannot coexist with the vllm extra (for Linux GPU inference) because they pin incompatible transformers versions. This conflict is defined under [tool.uv] conflicts (lines 38-46), preventing uv from creating invalid environments.

Platform-Specific Environments

Uv generates separate lockfiles for macOS (ARM), Linux (x86_64), and Windows (lines 48-54), ensuring each platform receives a compatible dependency resolution without manual specification.

Installation Workflows and Commands

Users interact with the dependency system through uv commands or standard pip syntax.

To install only the dependencies needed for Chapter 1:

uv sync --extra ch1

For the full GPU fine-tuning stack on Linux:

uv sync --extra unsloth

Non-uv users can achieve similar results using pip with extras notation:

pip install -e ".[ch1]"

However, pip performs fresh resolution rather than utilizing uv's pre-generated lockfile.

Summary

• The project centralizes dependency definitions in pyproject.toml using PEP 621 optional-dependencies
• Extras like viz, docs, and web group related libraries while chapter aggregates (e.g., ch1, ch2) compose these for specific use cases
• uv generates platform-specific lockfiles and enforces conflict rules (e.g., unsloth vs vllm incompatibility)
• Installation granularity ranges from minimal core packages to full chapter environments using uv sync --extra <name>

Frequently Asked Questions

What is the difference between core and optional dependencies in ai-agent-book?

Core dependencies listed under [project] dependencies in pyproject.toml install with every package usage and include fundamental libraries like openai and pydantic. Optional dependencies are organized into extras groups under [project.optional-dependencies] that users must explicitly request via uv sync --extra <group> or pip install -e ".[<group>]", keeping the base installation lightweight.

Why does uv prevent installing unsloth and vllm extras together?

According to the [tool.uv] conflicts section in pyproject.toml (lines 38-46), the unsloth extra (Linux GPU fine-tuning) and vllm extra (Linux GPU inference) declare conflicting version pins for the transformers library. Uv enforces this mutual exclusivity during resolution to prevent runtime version incompatibilities.

How do I install dependencies for a specific chapter without uv?

Users can install chapter-specific dependencies using standard pip with extras notation: pip install -e ".[ch1]" or pip install -e ".[ch2]". While this installs the same package sets defined in pyproject.toml, pip resolves dependencies dynamically rather than using uv's pre-generated lockfile, potentially yielding different versions.

Where are the dependency definitions stored in the repository?

All dependency specifications reside in the root pyproject.toml file. Core requirements appear under [project] dependencies, optional groups under [project.optional-dependencies], and uv-specific configuration (conflicts and environment targets) under [tool.uv]. Some chapters may include supplementary requirements.txt files for experiments requiring isolated environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}