# JDD-Agent OS

> **The MCP-native evolution control plane for AI agents.**

JDD discovers what to change in an agent, tests the change, governs it, versions it, and promotes the next better agent. It integrates with the existing `LocalLLM-MCP` service as its first model substrate without modifying it. It boots in **DEMO mode** (no real LLM required) and auto-switches to **LIVE mode** when any LocalLLM-MCP model port is reachable.

---

## Quick Start

```powershell
# 1. Clone / open the workspace
cd "C:\JDD-Agent OS"

# 2. Install dependencies
pip install -e ".[dev]"

# 3. Configure environment
cp .env.example .env    # edit as needed

# 4. Run DB migrations
alembic upgrade head

# 5. Start the backend
uvicorn backend.app.main:app --port 9000 --reload

# 6. Open the API docs
start http://localhost:9000/docs
```

---

## Port Map

| Service | Port | Notes |
|---|---|---|
| JDD Backend (FastAPI + MCP server) | **9000** | `uvicorn backend.app.main:app --port 9000` |
| JDD Frontend (Vite dev) | **5173** | `cd frontend && npm run dev` |
| IBM Granite 4.1 3B | **8080** | LocalLLM-MCP (independent MCP server) |
| NVIDIA Nemotron-3 Nano 4B | **8081** | LocalLLM-MCP |
| Google Gemma-4 4B | **8082** | LocalLLM-MCP |
| Alibaba Qwen 2.5 Coder 3B | **8083** | LocalLLM-MCP |
| Meta Llama 3.2 3B | **8084** | LocalLLM-MCP |

---

## Key Endpoints

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/system/health` | Health check |
| GET | `/api/v1/system/status` | System status + mode |
| GET | `/docs` | Interactive Swagger UI |

---

## Project Layout

```
backend/app/        FastAPI application (config, database, models, schemas, api, …)
backend/tests/      Unit, integration, and e2e tests
frontend/           React 18 + TypeScript + Vite + Tailwind frontend
alembic/            SQLAlchemy migrations
data/               Seed YAML (agents, benchmarks, strategies)
cli/                Click-based CLI (jdd)
docs/               Architecture & design docs
```

---

## Demo Mode

JDD starts in **DEMO mode** — no real LLM is required. It probes ports 8080–8084 every 30 s; if any LocalLLM-MCP server responds to `llm.health`, the system automatically switches to **LIVE mode**. All demo scores are labelled `[DEMO - simulated scores]` and are never presented as real benchmark results.

---

## Development

```powershell
# Run tests
pytest backend/tests

# Lint / format
ruff check .
ruff format .

# Generate a new DB migration after changing models
alembic revision --autogenerate -m "describe change"
alembic upgrade head
```