Metadata-Version: 2.4
Name: t-prompts
Version: 0.18.1
Summary: Structured prompts using template strings
Project-URL: Homepage, https://github.com/habemus-papadum/t-prompts
Project-URL: Repository, https://github.com/habemus-papadum/t-prompts
Project-URL: Documentation, https://github.com/habemus-papadum/t-prompts
Author-email: Nehal Patel <nehal@alum.mit.edu>
License: MIT License
        
        Copyright (c) 2025 Nehal Patel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: pillow>=10.0.0
Requires-Dist: pytest-cov>=7.0.0
Description-Content-Type: text/markdown

# t-prompts

[![CI](https://github.com/habemus-papadum/t-prompts/actions/workflows/ci.yml/badge.svg)](https://github.com/habemus-papadum/t-prompts/actions/workflows/ci.yml)
[![Coverage](https://raw.githubusercontent.com/habemus-papadum/t-prompts/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/habemus-papadum/t-prompts/blob/python-coverage-comment-action-data/htmlcov/index.html)
[![TypeScript Coverage](https://raw.githubusercontent.com/habemus-papadum/t-prompts/typescript-coverage-badge/typescript-coverage.svg)](https://github.com/habemus-papadum/t-prompts/tree/main/widgets)
[![Documentation](https://img.shields.io/badge/Documentation-blue.svg)](https://habemus-papadum.github.io/t-prompts/)
[![PyPI](https://img.shields.io/pypi/v/t-prompts.svg)](https://pypi.org/project/t-prompts/)
[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

**Provenance-preserving prompts for LLMs using Python 3.14's template strings**

## What is t-prompts?

`t-prompts` turns Python 3.14+ t-strings into navigable trees that preserve full provenance information (expression text, conversions, format specs). Perfect for building, composing, and auditing LLM prompts.

Unlike f-strings which immediately evaluate to strings, `t-prompts` keeps the structure intact so you can:

- **Trace** exactly which variable produced which part of your prompt
- **Navigate** nested prompt components programmatically
- **Compose** complex prompts from smaller, reusable pieces
- **Audit** with complete provenance for compliance and debugging
- **Validate** types at prompt creation (no accidental `str(obj)` surprises)

**Requirements:** Python 3.14+

## Quick Example

```python
from t_prompts import prompt

# Create a structured prompt
instructions = "Always answer politely."
p = prompt(t"Obey {instructions:inst}")

# Renders like an f-string
print(str(p))  # "Obey Always answer politely."

# But preserves full provenance
node = p['inst']
print(node.expression)  # "instructions" (original variable name)
print(node.value)       # "Always answer politely."
```

This enables riching tooling:
![Widget](docs/screenshot.png)

## Targeted Use Cases

- *Prompt Debugging:* "What exactly did this tangle of code render to?"
- *Prompt Optimization (Performance):* "What wording / content best achieves my goal?"
- *Prompt Optimization (Size):* "How do I get the same result with fewer words?"
- *Prompt Compacting:* "LLM tells me to keep it short, now what do I do?"

## Caveats
While this library targets the creation of structured multi-modal prompts, despite the name, there is nothing in particular tying this library to LLMs / Generative models.  (It is more "t" than "prompts") To use it for an actual LLM call, you would need to convert the IR into a model specific form (though for text, it could be as simple as `str(prompt)`)

## Documentation

📚 **Full documentation:** https://habemus-papadum.github.io/t-prompts/

- [Quick Interactive Demo](https://habemus-papadum.github.io/t-prompts/quick_demo/)
- [Tutorial](https://habemus-papadum.github.io/t-prompts/tutorial/)


## Installation

```bash
pip install t-prompts
```

Or with uv:

```bash
uv add t-prompts
```

## Development

This project uses [UV](https://docs.astral.sh/uv/) and [PNPM](https://pnpm.io/) for dependency management.

```bash
# Onetime Setup (per dev machine)
curl -LsSf https://astral.sh/uv/install.sh | sh # Other options exist!
curl -fsSL https://get.pnpm.io/install.sh | sh - # Other options exist!
./scripts/setup-visual-tests.sh

# Repo setup (per clone)
./scripts/setup.sh

# Lint and format
uv run ruff check .
uv run ruff format .

# Build documentation
uv run mkdocs serve
```

See [Developer Setup](https://habemus-papadum.github.io/t-prompts/developer/setup/) for detailed instructions.

## License

MIT License - see LICENSE file for details.
