Evolutionary Idea Lab

Local-first system for interactive idea generation and refinement with an evolutionary algorithm + LLM generator/critic agents.

Stack

• Backend: Python + FastAPI + SQLite (uv workflow)
• Frontend: React + TypeScript + Vite (bun workflow)
• LLM provider: OpenRouter chat completions API

Project Layout

• /Users/mishaaghamalyan/Development/personal/evolv/backend FastAPI backend
• /Users/mishaaghamalyan/Development/personal/evolv/frontend React frontend
• /Users/mishaaghamalyan/Development/personal/evolv/data SQLite DB, project artifacts, checkpoints, exports

Backend (uv)

1. Install deps

cd /Users/mishaaghamalyan/Development/personal/evolv/backend
uv sync

2. Optional OpenRouter config

export EVOLV_OPENROUTER_API_KEY="your_key"

If no key is set, backend runs in deterministic mock-LLM mode.

3. Run server

uv run uvicorn app.main:app --reload --port 8000

Frontend (bun)

1. Install deps

cd /Users/mishaaghamalyan/Development/personal/evolv/frontend
bun install

2. Run dev server

bun run dev

Frontend proxies /api and /ws to backend on localhost:8000.

Implemented Core Features

• Project CRUD with problem statement, criteria, hyperparams, seed ideas
• Async run orchestration with start, pause, resume, stop
• Evolution operators: mutate, crossover, random inject, elitism
• Critic scoring with weighted aggregate objective
• Diversity scoring (sentence-transformers with fallback)
• WebSocket live event stream
• Checkpoint creation and resume-from-checkpoint support
• Run results endpoint + Markdown/JSON export
• SQLite persistence + on-disk artifacts
• Health + Prometheus metrics endpoints

API Surface

• POST /api/projects
• GET /api/projects
• GET /api/projects/{project_id}
• PATCH /api/projects/{project_id}
• POST /api/projects/{project_id}/runs
• GET /api/runs/{run_id}
• POST /api/runs/{run_id}/pause
• POST /api/runs/{run_id}/resume
• POST /api/runs/{run_id}/stop
• POST /api/runs/{run_id}/checkpoint
• GET /api/runs/{run_id}/results
• GET /api/runs/{run_id}/export?format=json|md
• GET /api/runs/{run_id}/events
• GET /health/live
• GET /health/ready
• GET /metrics
• WS /ws/runs/{run_id}

Tests

cd /Users/mishaaghamalyan/Development/personal/evolv/backend
uv run pytest

Notes

• This is V1 local-first architecture with in-process async workers.
• Cost/token telemetry is informational only in this version.