AgentForge is an AI workspace that analyzes FastAPI repositories, generates pytest tests, runs them, analyzes failures, and produces repair plans with Cursor prompts.

AgentForge automates the workflow of:

1. Repository Analysis — Intake and parse FastAPI codebases
2. Test Strategy — Design test strategy and coverage map
3. Test Generation — Generate pytest tests based on repository structure and API definitions
4. Test Execution — Run generated tests and capture results
5. Failure Analysis — Analyze test failures and identify root causes (including test assumption vs. repo bugs)
6. Refinement — Decide whether to loop for test refinement or proceed to repair
7. Repair Planning — Produce actionable repair plans to fix failing tests
8. Prompt Generation — Generate Cursor prompts for the repair plan

• Backend — FastAPI application providing APIs for repository intake, orchestration, agent invocation, and test execution
• Frontend — Next.js 16 application for workspace presentation, run management, and artifact inspection
• Engines — Repository parsing, knowledge graph, retrieval, context building, agent reasoning (Nova/Bedrock), and test execution

Architecture documents are in /engines — individual engine specifications and audit reports.

AgentForge/
├── backend/              # FastAPI application
│   ├── app/
│   │   ├── api/          # API routes (repos, runs)
│   │   ├── config/       # Configuration
│   │   ├── db/           # Database setup
│   │   ├── services/     # Orchestration, execution, agents
│   │   ├── utils/        # Agent engine, context builder, memory
│   │   └── main.py
│   ├── data/             # Repos, runs, database (auto-created)
│   └── requirements.txt
├── frontend/             # Next.js application
│   ├── app/              # Pages (home, repo, run)
│   ├── components/       # Sidebar, workspace tabs, pipeline monitor
│   └── lib/              # API client
└── engines/              # Engine specification documents

• Python 3.10+
• Node.js 18+
• AWS credentials (for Bedrock/Nova)

# From project root
cd backend
pip install -r requirements.txt

# Create .env (copy from .env.example if available, or create with):
# APP_NAME=AgentForge
# APP_ENV=development
# DATA_DIR=backend/data
# REPO_STORAGE_PATH=backend/data/repos
# RUN_STORAGE_PATH=backend/data/runs
# LOG_DIR=backend/logs
# BEDROCK_REGION=us-east-1
# NOVA_TEXT_MODEL_ID=us.amazon.nova-micro-v1:0
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_DEFAULT_REGION=us-east-1

# Run the server (from project root)
uvicorn backend.app.main:app --reload

API: http://localhost:8000

• GET / — Root
• GET /health — Health check
• GET /docs — OpenAPI docs
• /repos — Repository import, parse, graph
• /runs — Run init, orchestration, agents, execution

# From project root
cd frontend
npm install
npm run dev

UI: http://localhost:3000

• Home — Create project, start run, recent projects/runs
• Repo page — Repository details and artifacts
• Run page — Pipeline monitor, artifact tabs (repo analysis, test strategy, generated tests, execution results, failure analysis, repair plan, cursor prompt), terminal output

Create .env in the project root (see .env.example if present). Required for Bedrock:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_DEFAULT_REGION (e.g. us-east-1)
• BEDROCK_REGION
• NOVA_TEXT_MODEL_ID (e.g. us.amazon.nova-micro-v1:0)

See repository for license information.