py-priompt: Build Token-Budgeted Prompts in Python

Overview

PyPriompt is a Python port of Priompt, a prompt-design library inspired by component-based web frameworks. It lets developers build prompts as reusable Python components and uses priorities to decide which content to include when a prompt must fit a token budget.

It is most useful when prompt contents have different levels of importance, such as in long conversations or prompts assembled from files. It renders chat messages or a string, with tokenization configured for the target model.

Key Features

• Build prompts from custom components and standard system, user, and assistant message components.
• Set absolute or relative priorities for content so lower-priority sections can be omitted to meet a token limit.
• Use First to provide priority-based fallbacks, and Empty to reserve space for generation.
• Add images and tool schemas to prompts with Image and Tools components.
• Isolate sections with their own token limits, or force token breaks with Br.
• Capture and parse rendered output, and configure common generation properties with Config.
• Use inclusion and exclusion callbacks or source maps to inspect which prompt components were rendered.

Use Cases

• Chat application developers can keep system instructions and the latest user message while trimming older conversation history.
• AI application developers can include long files or other context selectively, favoring the most relevant sections when the token budget is tight.
• Prompt designers can reserve tokens for generated responses and provide fallback text when larger content does not fit.
• Teams debugging prompt changes can use source maps to trace rendered text back to its component, including when investigating cache misses.

Project Facts

• Language: Python
• License: NOASSERTION
• Stars: 65
• Forks: 2
• Topics: none listed
• Archived: no

Getting Started

Install the package with pip install priompt. See the README for usage examples and details.

Alternatives

• POML: POML uses markup to structure and integrate prompt content, rather than selecting reusable components by priority to fit a token limit.

Considerations

The README notes that the original test suite passes, but this port was produced in a day with AI assistance and may contain bugs. It also lists Capture, Tool, and Tools behavior and compatibility with priompt-preview as items to verify. The renderer may not always find the exact optimal priority cutoff, and performance is described as reasonable for around 10K scopes. Prompts built with many priorities can also be difficult to cache effectively.