ln-713-pip-upgrader

| Aspect | Details |

|--------|---------|

| Input | Project path, package manager type |

| Output | Updated requirements.txt/pyproject.toml |

| Supports | pip, poetry, pipenv |

---

See [diagram.html](diagram.html) for visual workflow.

Phases: Pre-flight → Detect Manager → Security Audit → Check Outdated → Apply Upgrades → Verify Installation → Report

---

| Check | Required | Action if Missing |

|-------|----------|-------------------|

| 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.

---

| Manager | Indicator Files |

|---------|-----------------|

| pip | requirements.txt |

| poetry | pyproject.toml + poetry.lock |

| pipenv | Pipfile + Pipfile.lock |

---

Commands

| Manager | Command |

|---------|---------|

| pip | pip-audit --json |

| poetry | poetry audit (via plugin) |

| pipenv | pipenv check |

Actions

| Severity | Action |

|----------|--------|

| Critical | Block upgrade, report |

| High | Warn, continue |

| Moderate/Low | Log only |

---

Commands

| Manager | Command |

|---------|---------|

| pip | pip list --outdated --format=json |

| poetry | poetry show --outdated |

| pipenv | pipenv update --outdated |

---

Commands

| Manager | Command |

|---------|---------|

| pip | pip install --upgrade |

| pip (freeze) | pip freeze > requirements.txt |

| poetry | poetry update |

| pipenv | pipenv update |

---

Priority Order (Fallback Strategy)

| Priority | Tool | When to Use |

|----------|------|-------------|

| 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

| Step | Tool | Parameters |

|------|------|------------|

| 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

| Action | Tool | Query Example |

|--------|------|---------------|

| 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:

• " python breaking changes migration"
• " fix"

---

Commands

| Check | Command |

|-------|---------|

| Import test | python -c "import " |

| Tests | pytest or python -m pytest |

---

Report Schema

| Field | Description |

|-------|-------------|

| project | Project path |

| packageManager | pip, poetry, or pipenv |

| duration | Total time |

| upgrades[] | Applied upgrades |

| verification | PASSED or FAILED |

---

> See [breaking_changes_patterns.md](../ln-710-dependency-upgrader/references/breaking_changes_patterns.md) for full patterns.

| Package | Breaking Version | Key Changes |

|---------|------------------|-------------|

| pydantic | 1 → 2 | V1 compatibility layer needed |

| sqlalchemy | 1 → 2 | Query syntax changes |

| fastapi | 0.99 → 0.100+ | Pydantic v2 required |

---

```yaml

Options:

# Upgrade scope

upgradeType: major # major | minor | patch

# Security

auditLevel: high

minimumReleaseAge: 14

# Python specific

pythonVersion: "3.12"

useVirtualenv: true

# Verification

runTests: true

```

---

| Error | Cause | Solution |

|-------|-------|----------|

| ImportError | Breaking API change | Search Context7/Ref for migration |

| Dependency conflict | Version mismatch | Try pip-compile or poetry lock |

---

• [breaking_changes_patterns.md](../ln-710-dependency-upgrader/references/breaking_changes_patterns.md)
• [python_venv_handling.md](references/python_venv_handling.md)

---

Version: 1.1.0

Last Updated: 2026-01-10