autonomous-api-migration-engineer 0.1.1

Production-grade bootstrap for AI-assisted REST migration planning.

Autonomous API Migration Engineer

AI-assisted platform for analyzing legacy REST services and proposing migrations to gRPC, event-driven architecture, and improved contracts.

This bootstrap is intentionally deterministic: it uses graph-style local agents, sample OpenAPI input, generated protobuf/event schemas, compatibility checks, reports, and tests without requiring paid external APIs.

What Is Included

• FastAPI orchestration API in apps/api_orchestrator
• Interactive React dashboard in apps/web-dashboard
• Multi-agent workflow across scanner, planner, contract generator, verifier, and reporter agents
• OpenAPI v3 parser and sample legacy user-management service
• Generated artifacts with provenance metadata
• Human approval queue model before finalizing generated contracts
• Docker Compose for API, web, PostgreSQL, and Redis
• Unit/integration tests for the happy path
• GitHub Actions CI for Python tests and dashboard builds
• Contribution and changelog docs for collaborators

Quick Start

Install the CLI package:

pip install autonomous-api-migration-engineer

Run an OpenAPI analysis from any project:

migration-engineer analyze \
  --openapi ./openapi.yaml \
  --output-dir ./migration-artifacts

Use it from Python:

from autonomous_api_migration_engineer import run_migration

result = run_migration("openapi.yaml", "migration-artifacts")
print(result["plan"].readiness_score)

Run the FastAPI server after installing:

uvicorn autonomous_api_migration_engineer.api:app --reload --port 8000

Local development setup:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
uvicorn autonomous_api_migration_engineer.api:app --reload --port 8000

Dashboard scaffold:

cd apps/web-dashboard
npm install
npm run dev

Open the dashboard at:

http://localhost:5173

The dashboard is an interactive local demo of the CLI workflow. You can:

• Upload an OpenAPI .json, .yaml, or .yml file.
• Analyze uploaded endpoints directly in the browser.
• Select REST endpoints from the inventory.
• Inspect recommendation rationale, evidence, compatibility score, and contract diff.
• Generate gRPC or event proposals.
• Add review comments.
• Resolve comments.
• Approve proposals.
• See the implementation panel after approval and simulate gRPC implementation output.
• Review Kafka vs RabbitMQ event transport reasoning.
• Watch an agent activity feed update as you interact.

After uploading a file, use the Next action bar:

1. Select a gRPC or Event endpoint from Endpoint Inventory.
2. Click Generate proposal.
3. Add comments if needed.
4. Resolve comments.
5. Approve the proposal.
6. For gRPC endpoints, click Implement gRPC to show generated proto/service/test outputs.

Dashboard Walkthrough

The UI follows the same approval-first migration flow as the CLI, but makes every step visible.

1. Upload And Analyze OpenAPI

Upload an OpenAPI .json, .yaml, or .yml file. The dashboard parses the service name, endpoint paths, HTTP methods, request/response shapes, and response codes locally, then refreshes the endpoint inventory and readiness metrics.

In this example, the uploaded testopenapi.yaml file is recognized as Student API. The UI immediately shows:

• total endpoints discovered,
• gRPC candidates,
• event candidates,
• REST-retained endpoints,
• risk flags,
• migration readiness score,
• the next recommended action.

2. Review Endpoint Inventory

Select any endpoint from Endpoint Inventory to inspect why the system classified it as Keep REST, gRPC, or Event.

The selected endpoint panel shows:

• the migration recommendation,
• evidence from the OpenAPI path,
• compatibility score,
• explainability notes,
• REST-to-target contract diff,
• human approval queue controls.

This is where a developer checks whether the recommendation makes sense before allowing any generated output to move forward.

3. Generate A Proposal

For a gRPC or event candidate, click Generate proposal. The dashboard creates a reviewable proposal and changes the next action message to guide the developer.

The proposal is not treated as final code yet. It is a draft artifact that can receive comments, be revised, and then be approved.

4. Add Comments And Approve

Use Add comment when the proposed contract needs edits. In this example, the developer asks for an idempotency key and validation notes.

After comments are resolved, click Approve. The approval queue records that the proposal has passed review and displays the generated gRPC contract preview.

5. Implement gRPC Scaffold

After approval, click Implement gRPC. The dashboard shows the generated implementation outputs:

• generated_grpc/proto/service.proto,
• generated_grpc/server/service_impl.py,
• tests/test_grpc_mapping.py.

This models the intended product behavior: no generated contract is silently finalized, and implementation only happens after human approval.

