Dependency Management - Awesome AI Apps

Efficient dependency management ensures consistent environments across development, testing, and production. This guide covers modern Python dependency management tools and patterns.

pyproject.toml vs requirements.txt

Modern Approach: pyproject.toml

Most projects in the repository use pyproject.toml (PEP 518/621).

[project]
name = "my-ai-agent"
version = "0.1.0"
description = "AI agent for automated tasks"
requires-python = ">=3.10"
dependencies = [
    "agno>=2.3.0",
    "openai>=1.57.0",
    "python-dotenv>=1.0.0",
    "pydantic>=2.10.0",
    "streamlit>=1.45.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "black>=24.0.0",
    "ruff>=0.6.0",
]

[project.urls]
Homepage = "https://github.com/username/project"
Repository = "https://github.com/username/project"

Advantages:

Single source of truth for project metadata
Supports optional dependencies
Better dependency resolution
Standard format (PEP 621)

Legacy Approach: requirements.txt

agno>=2.3.0
openai>=1.57.0
python-dotenv>=1.0.0
pydantic>=2.10.0
streamlit>=1.45.0

Use when:

Working with older projects
Deploying to platforms that only support requirements.txt
Simple scripts without package structure

Installation Tools

pip (Standard)

Built-in Python package installer.

Install from pyproject.toml

# Install in editable mode (development)
pip install -e .

# Install normally (production)
pip install .

# Install with optional dependencies
pip install -e ".[dev]"

Install from requirements.txt

pip install -r requirements.txt

Upgrade All Packages

pip list --outdated
pip install --upgrade package-name

uv (Fast Alternative)

uv is a blazingly fast Python package installer, 10-100x faster than pip.

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Usage

# Install from pyproject.toml (much faster than pip)
uv pip install -e .

# Install from requirements.txt
uv pip install -r requirements.txt

# Install specific package
uv pip install agno

# Install with specific Python version
uv pip install -e . --python python3.11

Performance Comparison:

pip install:  45 seconds
uv pip install:  2 seconds  ✨

Common Dependencies

AI Frameworks

Agno

Most common framework in the repository.

dependencies = [
    "agno>=2.3.0",
]

pip install agno
# or
uv pip install agno

AWS Strands

dependencies = [
    "strands>=0.1.0",
]

LangChain

dependencies = [
    "langchain>=0.3.0",
    "langgraph>=0.2.0",
]

LlamaIndex

dependencies = [
    "llama-index>=0.12.0",
    "llama-index-llms-openai>=0.3.0",
    "llama-index-embeddings-openai>=0.3.0",
]

CrewAI

dependencies = [
    "crewai>=0.70.0",
    "crewai-tools>=0.12.0",
]

Model Providers

dependencies = [
    "openai>=1.57.0",          # OpenAI models
    "anthropic>=0.39.0",       # Claude models  
    "groq>=0.13.0",            # Groq inference
    "litellm>=1.0.0",          # Unified API
]

Vector Databases

dependencies = [
    "lancedb>=0.15.0",         # Embedded vector DB
    "qdrant-client>=1.12.0",   # Qdrant
    "chromadb>=0.5.0",         # ChromaDB
    "pinecone-client>=5.0.0",  # Pinecone
]

Web Tools

dependencies = [
    "scrapegraph-py>=1.0.0",   # ScrapeGraph AI
    "google-search-results>=2.4.0",  # SerpAPI
    "tavily-python>=0.5.0",    # Tavily search
    "playwright>=1.48.0",      # Browser automation
    "beautifulsoup4>=4.12.0",  # HTML parsing
]

Utilities

dependencies = [
    "python-dotenv>=1.0.0",    # Environment variables
    "pydantic>=2.10.0",        # Data validation
    "rich>=13.0.0",            # Terminal formatting
    "streamlit>=1.45.0",       # Web UI
    "fastapi>=0.126.0",        # REST API
    "pyyaml>=6.0.0",           # YAML parsing
]

Dependency Versioning

Version Specifiers

dependencies = [
    "agno",                    # Any version (not recommended)
    "agno==2.3.0",             # Exact version (too strict)
    "agno>=2.3.0",             # Minimum version (recommended)
    "agno>=2.3.0,<3.0.0",      # Version range
    "agno~=2.3.0",             # Compatible release (>=2.3.0, <2.4.0)
]

Recommended Practices

# ✅ Good: Allow patch updates
dependencies = [
    "agno>=2.3.0,<3.0.0",      # Major version locked
    "openai>=1.57.0,<2.0.0",   # Major version locked
]

# ❌ Bad: Too strict or too loose
dependencies = [
    "agno==2.3.0",             # Blocks security patches
    "openai",                  # Unpredictable versions
]

Lock Files

Generate Lock File

