# PromptBoost v0.1.1+

PromptBoost is the Python/FastAPI app and product line for local prompt
compilation, evaluation logging, and matrix-based prompt checks.

It reads PromptGarage examples read-only, accepts raw prompts, selects
task/harness/model rules, generates deterministic boosted prompts, runs a local
no-new-facts check, and stores boost runs in `promptboost.db`. The app also
includes a Matrix Lab UI/API and an optional agentic LLM prepass that safely
falls back to deterministic PromptBoost when the LLM is unavailable or unsafe.

The repository root TypeScript code is a separate portable V2 library and
experiment line. Its public entry point is `../src/index.ts`; this Python app
remains the product-facing web/API implementation.

## Run

```bash
uv run uvicorn promptboost.main:app --reload --port 8000
```

Open `http://127.0.0.1:8000`.

## Routes

- `GET /` — main PromptBoost web form.
- `GET /matrix-lab` — Matrix Lab UI for comparing deterministic and full-cell
  prompt evaluations.
- `GET /health` — local health check.
- `POST /boost` — deterministic PromptBoost pipeline.
- `POST /boost/agentic` — optional LLM prepass plus deterministic fallback.
- `POST /api/matrix/deterministic` — deterministic matrix evaluation endpoint.
- `POST /api/matrix/full-cell` — full-cell matrix evaluation endpoint.
- `GET /api/runs` — stored boost-run history from `promptboost.db`.
- `GET /api/promptgarage/samples` — read-only PromptGarage sample access.

## Agentic mode

The deterministic `/boost` route remains the default. The optional
`/boost/agentic` route runs an OpenAI-compatible LLM prepass first, validates
the JSON task draft, then falls back to deterministic PromptBoost if the LLM is
unavailable or adds suspected new facts.

```bash
export PROMPTBOOST_LLM_API_KEY=...
export PROMPTBOOST_LLM_BASE_URL=https://api.openai.com/v1
export PROMPTBOOST_LLM_MODEL=gpt-5.4-mini
```

## Test

```bash
uv run pytest
```

## Notes

- PromptGarage is read with SQLite immutable/read-only connections.
- Paid LLM APIs are only called when agentic mode is explicitly configured and
  requested.
- The no-new-facts check is conservative and deterministic; it is a warning
  gate, not a semantic proof system.