Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader
Upgrades Python dependencies with automatic breaking change detection.
Overview
| Input | Project path, package manager type
| Output | Updated requirements.txt/pyproject.toml
| Supports | pip, poetry, pipenv
Workflow
See diagram.html for visual workflow.
Phases: Pre-flight → Detect Manager → Security Audit → Check Outdated → Apply Upgrades → Verify Installation → Report
Phase 0: Pre-flight Checks
| requirements.txt OR pyproject.toml OR Pipfile | Yes | Block upgrade
| Virtual environment active | No | Warn user (risk of system pollution)
Workers assume coordinator (ln-710) already verified git state and created backup.
Phase 1: Detect Manager
| pip | requirements.txt
| poetry | pyproject.toml + poetry.lock
| pipenv | Pipfile + Pipfile.lock
Phase 2: Security Audit
Commands
| pip
| pip-audit --json
| poetry
| poetry audit (via plugin)
| pipenv
| pipenv check
Actions
| Critical | Block upgrade, report
| High | Warn, continue
| Moderate/Low | Log only
Phase 3: Check Outdated
Commands
| pip
| pip list --outdated --format=json
| poetry
| poetry show --outdated
| pipenv
| pipenv update --outdated
Phase 4: Apply Upgrades
Commands
| pip
| pip install --upgrade <package>
| pip (freeze)
| pip freeze > requirements.txt
| poetry
| poetry update
| pipenv
| pipenv update
MCP Tools for Migration Search
Priority Order (Fallback Strategy)
| 1 | mcp__context7__query-docs | First choice for library docs
| 2 | mcp__Ref__ref_search_documentation | Official docs and PyPI
| 3 | WebSearch | Latest info, community solutions
Context7 Usage
| 1. Find library | mcp__context7__resolve-library-id | libraryName: "pydantic"
| 2. Query docs | mcp__context7__query-docs | query: "pydantic v1 to v2 migration breaking changes"
MCP Ref Usage
| Search | mcp__Ref__ref_search_documentation | "python pydantic 2 migration guide"
| Read | mcp__Ref__ref_read_url | URL from search results
WebSearch Fallback
Use when Context7/Ref return no results:
-
"<package> python <version> breaking changes migration" -
"<ImportError message> <package> fix"
Phase 5: Verify Installation
Commands
| Import test
| python -c "import <package>"
| Tests
| pytest or python -m pytest
Phase 6: Report Results
Report Schema
| project | Project path
| packageManager | pip, poetry, or pipenv
| duration | Total time
| upgrades[] | Applied upgrades
| verification | PASSED or FAILED
Common Breaking Changes
See breaking_changes_patterns.md for full patterns.
| pydantic | 1 → 2 | V1 compatibility layer needed
| sqlalchemy | 1 → 2 | Query syntax changes
| fastapi | 0.99 → 0.100+ | Pydantic v2 required
Configuration
Options:
# Upgrade scope
upgradeType: major # major | minor | patch
# Security
auditLevel: high
minimumReleaseAge: 14
# Python specific
pythonVersion: "3.12"
useVirtualenv: true
# Verification
runTests: true
Error Handling
| ImportError | Breaking API change | Search Context7/Ref for migration
| Dependency conflict | Version mismatch | Try pip-compile or poetry lock
References
Version: 1.1.0 Last Updated: 2026-01-10