prompt-library

# prompt-library Skill

## Overview

prompt-library is a self-hosted prompt management system. Prompts use `{{variable}}` template syntax, are versioned on every save, and can be executed against OpenAI, Anthropic, or a local Ollama instance. All data is stored in SQLite.

## Quick Start

```bash
# clone and install
git clone https://github.com/yourorg/prompt-library
cd prompt-library
pnpm install

# set required env vars
export API_KEY=pl_$(openssl rand -hex 32)
export ENCRYPTION_KEY=$(openssl rand -hex 32)
export ANTHROPIC_API_KEY=sk-ant-...

# start server (port 3000) and web (port 5173)
pnpm dev
```

## REST API Reference

All endpoints (except `/api/health`) require `Authorization: Bearer <API_KEY>`.

### Prompts

```bash
# List all prompts
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/prompts

# Create prompt with first version
curl -X POST http://localhost:3000/api/prompts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Assistant",
    "description": "Reviews {{language}} code",
    "body": "Please review this {{language}} code:\n\n{{code}}",
    "systemMessage": "You are an expert engineer.",
    "projectId": 1,
    "tags": ["coding", "review"]
  }'

# Get prompt (with current version)
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/prompts/1

# Save new version
curl -X POST http://localhost:3000/api/prompts/1/versions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Please review this {{language}} code for bugs and style:\n\n{{code}}",
    "commitMessage": "add style check"
  }'

# List versions
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/prompts/1/versions
```

### Running Prompts

```bash
# Run a prompt
curl -X POST http://localhost:3000/api/prompts/1/run \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": 5,
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "variables": {
      "language": "Python",
      "code": "def add(a, b):\n    return a + b"
    },
    "maxTokens": 1024,
    "temperature": 0.7
  }'

# Response
{
  "runId": 247,
  "renderedPrompt": "Please review this Python code for bugs and style:\n\ndef add(a, b):\n    return a + b",
  "response": "The code is clean and correct...",
  "inputTokens": 34,
  "outputTokens": 128,
  "latencyMs": 921,
  "provider": "anthropic",
  "model": "claude-3-5-sonnet-20241022"
}

# Run history for a prompt
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/prompts/1/runs

# All runs (paginated)
curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/api/runs?limit=20&offset=0"
```

### Provider Configuration

```bash
# Set Anthropic API key
curl -X PUT http://localhost:3000/api/providers/anthropic \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "sk-ant-..."}'

# Set OpenAI API key
curl -X PUT http://localhost:3000/api/providers/openai \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "sk-..."}'

# List configured providers (keys redacted)
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/providers
# Response: [{"provider":"anthropic","configured":true}, {"provider":"openai","configured":true}]

# Remove a key
curl -X DELETE -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/providers/openai
```

## Template Variable Syntax

Variables use double curly-brace syntax: `{{variable_name}}`

Rules:
- Variable names: `[a-zA-Z_][a-zA-Z0-9_]*` (max 64 chars)
- Case-sensitive: `{{Language}}` and `{{language}}` are different variables
- No expressions -- string substitution only
- Whitespace inside braces not allowed: `{{ name }}` is invalid

```
Write a {{style}} summary of the following {{language}} code:

{{code}}
```

Variables: `style`, `language`, `code`

If any declared variable is missing at run time, the API returns HTTP 400:
```json
{"error": "Missing variables: code"}
```

## Supported Models

### Anthropic

| Model ID | Notes |
|----------|-------|
| `claude-3-5-sonnet-20241022` | Best quality |
| `claude-3-5-haiku-20241022` | Fast, lower cost |
| `claude-3-opus-20240229` | Highest capability |

### OpenAI

| Model ID | Notes |
|----------|-------|
| `gpt-4o` | Best quality |
| `gpt-4o-mini` | Fast, lower cost |
| `gpt-4-turbo` | Large context |

### Ollama (local, no API key)

Any model installed in your local Ollama instance is supported. Common models:
- `llama3.1:8b` -- good general purpose
- `mistral:7b` -- fast reasoning
- `codellama:13b` -- code tasks
- `deepseek-coder:6.7b` -- code generation

Check available models: `ollama list`

## Environment Variables

| Variable | Required | Default | Notes |
|----------|----------|---------|-------|
| `PORT` | No | `3000` | HTTP listen port |
| `DATABASE_PATH` | No | `./data/prompts.db` | SQLite file path |
| `API_KEY` | Yes | -- | Full key value (not hash). Server hashes on startup. |
| `ENCRYPTION_KEY` | Yes | -- | 32-byte hex string for provider key encryption |
| `OLLAMA_BASE_URL` | No | `http://localhost:11434` | Ollama base URL |
| `LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error` |

## Docker

```bash
# build
docker build -t prompt-library ./packages/server

# run
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/data \
  -e API_KEY=pl_$(openssl rand -hex 32) \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e DATABASE_PATH=/data/prompts.db \
  prompt-library
```

docker-compose.yml:
```yaml
services:
  server:
    build: ./packages/server
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      DATABASE_PATH: /data/prompts.db
      API_KEY: ${API_KEY}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
```

## Backup and Restore

SQLite backup (online, safe while server is running):
```bash
# backup
sqlite3 data/prompts.db ".backup data/prompts.backup.db"

# restore
cp data/prompts.backup.db data/prompts.db
```

Export all prompts via API:
```bash
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:3000/api/export > prompts-export.json
```

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| 401 Unauthorized | Wrong API key | Check `API_KEY` env var |
| 400 Missing variables | Variable in template not supplied | Provide all `{{var}}` values in `variables` object |
| 502 Provider error | LLM API returned an error | Check provider status; verify key is set and valid |
| Provider error "key not configured" | No key set for provider | `PUT /api/providers/<name>` with API key |
| Ollama "connection refused" | Ollama not running | `ollama serve` or check `OLLAMA_BASE_URL` |
| DB locked | Multiple server instances | Run only one server process per DB file |