Metadata-Version: 2.4
Name: prompt-lineage
Version: 0.1.0
Summary: Git-like version control for LLM prompts
License-Expression: MIT
Project-URL: Homepage, https://github.com/Shr1tan/lineage
Project-URL: Repository, https://github.com/Shr1tan/lineage
Keywords: llm,prompts,version-control,cli,ai,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyyaml>=6.0

# Lineage

**Git-like version control for LLM prompts.**

Lineage tracks every version of your LLM prompts — commit, diff, test, and roll back from the terminal. Built for developers who treat prompts like code.

## The problem

Prompts are code, but most teams treat them like scratch notes — no history, no diffs, no rollback. Lineage gives you `git`-style version control purpose-built for `.prompt` files so you can track what changed, when, and why.

## Install

```bash
pip install prompt-lineage
```

Or install from source:

```bash
git clone https://github.com/Shr1tan/lineage.git
cd lineage
pip install -e .
```

## Commands

### `promptctl init`

Creates a `.promptctl/` directory with a SQLite store and a `prompts/` folder.

```
$ promptctl init
╭── promptctl init ──╮
│ Initialized promptctl in .promptctl/ │
│ Prompt files go in prompts/          │
╰────────────────────╯
```

### `promptctl commit <name> -m "message"`

Reads `prompts/<name>.prompt`, snapshots its content, and auto-increments the version.

```
$ promptctl commit email-subject-line -m "initial version"
╭── promptctl commit ──╮
│ Committed email-subject-line@v1 │
│ Message: initial version        │
╰──────────────────────╯
```

### `promptctl log <name>`

Shows version history as a table, most recent first.

```
$ promptctl log email-subject-line
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Message                 ┃ Author ┃ Date                ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│   v2    │ added recipient context │ you    │ 2026-03-18 18:26:32 │
│   v1    │ initial version         │ you    │ 2026-03-18 18:26:20 │
└─────────┴─────────────────────────┴────────┴─────────────────────┘
```

### `promptctl diff <name>@v1 <name>@v2`

Colored unified diff between any two versions.

```
$ promptctl diff email-subject-line@v1 email-subject-line@v2
-variables: [recipient_name, company, role]
+variables: [recipient_name, company, role, tone]

-You are a sales email assistant. Write a subject line
+You are a sales email assistant. Write a compelling subject line
```

### `promptctl checkout <name>@v<n>`

Restores a specific version back to `prompts/<name>.prompt`.

```
$ promptctl checkout email-subject-line@v1
╭── promptctl checkout ──╮
│ Checked out email-subject-line@v1 → prompts/email-subject-line.prompt │
╰────────────────────────╯
```

### `promptctl status`

Shows which prompts are clean, modified, or untracked.

```
$ promptctl status
┌─────────────────────┬─────────┬──────────────────────┬───────────┬───────────┐
│ Prompt              │ Version │ Last message         │ Committed │ Status    │
├─────────────────────┼─────────┼──────────────────────┼───────────┼───────────┤
│ email-subject-line  │ v3      │ added urgency framing│ 2h ago    │ clean     │
│ code-review         │ v1      │ initial version      │ 3d ago    │ modified  │
│ onboarding-email    │ —       │ —                    │ —         │ untracked │
└─────────────────────┴─────────┴──────────────────────┴───────────┴───────────┘
```

### `promptctl test <name>`

Runs a prompt against an LLM with test cases from a `.prompttest` file.

```
$ promptctl test email-subject-line
Testing email-subject-line@v2

─── Case: basic-cold-outreach ───
Output: "Quick follow-up on API reliability at Stripe"

─── Case: enterprise-outreach ───
Output: "Exploring OpenAI API impact on your roadmap"

2 cases run.
```

## Prompt file format

```
---
name: email-subject-line
description: Generates subject lines for cold outreach
variables: [recipient_name, company, role]
---

You are a sales email assistant. Write a subject line
for the following cold outreach email.

Recipient: {{recipient_name}}, {{role}} at {{company}}
Email body: {{email_body}}

Subject line only. No explanation.
```

YAML frontmatter defines metadata. The body below `---` is the prompt template. Use `{{variable}}` for interpolation.

## Roadmap

- **Web UI** — browser-based dashboard for browsing prompt history, comparing versions, and running evals
- **Assertions** — add pass/fail criteria to `.prompttest` files for automated scoring
- **GitHub Actions integration** — CI pipeline to eval prompts on every PR and block merges on regression
