dev-agent/README.md

Universal Dev Agent

The Universal Dev Agent converts natural-language user requirements into validated, structured, platform-independent Agent Specs.

It acts as an interactive builder, allowing developers and end-users to design workflows, map connections, resolve dependency chains, and validate agent schemas through conversational chat and APIs.

---

Quick Start

1. Recreate Environment & Install

Ensure you have Python 3.12 installed:

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Apply Migrations

Initialize SQLite database tables:

python -m alembic upgrade head

3. Run FastAPI Server

uvicorn app.main:app --reload

API Documentation: http://localhost:8000/docs

4. Run Conversational CLI

python -m app.cli

---

Repository Map

dev-agent/
│
├── app/
│   ├── main.py                     # FastAPI server entry point
│   ├── cli.py                      # Stateful interactive CLI
│   │
│   ├── api/                        # API router and session routes
│   │
│   ├── core/                       # App settings, logging config
│   │
│   ├── db/                         # SQLite connection and SQLAlchemy schemas
│   │
│   ├── schemas/                    # Pydantic schemas (AgentSpec, validation)
│   │
│   ├── agents/                     # LangGraph workflow, nodes, and states
│   │
│   ├── validators/                 # Validation layer (Schema, Workflow, Conflict)
│   │
│   └── services/                   # Business services (Validation, LLM with fallback)
│
├── tests/                          # 20+ automated test cases
└── alembic/                        # Database migration scripts

---

Running Automated Tests

Run the test suite with Python's UTF-8 mode enabled on Windows:

$env:PYTHONUTF8=1; python -m pytest

---

Detailed Documentation

• ARCHITECTURE.md: Architectural layout, LangGraph state machine, and validator pipeline details.
• AGENT_SPEC.md: Fields and structure layout of the platform-agnostic specification.
• API.md: FastAPI REST endpoints, JSON payloads, and response models.
• DEVELOPMENT.md: Local developer setup, migration workflow, and testing details.