Grompt - Git for Prompts

Store prompts as YAML files, version them, and use them in code by ID.

That's it. Everything else is optional.

---

The Core Idea

Grompt lets you store prompts as YAML files, version them, and use them in code by ID.

• ✅ Prompts live in files (prompts/code-review.yaml) - not buried in code
• ✅ Version changes with grompt commit code-review
• ✅ Use in code: prompt = grompt.load("code-review")

That's the core. Everything else is nice-to-have.

---

Why Grompt?

Problem: Prompts buried in code are hard to version, test, and optimize.

Solution: Prompts as files, referenced by ID.

Benefits:

• ✅ Change prompts without touching code
• ✅ Version prompts with git
• ✅ Test prompts with real data
• ✅ Track which version is in production

---

What Grompt Is

1. Prompt Storage

• Prompts live in YAML files (prompts/code-review.yaml)
• Not buried in code
• Easy to edit, review, and share

2. Versioning

• Track changes with version numbers
• Commit changes: grompt commit code-review
• Only version when content actually changes (hash-based)

3. Use in Code

import grompt
prompt = grompt.load("code-review")
result = prompt.render(code="...", language="Python")

---

What Grompt Is NOT

• ❌ Not a test runner - Use pytest for that
• ❌ Not an LLM execution engine - Just manages prompts
• ❌ Not a prompt optimization tool - Just stores and versions them
• ❌ Not a database - Just files

---

Installation

Install Grompt via pip:

pip install grompt

For development installation:

pip install -e ".[dev]"

---

Quick Start

The Simple Workflow

1. Create prompt file    → prompts/code-review.yaml
2. Edit it               → vim prompts/code-review.yaml
3. Test it               → Use test inputs or pytest
4. Commit changes        → grompt commit code-review
5. Use in code          → grompt.load("code-review")

Step-by-Step

1. Initialize Grompt

Initialize Grompt in your project root. This creates a .grompt config file and a prompts directory.

grompt init

2. Create a Prompt

Create a new prompt named code-review.

grompt add code-review --template "Review this code:\n{{ code }}"

This creates prompts/code-review.yaml.

3. Use in Python

Load and use the prompt in your application.

import grompt

# Load the prompt
prompt = grompt.load("code-review")

# Render with variables
rendered = prompt.render(
    code="def add(a,b): return a+b"
)
print(rendered)

4. Load Variables from Files (Optional)

Use the optional helper to load test inputs from YAML files:

import grompt

prompt = grompt.load("code-review")

# Load variables from any YAML file
variables = grompt.load_variables("inputs/simple.yaml")
result = prompt.render(**variables)

5. Commit Changes

Commit changes when you're ready:

grompt commit code-review "Updated template"

---

File Structure

my-project/
├── prompts/
│   ├── code-review.yaml              ← Your prompts
│   └── test-inputs/                  ← Example inputs (optional)
│       └── code-review.simple.yaml
└── .grompt/                          ← Config (auto-created)
    └── config.yaml

Just files. Nothing hidden.

---

Quick Reference

Create Prompt

grompt add code-review

Edit Prompt

vim prompts/code-review.yaml

Test with Input

# Create input file (anywhere, any name)
cat > inputs/simple.yaml << EOF
code: "def add(a, b): return a + b"
language: Python
EOF

# Use in Python
python3 << EOF
import grompt

prompt = grompt.load("code-review")
inputs = grompt.load_variables("inputs/simple.yaml")  # Any path
result = prompt.render(**inputs)
print(result)
EOF

Commit Changes

grompt commit code-review "Updated template"

Use in Code

import grompt
prompt = grompt.load("code-review")
result = prompt.render(code="...", language="Python")

---

Documentation

• Defining Prompts - Learn how to create prompts with variables, system messages, and more.
• Using Prompts - How to use prompts in your CLI and Python code.
• Testing Prompts - Creating test cases and running tests.
• Variable Validation - Ensuring inputs match expected schemas.
• CLI Reference - Complete command-line interface documentation.
• Python API - API reference for integrating Grompt.
• Configuration - Global configuration options.
• Best Practices - Tips for managing prompts effectively.
• Examples - Real-world usage examples.

---

Contributing

We welcome contributions! Please see:

• CONTRIBUTING.md - Development setup and contribution guidelines
• CODING_GUIDELINES.md - Code style, architecture, and best practices
• CODE_OF_CONDUCT.md - Community standards and behavior expectations

---

Security

For security concerns, please see SECURITY.md.

Please do not report security vulnerabilities through public GitHub issues. Instead, email: mkarots@users.noreply.github.com

---

License

MIT