Metadata-Version: 2.4
Name: migration-agent
Version: 0.1.0a1
Summary: Evidence-backed dependency migration assistant (experimental alpha)
Keywords: migration,refactoring,dependency,upgrade
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Migration Agent (experimental alpha)

> **This is an experimental alpha release (`0.1.0a1`).** It is a research
> prototype for exploring evidence-backed dependency migration assistance. It
> does **not** perform fully autonomous migration of arbitrary repositories.

## What it is

Migration Agent analyses a Python repository and assists with upgrading a
pinned dependency from one major version to another. It walks a fixed,
auditable pipeline:

```
MigrationSpec (discovery)
  → Migration Knowledge (static registry + dynamic web acquisition)
  → Affected-Code Discovery (AST-assisted usage search)
  → Planning (one action per usage, with an explicit strategy)
  → Transformation (mechanical edits in a working copy; original untouched)
  → Validation (syntax, residual old-usage, target-usage, test suite)
  → Completeness (every usage gets a disposition)
  → Report (evidence-preserving MigrationReport)
```

The package's only runtime requirement is the Python standard library.

## Problem it addresses

Major-version upgrades (e.g. Pydantic 1.x → 2.x) rename, remove, or subtly
change APIs. Doing such an upgrade by hand means: reading the migration
guide, finding every affected call site, editing each one, and verifying
nothing was missed. Migration Agent mechanises that loop while keeping every
claim traceable to cited documentation.

## Key ideas

- **Dynamic migration knowledge acquisition.** For version paths without a
  built-in rule set, the agent searches the web for official migration
  documentation (preferring authoritative sources), fetches the pages, and
  extracts `MigrationChange` objects from the page bodies. Search snippets
  are never used as evidence.
- **Evidence-backed migration changes.** Every `MigrationChange` carries an
  `Evidence` record (document, section, verbatim excerpt, URL), preserved all
  the way through to the final `MigrationReport`.
- **Safety behaviour.** The original repository is never modified; edits
  happen in a working copy. Unknown versions produce an explicit
  `unsupported` result instead of fabricated knowledge. Ambiguous usages are
  planned as `LLM_ASSISTED` and left pending rather than guessed at.
- **Completeness accounting.** Every discovered usage receives a disposition
  (`MIGRATED`, `NOT_MIGRATED`, `SKIPPED`, `FAILED`, `MANUAL_REVIEW`) and the
  overall outcome (`SUCCESS`, `PARTIALLY_MIGRATED`, `BLOCKED`, `FAILED`,
  `NO_MIGRATION_REQUIRED`) is derived from those dispositions.

## Capabilities (current)

- Repository discovery: finds `pyproject.toml`, `requirements.txt`,
  `requirements/*.txt`, `setup.py`, `setup.cfg` dependency metadata.
- Version evidence: exact pins (`==`) determine the source version;
  non-exact constraints are reported as "unknown" rather than guessed.
- Static evidence-backed knowledge for **Pydantic 1.x → 2.x** (a
  representative subset of the official migration guide).
- Dynamic web knowledge for other technology/version paths via a
  standard-library search/fetch backend (injectable for tests via
  `set_backend()`).
- AST-assisted affected-usage discovery, per-usage planning, mechanical
  transformation of exact matches, syntax/residual/target/test validation,
  completeness verification, and report generation.

## Current limitations (read before using)

- **Knowledge-source verification still needs strengthening.** The dynamic
  backend can accept documentation from a different project with a similar
  name when it ranks highly (observed: Django REST Framework release notes
  returned for a Django query). Cross-project results must be checked.
- **Some transformations are deferred as `LLM_ASSISTED`.** Text-only
  (non-AST-confirmed) usages are deliberately left pending; the executor
  does not guess. Behaviour-only changes without exact code patterns are not
  discovered as usages.
- **Documented M3/M8 end-to-end limitations:** multi-file migrations may be
  partial; text matches inside strings/docstrings can be flagged as
  candidate usages; exact-match transformation can fail on conflicting
  patterns (see `E2E_TEST_SUMMARY.md` in the source repository).
- **Behavioural migration changes may require additional
  knowledge/extraction support** beyond the current exact-pattern machinery.

## Installation

```bash
pip install migration-agent
```

Requires Python 3.12 or newer. There are no runtime dependencies.

## Minimal usage

The package exposes a library API (there is no command-line interface):

```python
from pathlib import Path
from migration_agent import (
    acquire_migration_knowledge,
    create_migration_plan,
    discover_affected_usages,
    discover_migration,
    execute_transformation_plan,
    execute_validation,
    generate_report,
    verify_completeness,
)

repo = Path("./my-repo")
spec = discover_migration(repo, technology="pydantic", target_version="2")
print("source:", spec.source_version, "target:", spec.target_version)

knowledge = acquire_migration_knowledge(spec)
print("supported:", knowledge.supported)
if not knowledge.supported:
    print("reason:", knowledge.reason)
else:
    usages = discover_affected_usages(repo, knowledge.changes)
    plan = create_migration_plan(spec, knowledge.changes, usages)
    result = execute_transformation_plan(repo, plan)
    validation = execute_validation(result.working_copy, usages, knowledge.changes)
    completeness = verify_completeness(spec, usages, plan, result, validation)
    report = generate_report(completeness)
    print("outcome:", report.outcome)
```

For a fully worked offline example using a deterministic injected backend,
see `examples/dynamic_knowledge_demo.py --mock` in the source repository.