Lock files ensure reproducible installs.

Using pip-tools

# Install pip-tools
pip install pip-tools

# Generate lock file from pyproject.toml
pip-compile pyproject.toml -o requirements.lock

# Install from lock file
pip install -r requirements.lock

Using uv

# uv automatically creates uv.lock
uv pip install -e .

# Install from lock file
uv pip sync uv.lock

Development Dependencies

Separate Dev and Prod

[project]
dependencies = [
    # Production dependencies only
    "agno>=2.3.0",
    "openai>=1.57.0",
]

[project.optional-dependencies]
dev = [
    # Development tools
    "pytest>=8.0.0",
    "pytest-cov>=6.0.0",
    "black>=24.0.0",
    "ruff>=0.6.0",
    "mypy>=1.13.0",
]

test = [
    # Test-specific dependencies
    "pytest>=8.0.0",
    "pytest-asyncio>=0.24.0",
    "pytest-mock>=3.14.0",
]

docs = [
    # Documentation tools
    "sphinx>=8.1.0",
    "sphinx-rtd-theme>=3.0.0",
]

Install Optional Dependencies

# Install dev dependencies
pip install -e ".[dev]"

# Install multiple groups
pip install -e ".[dev,test]"

# Install all optional dependencies
pip install -e ".[dev,test,docs]"

Virtual Environment Management

Create Virtual Environment

# Using venv (built-in)
python -m venv .venv

# Using uv (faster)
uv venv

# Specify Python version
uv venv --python python3.11

Activate/Deactivate

# Activate
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Verify activation
which python               # Should show .venv path

# Deactivate
deactivate

Delete Virtual Environment

# Deactivate first
deactivate

# Delete directory
rm -rf .venv

# Recreate
python -m venv .venv
source .venv/bin/activate
pip install -e .

Project Examples

Simple Agent Project

From starter_ai_agents/agno_starter/:

[project]
name = "agno-starter"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "agno",
    "python-dotenv",
]

Advanced Multi-Agent Project

From advance_ai_agents/content_team_agent/:

[project]
name = "content-team-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "agno>=2.3.4",
    "google-search-results>=2.4.2",
    "openai>=2.8.1",
    "serpapi>=0.1.5",
    "python-dotenv>=1.0.0",
    "rich>=13.0.0",
    "trafilatura>=1.6.0",
    "httpx>=0.25.0",
    "sqlalchemy>=2.0.45",
    "fastapi>=0.126.0",
    "streamlit>=1.28.0",
]

RAG Project with Vector DB

From rag_apps/contextual_ai_rag/:

[project]
name = "contextual-rag"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "streamlit>=1.45.0",
    "contextual-ai>=0.1.0",
    "llama-index>=0.12.0",
    "llama-index-llms-nebius>=0.1.0",
    "python-dotenv>=1.0.0",
]

Dependency Conflicts

Resolve Version Conflicts

# Check for conflicts
pip check

# View dependency tree
pip install pipdeptree
pipdeptree

# Show specific package dependencies
pipdeptree -p agno

Fix Conflicts

# If two packages require different versions:
# package-a requires pydantic>=2.0,<3.0
# package-b requires pydantic>=1.10,<2.0

# Option 1: Find compatible versions
dependencies = [
    "package-a>=1.0,<1.5",  # Older version compatible with pydantic 1.x
    "package-b>=2.0",
    "pydantic>=1.10,<2.0",
]

# Option 2: Update to packages that use same version
dependencies = [
    "package-a>=2.0",       # Newer version uses pydantic 2.x
    "package-b>=3.0",       # Updated version
    "pydantic>=2.0,<3.0",
]

Updating Dependencies

Check for Updates

# List outdated packages
pip list --outdated

# Using pip-check
pip install pip-check
pip-check

Update Safely

# Update specific package
pip install --upgrade agno

# Update with constraints
pip install --upgrade "agno>=2.3.0,<3.0.0"

# Test after update
pytest

Update Lock File

# Regenerate lock file
pip-compile --upgrade pyproject.toml -o requirements.lock

# Or with uv
uv pip install --upgrade -e .

Best Practices

1. Pin Production Dependencies

# Generate exact versions for production
pip freeze > requirements-prod.lock

# Deploy with exact versions
pip install -r requirements-prod.lock

2. Separate Requirements Files

requirements/
├── base.txt          # Core dependencies
├── dev.txt           # Development tools
├── prod.txt          # Production-only
└── test.txt          # Testing dependencies

# requirements/dev.txt
-r base.txt          # Include base requirements
pytest>=8.0.0
black>=24.0.0
ruff>=0.6.0

3. Use .gitignore

# Python
.venv/
venv/
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# Dependencies
uv.lock
requirements.lock

4. Document Dependencies

