{"name":"PyPriompt: Python Library for Priority-Based Prompt Design","description":"PyPriompt is a Python library for designing prompts, inspired by web design libraries like React and FastHTML. It intelligently manages context windows by using priorities to decide what information to include in the prompt, ensuring efficient use of token limits. This tool helps developers create dynamic and adaptable prompts for large language models.","github":"https://github.com/zenbase-ai/py-priompt","url":"https://osrepos.com/repo/zenbase-ai-py-priompt","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/zenbase-ai-py-priompt","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/zenbase-ai-py-priompt.md","json":"https://osrepos.com/repo/zenbase-ai-py-priompt.json","topics":["Python","Prompt Engineering","AI","LLM","Context Management","Software Development"],"keywords":["Python","Prompt Engineering","AI","LLM","Context Management","Software Development"],"stars":null,"summary":"PyPriompt is a Python library for designing prompts, inspired by web design libraries like React and FastHTML. It intelligently manages context windows by using priorities to decide what information to include in the prompt, ensuring efficient use of token limits. This tool helps developers create dynamic and adaptable prompts for large language models.","content":"## Introduction\n\nPyPriompt (Python + priority + prompt) is a Python port of the [Priompt](https://github.com/anysphere/priompt){target=_blank} library, remixed with [FastHTML](https://github.com/AnswerDotAI/fasthtml){target=_blank}. It introduces a structured approach to prompt design, allowing developers to manage the context window of large language models (LLMs) by assigning priorities to different parts of the prompt. This ensures that the most critical information is always included, even when facing token limits. The library draws inspiration from web design frameworks, aiming to bring similar component-based development principles to prompt engineering. You can read more about the motivation behind this approach in the [Prompt Design article](https://arvid.xyz/prompt-design){target=_blank}.\n\n## Installation\n\nPyPriompt can be easily installed using various Python package managers:\n\nbash\nuv add priompt\nrye add priompt\npoetry add priompt\npip install priompt\n\n\n## Examples\n\nPrompts in PyPriompt are rendered from Python components, allowing for dynamic and flexible prompt construction. Here's an example demonstrating a simple chat component that manages message history with priorities:\n\npython\nfrom priompt import (\n  component, # Decorator for custom components\n  # Standard components\n  SystemMessage, # For system messages\n  AssistantMessage, # For assistant messages\n  UserMessage, # For user messages\n  # Priompt components\n  Empty, # For reserving empty space\n  Scope, # For setting priorities\n  # For rendering prompts to OpenAI chat messages or a string\n  render,\n  O200KTokenizer, # For GPT-4o, GPT-4o-mini\n)\n\n@component\ndef chat(name: str, message: str, history: list[dict[str, str]]):\n    capitalized_name = name[0].upper() + name[1:]\n\n    return [\n        SystemMessage(f\"The user's name is {capitalized_name}. Please respond to them kindly.\"),\n        *[\n            Scope(\n                UserMessage(m[\"message\"]) if m[\"role\"] == \"user\" else AssistantMessage(m[\"message\"]),\n                prel=i,\n            )\n            for i, m in enumerate(history)\n        ],\n        UserMessage(message),\n        Empty(1000),\n    ]\n\nmessages = render(\n    chat(\n        name=\"cyrus\",\n        message=\"What is the answer to life, the universe, and everything?\",\n        history=[\n            {\"role\": \"user\", \"message\": \"Hello!\"},\n            {\"role\": \"assistant\", \"message\": \"Hello! How can I help you today?\"},\n        ],\n    ),\n    {\n        \"token_limit\": 8192, # However many tokens you want to limit to\n        \"tokenizer\": O200KTokenizer,\n    }\n)\n\nopenai.chat.completions.create(\n    ...\n    messages=messages,\n)\n\n\nIn this example, the `chat` component defines a prompt structure. The `SystemMessage` and the latest `UserMessage` are always included. Historical messages are wrapped in `Scope` with `prel=i`, meaning later messages (higher `i`) are prioritized over earlier ones. The `render` function then processes this component, respecting the `token_limit` and including as many high-priority items as possible.\n\n## Why Use PyPriompt\n\nPyPriompt offers a powerful way to manage LLM prompts, especially when dealing with dynamic content and strict token limits. Its core principles revolve around component-based design and priority-driven content inclusion.\n\n### Key Principles:\n\n*   **Component-Based Prompt Design:** Just like in web frameworks, you can create reusable Python components to build complex prompts, making them modular and maintainable.\n*   **Priority System:** Each child within a component can be assigned an absolute (`p`) or relative (`prel`) priority. Higher priority items are favored for inclusion when token limits are approached.\n*   **Token Limit Optimization:** The renderer guarantees that it will find the minimum priority cutoff such that the prompt's total token count stays within the specified limit, maximizing the included relevant information.\n\n### Building Blocks:\n\nPyPriompt provides several specialized components to control prompt structure and content:\n\n*   `Scope`: Sets priorities for its children.\n*   `First`: Includes the first child with sufficiently high priority, useful for fallbacks.\n*   `Empty`: Reserves a specified number of tokens, useful for ensuring space for model generation.\n*   `Capture`: Captures and parses output directly within the prompt.\n*   `Isolate`: Isolates a section with its own token limit, useful for caching or guaranteeing specific content.\n*   `Br`: Forces a token break, useful for precise tokenization control.\n*   `Config`: Specifies common configuration properties like `stop` tokens or `maxResponseTokens`.\n\n### Built-in Components for LLMs:\n\n*   `UserMessage`, `AssistantMessage`, `SystemMessage`: For constructing standard chat-based prompts.\n*   `Image`: For incorporating images into multimodal prompts.\n*   `Tools`: For defining tools that the AI can call using a JSON schema.\n\n### Advanced Features:\n\n*   **Callbacks (`on_eject`, `on_include`):** Execute custom logic when a scope is either excluded or included in the final prompt, allowing for adaptive prompt behavior.\n*   **Sourcemaps:** When enabled, the renderer can compute a map between prompt characters and their originating JSX tree parts, aiding in debugging and caching strategies.\n\n### Important Considerations (Caveats):\n\nWhile powerful, it's important to be aware of certain aspects:\n\n*   Overusing priorities can sometimes be an anti-pattern, potentially making prompts harder to cache.\n*   The current version supports around 10K scopes reasonably fast, which is sufficient for most use cases.\n*   For latency-critical prompts, monitoring performance in a preview dashboard is recommended.\n*   The renderer's token limit optimization is generally accurate but may have slight inaccuracies in specific edge cases involving `First` components.\n\n## Links\n\n*   **GitHub Repository:** [zenbase-ai/py-priompt](https://github.com/zenbase-ai/py-priompt){target=_blank}\n*   **Motivation Article:** [Prompt Design](https://arvid.xyz/prompt-design){target=_blank}","metrics":{"detailViews":1,"githubClicks":3},"dates":{"published":null,"modified":"2025-11-27T12:01:17.000Z"}}