# PromptLooper

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Status: Alpha](https://img.shields.io/badge/Status-Alpha-orange.svg)]()

> 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)

```bash
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)

```bash
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 5434
- `promptlooper-redis` — Redis 7
- `promptlooper-api` — FastAPI + Alembic migrations (auto-runs on startup)
- `promptlooper-worker` — Celery worker for experiment execution
- `promptlooper-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

```bash
# 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

```bash
cd backend && pytest
cd frontend && npm test
```

## License

[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html)