@reaatech/prompt-version-control-server

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Prompt Version Control API server providing Git-like versioning for AI prompts with eval-gated promotion, A/B deployment, metrics collection, and webhook integrations. Built on Hono 4 with Prisma and PostgreSQL.

Installation

npm install @reaatech/prompt-version-control-server
# or
pnpm add @reaatech/prompt-version-control-server

Feature Overview

• Prompt CRUD — create, read, update, and archive prompts with automatic version numbering
• Version management — store and track prompt versions with SHA-256 checksums for deduplication
• Tag-based lifecycle — resolve versions by draft, staging, and production tags
• Evaluation gates — block staging→production promotion on eval harness results
• A/B deployments — serve multiple versions with weighted traffic splitting and sticky sessions
• Semantic diffing — compare versions with line-level diffs and semantic impact scoring
• Metrics ingestion — track per-version cost, latency, and quality metrics
• Promotion workflows — promote/rollback production with audit trails
• Webhook subscriptions — notify external systems on version creation, tag changes, and evaluations
• Structured logging — Pino-based JSON logging with automatic pretty-printing in development
• Prometheus metrics — built-in /metrics endpoint for monitoring
• API key auth — scoped API keys with HMAC verification and audit logging
• Swagger UI — OpenAPI 3.0 spec served at /api/v1/docs

Quick Start

Development

# Set up environment
cp .env.example .env
 
# Install dependencies
pnpm install
 
# Generate Prisma client
pnpm --filter @reaatech/prompt-version-control-server db:generate
 
# Run migrations
pnpm --filter @reaatech/prompt-version-control-server db:migrate
 
# Seed the database
pnpm --filter @reaatech/prompt-version-control-server db:seed
 
# Start development server with hot reload
pnpm --filter @reaatech/prompt-version-control-server dev

Programmatic

import { app } from "@reaatech/prompt-version-control-server";
import { serve } from "@hono/node-server";
 
serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server running on http://localhost:${info.port}`);
});

API Reference

Infrastructure Endpoints

All API routes are prefixed with /api/v1 and require Authorization: Bearer <api-key> unless noted.

Prompts

Tags

Tag names: draft, staging, production. Only one version can hold a given tag at a time.

Promotions

The promote endpoint checks the evaluation gate: if the staging version has failed evaluations, the promotion is blocked.

Evaluations

Metrics

Metric types: cost, latency, quality.

Deployments

Render

Both accept { variables: Record<string, unknown> } in the body and return the rendered output with variable usage metadata.

Webhooks

Middleware Stack

All API routes pass through:

Environment Variables

Usage Patterns

Create a Prompt with Versions

# Create a prompt
curl -X POST http://localhost:3000/api/v1/prompts \
  -H "Authorization: Bearer pvc_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "template": "You are a helpful support agent. Help with: {{issue}}"
  }'
 
# Create a version
curl -X POST http://localhost:3000/api/v1/prompts/<promptId>/versions \
  -H "Authorization: Bearer pvc_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are a senior support agent. Help with: {{issue}}"
  }'
 
# Tag as production
curl -X POST http://localhost:3000/api/v1/prompts/<promptId>/tags/production \
  -H "Authorization: Bearer pvc_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": "<versionId>" }'

Render a Prompt with Variables

curl -X POST http://localhost:3000/api/v1/prompts/<promptId>/render \
  -H "Authorization: Bearer pvc_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": { "issue": "I cannot log in to my account" }
  }'

A/B Deployment

curl -X POST http://localhost:3000/api/v1/deployments \
  -H "Authorization: Bearer pvc_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "<promptId>",
    "variants": [
      { "versionId": "<versionA>", "weight": 90 },
      { "versionId": "<versionB>", "weight": 10 }
    ]
  }'
 
# Resolve for a session
curl "http://localhost:3000/api/v1/deployments/<deploymentId>/resolve?sessionId=user-123" \
  -H "Authorization: Bearer pvc_your-api-key"

Related Packages

• @reaatech/prompt-version-control-shared — Shared types and schemas
• @reaatech/prompt-version-control — TypeScript SDK
• @reaatech/prompt-version-control-cli — CLI tool
• @reaatech/prompt-version-control-mcp — MCP server for AI agents

License

MIT