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

# 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

# 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