Metadata-Version: 2.4
Name: tmpt
Version: 0.1.0
Summary: Fast, dev-friendly prompt management for Python.
Project-URL: Homepage, https://github.com/mtrkwsk/tmpt
Project-URL: Repository, https://github.com/mtrkwsk/tmpt
Project-URL: Documentation, https://mtrkwsk.github.io/tmpt
Project-URL: Changelog, https://github.com/mtrkwsk/tmpt/blob/main/CHANGELOG.md
Author-email: mtrkwsk <git@mtarkowski.pl>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,llm,prompt,template
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: marimo
Requires-Dist: marimo>=0.20.4; extra == 'marimo'
Provides-Extra: rich
Requires-Dist: rich>=13.7.0; extra == 'rich'
Description-Content-Type: text/markdown

# tmpt

**Fast, file-based prompt management for Python.**

`tmpt` lets you write LLM prompts as plain Markdown files, version them, compose them, and render them with typed variables — all with zero runtime dependencies.

[![PyPI version](https://img.shields.io/pypi/v/tmpt)](https://pypi.org/project/tmpt/)
[![Python](https://img.shields.io/pypi/pyversions/tmpt)](https://pypi.org/project/tmpt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

- 📝 Write prompts as plain **Markdown files** with YAML frontmatter
- 🔀 **Variables** `{{ var }}`, **defaults** `{{ var:default }}`, and **conditionals** `{{ ? var }}`
- 🧩 **Compose** prompts can include other prompts `{{#other.id}}`
- 📦 **Version** prompts with multiple variants per file
- 🗂️ **Registry** auto-discovery, auto-reload
- ⚡ **Zero runtime dependencies** — stdlib only, Python 3.10+
- 🔌 **Extensible** add own processing steps
- 🖥️ **CLI** for discovery, validation, and rendering
- 🎨 Optional **Rich** output for colorful terminal and notebook display

---

## Table of contents

- [Install](#install)
- [Quick start](#quick-start)
- [Template syntax](#template-syntax)
- [File format](#file-format)
- [Multiple variants in one file](#multiple-variants-in-one-file)
- [Registry & loading](#registry--loading)
- [Python API](#python-api)
- [CLI](#cli)
- [Extensible pipeline](#extensible-pipeline)
- [Optional rich output](#optional-rich-output)

---

## Install

```bash
pip install tmpt
```

No runtime dependencies. Python 3.10+ required.

---

## Quick start

**1. Write a prompt file** (`prompts/summarize.md`):

```markdown
---
id: summarize
tone: concise
---
Summarize the following in {{ tone }} tone.

{{ ? topic }}
Topic: {{ topic }}

{{#shared_context}}
```

**2. Render it in Python:**

```python
from tmpt import Tmpt

Tmpt("./prompts")

prompt = Tmpt["summarize"]
text = prompt(topic="climate change")
print(text)
```

**Or load and render in one line:**

```python
from tmpt import Tmpt

text = Tmpt("./prompts/summarize.md")(topic="climate change")
print(text)
```

---

## Template syntax

| Syntax | Description |
|---|---|
| `{{ var }}` | Substitute variable `var` |
| `{{ var:default }}` | Substitute `var`, fall back to `default` if not provided |
| `{{ ? var }}` ... `#` | Include block only when `var` is set and non-empty |
| `{{ ! var }}` ... `#` | Include block only when `var` is **not** set or empty |
| `{{#other_prompt}}` | Inline-include another registered prompt by ID |
| `// comment` | Line comment — stripped from rendered output |

### Variable substitution

```
Hello {{ name }}!
Using {{ model:gpt-4o }} today.
```

Calling `prompt(name="Alice")` renders:

```
Hello Alice!
Using gpt-4o today.
```

### Conditional blocks

Conditionals occupy their own line and close with a bare `#` line:

```
{{ ? topic }}
Our topic is {{ topic }}.
#

{{ ! topic }}
No topic provided.
#
```

### Includes

Embed another registered prompt by ID:

```
{{#shared_checklist}}
```

Recurrent rendering allows powerful, multi-stage composing.

### Comments

```
// This line is stripped from the final output.
```

---

## File format

Prompt files are plain Markdown with an optional YAML frontmatter block to include variable defaults or metadata:

```markdown
---
id: summarize
tone: concise
tags: [summarization, text]
---
Summarize the following in {{ tone }} tone.

{{ ? topic }}
Topic: {{ topic }}
```

---

## Multiple variants in one file

A single file can hold multiple prompt variants separated by `---`:

```markdown
---
id: summarize.1
---
Short summary of {{ topic }}.

---

Detailed summary of {{ topic }}.
Steps:
1. Understand impact
2. Isolate issue
3. Communicate status
```

Each variant is registered independently and accessible by its own ID with common root name: `prompt.1`, `prompt.2`

---

## Registry & loading

```python
from tmpt import Tmpt

# Load all prompts from a folder (recursive)
Tmpt("./prompts")

# Load a single file
Tmpt("./prompts/summarize.md")

# Inline prompts
Tmpt("Hi, {{ name }}!", name="John")

# Register inline from a string
Tmpt["greeting"] = "Hello {{ name }}!"

# Access by ID
prompt = Tmpt["summarize"]
```

---


## CLI

`tmpt` ships with a command-line interface. Default command is `validate`.

### Validate

Discover and inspect all prompt files in a directory:

```bash
tmpt validate ./prompts
```

Validate a single file:

```bash
tmpt validate ./prompts/summarize.md
```

Look up a specific prompt ID (from the current directory):

```bash
tmpt validate summarize.last
```

### Render

Render a prompt with variables and print both the raw template and the output:

```bash
tmpt render summarize --variable topic="incident response"
tmpt render release_notes.last --variable product="tmpt" --variable version="0.2.0"
```

### Discover

List all prompts and their aliases discovered in a path:

```bash
tmpt discover ./prompts
```

---


## Optional rich output

`tmpt` works with the standard library only. Install `rich` to get syntax-highlighted CLI output:

```bash
pip install "tmpt[rich]"
```

## Examples

See the `examples/` directory for runnable notebooks and scripts.


