Generate AI

Read from $MIGRATION_DIR/:

• aws-design-ai.json (REQUIRED) — AI architecture design from Phase 3
• estimation-ai.json (REQUIRED) — AI cost estimates from Phase 4
• ai-workload-profile.json (REQUIRED) — AI workload profile from Phase 1
• preferences.json (REQUIRED) — User migration preferences from Phase 2

If any required file is missing: STOP. Output: “Missing required artifact: [filename]. Complete the prior phase that produces it.”

Part 1: Fast-Track Timeline

Check preferences.json → ai_constraints.ai_framework to determine the migration path. Describe effort by MECHANISM (what changes, how many files/lines) and duration by PHASE SEQUENCE — never calendar week/hour estimates (uncalibrated; see shared/migration-complexity.md § Provenance):

Gateway users (config-only path — shortest) — ai_framework includes llm_router, api_gateway, voice_platform, or framework:

OpenAI SDK users via Mantle (config path for a Responses source; small reshape for a Chat Completions source) — ai_framework = direct AND ai_source = openai AND migration_path starts with mantle (mantle, mantle_openai_responses):

• Point the client at https://bedrock-mantle.{region}.api.aws/openai/v1 — note the openai/v1 segment for proprietary GPT models; a bare /v1 404s
• Swap the credential for a Bedrock API key or the auto-refreshing token provider — not the existing OpenAI key
• Update the model string to the Bedrock model ID (openai.gpt-* for a same-model move)
• Grant the bedrock-mantle:* actions; bedrock:InvokeModel does not authorize these models
• Config-only ONLY if the source already calls responses.create. A Chat Completions source must reshape to Responses — small and mechanical, but it is a code change, so do not present this path as “no code changes” without checking the detected surface
• Test in staging, validate responses

Match the migration_path prefix, not the exact string: Design writes the more specific mantle_openai_responses for a same-model OpenAI migration, and an equality test against mantle would misroute those runs into the adapter path below.

Direct SDK users (adapter path — the long pole) — ai_framework = direct AND (ai_source != openai OR migration_path = converse):

• Phase 1: Enable Bedrock access, create IAM role, develop provider adapter with feature flag, unit test
• Phase 2: Deploy to staging, run A/B comparison, measure latency/quality/cost, tune prompts
• Phase 3: Gradual rollout (10% → 50% → 100%), monitor, disable source provider after 48h stable

Duration drivers: multiple models (adapter + evaluation per model), framework integration, custom inference pipeline (the longest driver), and — when alongside infra migration — alignment with the infra deployment stage.

Part 2: Step-by-Step Migration Guide

Based on ai-workload-profile.json → integration.pattern and integration.languages, generate SDK migration examples.

Migration patterns to include (matched to detected language and source):

For each detected language and pattern, generate before/after code examples using actual model IDs from aws-design-ai.json.

Include streaming migration (converse_stream) if capabilities_summary.streaming = true.

Include embeddings migration (Titan Embeddings v2 via invoke_model) if capabilities_summary.embeddings = true.

Part 3: Rollback Plan

Feature flag strategy: AI_PROVIDER env var controls routing:

• vertex_ai (default) — existing provider
• bedrock — switch to Bedrock
• shadow — send to both, return source response (for comparison)

Rollback triggers: quality below threshold, P95 latency > 2x baseline, error rate > 1% for 5 min, cost per request > 3x source.

Rollback steps: Set AI_PROVIDER=vertex_ai (instant), verify source traffic, monitor 1 hour, investigate, re-attempt.

Part 4: Monitoring and Observability

Key metrics and alert thresholds:

Dashboard panels: Request volume by provider, latency comparison (P50/P95/P99), error rates, token usage, cost tracking, quality scores.

Part 5: Production Readiness Checklist

• Not done: Bedrock model access enabled
• Not done: IAM role with bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream
• Not done: Provider adapter deployed and tested in staging
• Not done: A/B test with >= 100 representative prompts
• Not done: Response quality >= 90% of source baseline
• Not done: Latency P95 within 2x of source baseline
• Not done: Error rate < 0.1% in staging
• Not done: Monitoring dashboards and alerting active
• Not done: Rollback procedure documented and tested
• Not done: Cost estimates validated against staging usage

Part 6: Success Criteria

Output

Write generation-ai.json to $MIGRATION_DIR/.

Schema — top-level fields:

Validation Checklist

• Not done: migration_plan.models_to_migrate covers all models from aws-design-ai.json
• Not done: step_by_step_guide.languages matches ai-workload-profile.json languages
• Not done: step_by_step_guide.files_to_modify matches aws-design-ai.json code_migration
• Not done: rollback_plan.mechanism is "feature_flag"
• Not done: success_criteria covers quality, latency, and cost

Generate Phase Integration

The parent orchestrator (generate.md) uses generation-ai.json to:

1. Gate Stage 2 artifact generation — generate-artifacts-ai.md requires this file
2. Provide AI migration context to generate-artifacts-docs.md for MIGRATION_GUIDE.md
3. Set phase completion status in .phase-status.json

Part 7: Generate STARTUP_PROGRAMS.md

Always generate $MIGRATION_DIR/STARTUP_PROGRAMS.md when preferences.json contains ai_monthly_spend or startup_program_status. This artifact summarizes applicable AWS startup programs based on Q27 (startup_program_status) and workload type — not GCP or AI spend bands alone.

Content rules (all amounts from AWS official sources only):

Generation rules:

• Always include the Activate decision table (both Founders and Portfolio rows).
• Only include the Generative AI Accelerator section when ai_monthly_spend is "$2K-$10K" or ">$10K" AND agentic_profile.is_agentic == true
• If startup_program_status.value == "has_credits": replace the “Apply for AWS Activate” steps with “You already have AWS Activate credits — ensure they are applied to your account before running terraform apply”
• If startup_program_status.value == "unknown": never write your status: eligible_founders, your status: eligible_portfolio, or “Eligible Founders tier” in this file or the migration report — use neutral copy per the unknown branch above
• If startup_program_status.value == "eligible_founders": may recommend Founders specifically; still mention Portfolio exists for VC-backed teams
• If startup_program_status.value == "eligible_portfolio": may recommend Portfolio specifically; still mention Founders for self-funded teams
• Do NOT include any credit amounts not sourced from official AWS pages (aws.amazon.com)
• Do NOT reference MAP, IW Migrate, or ISV Workload Migration Program — these are enterprise/partner programs, not startup self-service paths
• After writing, run scripts/validate-startup-program-artifacts.py with --migration-dir $MIGRATION_DIR (see validate-artifacts.md check 16)