Create DEPENDENCIES.md:

# Dependencies

## Core
- `agno` - AI agent framework
- `openai` - OpenAI API client

## Optional
- `streamlit` - Web UI (only if using app.py)
- `pytest` - Testing (only for development)

## Installation

```bash
# Production
pip install -e .

# Development
pip install -e ".[dev]"

---

## Common Issues

### Dependency Not Found

```bash
# Update pip
pip install --upgrade pip

# Clear cache
pip cache purge

# Reinstall
pip install --no-cache-dir agno

Conflicting Dependencies

# Create fresh virtual environment
deactivate
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -e .

Slow Installation

# Use uv instead of pip (10-100x faster)
uv pip install -e .

# Or use pip with binary packages only
pip install --only-binary :all: -e .

Migration Guide

From requirements.txt to pyproject.toml

# Install tool
pip install requirements-to-pyproject

# Convert
requirements-to-pyproject requirements.txt

Manual conversion:

# requirements.txt
agno>=2.3.0
openai>=1.57.0
python-dotenv>=1.0.0

# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "agno>=2.3.0",
    "openai>=1.57.0",
    "python-dotenv>=1.0.0",
]

Deployment

Docker

FROM python:3.11-slim

WORKDIR /app

# Copy dependency files
COPY pyproject.toml ./

# Install dependencies
RUN pip install --no-cache-dir -e .

# Copy application
COPY . .

CMD ["python", "main.py"]

Cloud Platforms

Most platforms support requirements.txt:

# Generate from pyproject.toml
pip-compile pyproject.toml -o requirements.txt

# Deploy with requirements.txt

Next Steps

Environment Setup

Set up complete development environment

API Keys

Configure credentials for dependencies

Best Practices

Production-ready patterns and code quality

Multi-Agent Patterns

Start building with installed dependencies

Frameworks

Patterns

Development

​pyproject.toml vs requirements.txt

​Modern Approach: pyproject.toml

​Legacy Approach: requirements.txt

​Installation Tools

​pip (Standard)

​Install from pyproject.toml

​Install from requirements.txt

​Upgrade All Packages

​uv (Fast Alternative)

​Install uv

​Usage

​Common Dependencies

​AI Frameworks

​Agno

​AWS Strands

​LangChain

​LlamaIndex

​CrewAI

​Model Providers

​Vector Databases

​Web Tools

​Utilities

​Dependency Versioning

​Version Specifiers

​Recommended Practices

​Lock Files

​Generate Lock File

​Using pip-tools

​Using uv

​Development Dependencies

​Separate Dev and Prod

​Install Optional Dependencies

​Virtual Environment Management

​Create Virtual Environment

​Activate/Deactivate

​Delete Virtual Environment

​Project Examples

​Simple Agent Project

​Advanced Multi-Agent Project

​RAG Project with Vector DB

​Dependency Conflicts

​Resolve Version Conflicts

​Fix Conflicts

​Updating Dependencies

​Check for Updates

​Update Safely

​Update Lock File

​Best Practices

​1. Pin Production Dependencies

​2. Separate Requirements Files

​3. Use .gitignore

​4. Document Dependencies

​Conflicting Dependencies

​Slow Installation

​Migration Guide

​From requirements.txt to pyproject.toml

​Deployment

​Docker

​Cloud Platforms

​Next Steps

Environment Setup

API Keys

Best Practices

Multi-Agent Patterns

Build docs developers (and LLMs) love

pyproject.toml vs requirements.txt

Modern Approach: pyproject.toml

Legacy Approach: requirements.txt

Installation Tools

pip (Standard)

Install from pyproject.toml

Install from requirements.txt

Upgrade All Packages

uv (Fast Alternative)

Install uv

Usage

Common Dependencies

AI Frameworks

Agno

AWS Strands

LangChain

LlamaIndex

CrewAI

Model Providers

Vector Databases

Web Tools

Utilities

Dependency Versioning

Version Specifiers

Recommended Practices

Lock Files

Generate Lock File

Using pip-tools

Using uv

Development Dependencies

Separate Dev and Prod

Install Optional Dependencies

Virtual Environment Management

Create Virtual Environment

Activate/Deactivate

Delete Virtual Environment

Project Examples

Simple Agent Project

Advanced Multi-Agent Project

RAG Project with Vector DB

Dependency Conflicts

Resolve Version Conflicts

Fix Conflicts

Updating Dependencies

Check for Updates

Update Safely

Update Lock File

Best Practices

1. Pin Production Dependencies

2. Separate Requirements Files

3. Use .gitignore

4. Document Dependencies

Conflicting Dependencies

Slow Installation

Migration Guide

From requirements.txt to pyproject.toml

Deployment

Docker

Cloud Platforms

Next Steps