7dad9d97af
Create docker/entrypoint.sh to run alembic migrations on API startup. Create backend/worker.py with Celery app config for the compose worker service. Fix README single-container port (8000) and add production compose documentation. Add 27 tests (stack integration + worker) verifying all Docker/compose artifacts are present, consistent, and the /health endpoint responds correctly. |
||
|---|---|---|
| alembic | ||
| Auto Run Docs | ||
| backend | ||
| docker | ||
| frontend | ||
| .env.example | ||
| .gitignore | ||
| alembic.ini | ||
| CLAUDE.md | ||
| docker-compose.yml | ||
| env.example | ||
| promptlooper-spec.md | ||
| README.md | ||
PromptLooper
The one who loops prompts — a universal LLM pipeline tuning workbench.
PromptLooper is a self-hosted tool for systematically optimizing LLM prompts, model selection, and inference parameters. It runs experiments across prompt x model x parameter combinations, caches every response, scores results against pluggable evaluation functions, and surfaces the best configurations through a real-time observability dashboard with human-in-the-loop steering.
It ships as a single Docker container (SQLite mode) for zero-config quickstart, or a Docker Compose stack (Postgres + Redis) for production use. An MCP server enables any AI agent to drive PromptLooper programmatically — creating experiments, running sweeps, and reading results without human intervention.
Quick Start
Single Container (zero dependencies)
docker run -p 8000:8000 -v promptlooper-data:/data ghcr.io/xpltdco/promptlooper
Open http://localhost:8000 — you'll be prompted to create an admin account on first boot.
In single-container mode, the API serves the built frontend as static files at the root. Database migrations run automatically on startup.
Production (Docker Compose)
git clone git@git.xpltd.co:xpltdco/promptlooper.git
cd promptlooper
cp .env.example .env
# Edit .env — set JWT_SECRET at minimum
docker compose up -d
Open http://localhost:8400 — nginx proxies the frontend (port 80 → 8400) and API (/api/ → port 8000).
Services started:
promptlooper-db— PostgreSQL 16 on port 5434promptlooper-redis— Redis 7promptlooper-api— FastAPI + Alembic migrations (auto-runs on startup)promptlooper-worker— Celery worker for experiment executionpromptlooper-web— Nginx reverse proxy on port 8400
First boot: Navigate to http://localhost:8400/setup to create the admin account.
Features
- Systematic experimentation — grid, random, and guided sweeps across prompt x model x parameter space
- Response caching — SHA-256 deduplication means re-runs cost zero tokens
- Pluggable scoring — embedding similarity, format compliance, keyword presence, LLM-as-judge, human rating, custom webhooks
- Real-time dashboard — live progress, leaderboard, side-by-side comparison, steering controls
- MCP server — AI agents can create experiments, run sweeps, and export results programmatically
- Single-container mode — SQLite + in-process queue when no external dependencies are configured
Development
# Start backing services
docker compose up -d promptlooper-db promptlooper-redis
# Backend
cd backend && pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Frontend (separate terminal)
cd frontend && npm install && npm run dev
Testing
cd backend && pytest
cd frontend && npm test