prompt-vcs 0.4.0

Git-native prompt management library for LLM applications

prompt-vcs

Git-native prompt management library for LLM applications

A lightweight, code-first Python library for managing LLM prompts using Git and the file system — no external database required.

中文文档

✨ Features

• 🚀 Zero Configuration - Define prompts directly in code, no extra setup needed
• 📦 Git Native - Version control through file system and Git
• 📄 Single-File Mode - All prompts in one prompts.yaml (default, clean and simple)
• 📂 Multi-File Mode - Separate files per prompt (for large projects)
• 🔄 Lockfile Mechanism - Lock specific versions for production, use code strings in development
• 🛠️ Auto Migration - One-click conversion of hardcoded prompts to managed format
• 🧪 Testing Framework - Define and run test cases for prompts with YAML-based test suites
• ✅ Output Validation - Validate prompt outputs with JSON schema, regex, length checks, and custom rules
• 🎯 Type Safe - Full type hints support

📦 Installation

pip install prompt-vcs

🚀 Quick Start

1. Initialize Project

# Single-file mode (default) - creates prompts.yaml
pvcs init

# Multi-file mode - creates prompts/ directory
pvcs init --split

2. Inline Mode

from prompt_vcs import p

# Uses code string by default, switches to locked version when specified
msg = p("user_greeting", "Hello {name}", name="Developer")

3. Decorator Mode

from prompt_vcs import prompt

@prompt(id="system_core", default_version="v1")
def get_system_prompt(role: str):
    """
    You are a helpful assistant playing the role of {role}.
    """
    pass

4. Extract Prompts to YAML

pvcs scaffold src/

5. Switch Versions

pvcs switch user_greeting v2

6. Auto-Migrate Existing Code

Automatically convert hardcoded prompt strings to p() calls:

# Preview changes
pvcs migrate src/ --dry-run

# Interactive migration (confirm each change)
pvcs migrate src/

# Apply all changes automatically
pvcs migrate src/ --yes

# Clean mode: extract prompts to YAML and remove from code
# - If prompts.yaml exists → writes to prompts.yaml (single-file mode)
# - Otherwise → creates prompts/{id}/v1.yaml (multi-file mode)
pvcs migrate src/ --clean -y

Supported Conversions:

# Before
prompt = f"Hello {user.name}, price: {price:.2f}"

# After (default mode) - keeps template in code
from prompt_vcs import p
prompt = p("demo_prompt", "Hello {user_name}, price: {price:.2f}", 
           user_name=user.name, price=price)

# After (--clean mode) - extracts template to YAML
from prompt_vcs import p
prompt = p("demo_prompt", user_name=user.name, price=price)
# Template is stored in prompts.yaml or prompts/demo_prompt/v1.yaml

Features:

• ✅ F-string variable extraction
• ✅ Format spec preservation (:.2f)
• ✅ Attribute/dict access sanitization (user.name → user_name)
• ✅ Automatic import statement insertion
• ✅ Smart skipping of short strings and complex expressions
• ✅ Clean mode: Extract to YAML, keep only ID in code
• ✅ Auto-detects storage mode: single-file (prompts.yaml) or multi-file (prompts/)

📁 Project Structure

Single-File Mode (Default)

your-project/
├── .prompt_lock.json     # Version lock file
├── prompts.yaml          # All prompts in one file
└── src/
    └── your_code.py

prompts.yaml format:

user_greeting:
  description: "Greeting template"
  template: |
    Hello, {name}!

system_core:
  description: "System prompt"
  template: |
    You are a helpful assistant.

Multi-File Mode (--split)

your-project/
├── .prompt_lock.json     # Version lock file
├── prompts/              # Prompt YAML files
│   ├── user_greeting/
│   │   ├── v1.yaml
│   │   └── v2.yaml
│   └── system_core/
│       └── v1.yaml
└── src/
    └── your_code.py

🎯 Core Principles

• No Database - File system is the database
• Git Native - Version control relies on file naming conventions and Git commits
• Code First - Developers define prompts in code first
• Zero Latency Dev - Development mode uses code strings, production reads from Lockfile

🧪 Testing Framework

Define test cases in YAML and validate prompt outputs:

# tests/prompts_test.yaml
name: "Prompt Tests"
tests:
  - name: "greeting_test"
    prompt_id: "user_greeting"
    inputs:
      name: "Developer"
    expected_output: "Hello, Developer!"
    validation:
      - type: contains
        substring: "Hello"
      - type: length
        max_length: 100

from prompt_vcs.testing import PromptTestRunner, load_test_suite_from_yaml

# Load and run tests
suite = load_test_suite_from_yaml("tests/prompts_test.yaml")
runner = PromptTestRunner()
results = runner.run_suite(suite)

Validation Types:

• json_schema - Validate JSON structure (requires pip install prompt-vcs[validation])
• regex - Match patterns
• length - Check min/max length
• contains - Verify substring presence
• custom - Custom validation functions

📖 CLI Commands

Command	Description
pvcs init	Initialize project (single-file mode, creates prompts.yaml)
pvcs init --split	Initialize project (multi-file mode, creates prompts/ dir)
pvcs scaffold <dir>	Scan code and generate prompts (auto-detects mode)
pvcs switch <id> <version>	Switch prompt version
pvcs status	View current lock status
pvcs migrate <path>	Auto-migrate hardcoded prompts
pvcs migrate <path> --clean	Migrate and extract prompts to YAML files
pvcs test <suite.yaml>	Run prompt tests from YAML suite
pvcs diff <id> <v1> <v2>	Compare two versions of a prompt
pvcs log <id>	Show Git commit history for a prompt

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License - See LICENSE file for details

👤 Author

emerard - @Dreamer431