Docker:

docker compose -f infra/docker-compose.yml up --build

Demo Workflow

Run the sample workflow:

python -m libs.common.demo examples/sample-openapi/user-management.openapi.json build/artifacts

Interactive migration proposal flow:

migration-engineer analyze --interactive

The command prints each recommendation and asks before creating a proposal:

System: POST /users is a migrate_grpc candidate.
System: Do you want to proceed and generate a proposal? [y/N]

If you answer y, proposal files are written under build/proposals/.

For the included sample service, accepting all actionable recommendations creates:

build/proposals/proposal-post-users.json
build/proposals/proposal-get-users-userid.json
build/proposals/proposal-patch-users-userid-event.json

Reviewing And Approving Proposals

Inspect a proposal:

python3 -m json.tool build/proposals/proposal-post-users.json
python3 -m json.tool build/proposals/proposal-get-users-userid.json
python3 -m json.tool build/proposals/proposal-patch-users-userid-event.json

Add review comments when the generated contract needs changes:

migration-engineer comment \
  --proposal build/proposals/proposal-post-users.json \
  --body "Add idempotency key and validation notes"

Resolve comments into the proposed contract:

migration-engineer resolve-comments \
  --proposal build/proposals/proposal-post-users.json

Approve a gRPC proposal:

migration-engineer approve \
  --proposal build/proposals/proposal-post-users.json

Generate the gRPC implementation scaffold after approval:

migration-engineer implement-grpc \
  --proposal build/proposals/proposal-post-users.json \
  --output-dir build/implementation-post-users

Check generated implementation files:

find build/implementation-post-users -type f

Expected files:

build/implementation-post-users/generated_grpc/__init__.py
build/implementation-post-users/generated_grpc/server/__init__.py
build/implementation-post-users/generated_grpc/proto/user_service.proto
build/implementation-post-users/generated_grpc/server/user_service_impl.py
build/implementation-post-users/tests/test_create_user_grpc_mapping.py

Approve and implement another gRPC endpoint the same way:

migration-engineer approve \
  --proposal build/proposals/proposal-get-users-userid.json

migration-engineer implement-grpc \
  --proposal build/proposals/proposal-get-users-userid.json \
  --output-dir build/implementation-get-user

Event Proposal Review

Event proposals are reviewable artifacts. Inspect the generated event recommendation:

python3 -m json.tool build/proposals/proposal-patch-users-userid-event.json

Look for:

"transport": "kafka"

The event proposal recommends Kafka when the endpoint looks like a durable domain event that benefits from replay, ordering, auditability, and fan-out. It recommends RabbitMQ when the endpoint looks more like task routing, command dispatch, or worker handoff.

Current bootstrap support:

• gRPC proposals support comment, resolve, approve, and implementation scaffold generation.
• Event proposals support AsyncAPI generation and Kafka/RabbitMQ recommendation review.
• Event approval and event implementation scaffolding are planned next steps.

Artifact approval states:

• pending_human_approval: generated by the batch workflow and not accepted by a developer yet.
• needs_review: generated as an explicit proposal and waiting for review.
• changes_requested: developer comments were added and must be resolved.
• approved: developer accepted the proposal; implementation can proceed.
• implemented: generated implementation files and tests were created.

Use analyze --interactive when you want the tool to ask before creating proposals. Use propose-grpc or propose-event when you already know the endpoint you want to convert.

RAG-style local memory:

migration-engineer memory
migration-engineer propose-grpc --endpoint "POST /users"

The implementation step writes successful approved migrations into build/memory/migration-memory.jsonl. Future proposals retrieve similar local cases and include the retrieved cases plus learned adjustments in the proposal basis. This is not model fine-tuning; it is transparent retrieval over prior generated/reviewed artifacts.

Event transport proposal:

migration-engineer propose-event --endpoint "PATCH /users/{userId}"

The event proposal recommends Kafka when the endpoint looks like a durable domain event that benefits from replay, ordering, and fan-out. It recommends RabbitMQ when the endpoint looks more like command dispatch, task routing, or worker handoff.

Generated outputs include:

• endpoint-inventory.json
• migration-plan.json
• contracts/user_service.proto
• events/user-events.asyncapi.json
• compatibility-report.json
• executive-report.md
• adr/0001-contract-migration-strategy.md

Proposal outputs include the basis for the suggestion. The bootstrap does not train agents on private data; it uses deterministic rules over supplied OpenAPI/source evidence and records that basis in the proposal JSON.