promptree 0.2.0

Type-safe Jinja prompt trees with runtime validation and generated Python stubs.

promptree

promptree turns a directory of Jinja templates into a type-safe Python prompt tree, with runtime validation and generated .pyi stubs for IDE autocomplete.

It gives you:

• Dot-notation access to prompt folders and files
• Runtime validation through Jinja StrictUndefined
• Generated .pyi stubs for IDE autocomplete
• Full Jinja support, including include, extends, and macros
• Raw strings as the only integration format, so there is no adapter layer

Install

pip install promptree

Optional extras:

pip install promptree[watch]
pip install promptree[pydantic-ai]

Quick Start

Directory layout:

prompts/
├── system.md
└── user/
    ├── greeting.md
    └── farewell.txt

Example templates:

{# prompts/system.md #}
System prompt for {{ name }}.

{# prompts/user/greeting.md #}
Hello {{ name }}!

{# prompts/user/farewell.txt #}
Goodbye {{ name }}.

Use them from Python:

from promptree import Promptree

prompts = Promptree("./prompts")

print(prompts.system(name="Claude"))
print(prompts.user.greeting(name="Tim"))
print(prompts.user.farewell(name="Tim"))

This direct Promptree(...) usage is runtime-dynamic. Editors can execute the code correctly, but they cannot infer from the filesystem whether prompts.system is a directory node or a template file. For precise VS Code autocomplete and call signatures, generate the prompt package and import its tree object:

promptree generate ./prompts

from prompts import tree

print(tree.system(name="Claude"))
print(tree.user.greeting(name="Tim"))

The CLI can generate an importable package and matching type stubs inside the prompt directory:

promptree generate ./prompts
promptree check ./prompts
promptree --version

For local VS Code navigation with absolute file links:

promptree generate ./prompts --stub-link-mode file-uri

You can also run the CLI as a module:

python -m promptree generate ./prompts

Pre-commit And CI

promptree check regenerates the stubs in memory and exits non-zero if the files on disk are stale. That makes it useful for both local pre-commit enforcement and CI.

If you keep a hand-written __init__.py in a prompt directory, promptree generate will leave it alone and promptree check will ignore that file.

The repository includes a hook definition in .pre-commit-hooks.yaml, and a consumer can wire it up like this:

- repo: https://github.com/your-org/promptree
  rev: v0.1.0
  hooks:
    - id: promptree-check
      files: ^prompts/

For CI, run the same command directly:

promptree check ./prompts

Why No Adapter Layer

Rendered prompt text is the common format across libraries like pydantic_ai, LangChain, and the OpenAI Python client. promptree focuses on generating and validating that text well, rather than wrapping every downstream API.

If you want IDE type safety, prefer importing the generated prompt package over constructing Promptree(...) inline in application code.

pydantic_ai

Full runnable example:

from dataclasses import dataclass

from pydantic_ai import Agent, RunContext
from prompts import tree as prompts


@dataclass
class MyDeps:
    user_name: str
    language: str


agent = Agent("openai:gpt-4o", deps_type=MyDeps)

# Static: render once at agent creation
agent_static = Agent(
    "openai:gpt-4o",
    instructions=prompts.system(name="Claude"),
)


# Dynamic: re-evaluated every run with access to ctx.deps
@agent.instructions
def dynamic_instructions(ctx: RunContext[MyDeps]) -> str:
    return prompts.system(
        name=ctx.deps.user_name,
        language=ctx.deps.language,
    )


result = agent.run_sync(
    prompts.user.greeting(name="Tim"),
    deps=MyDeps(user_name="Tim", language="en"),
)
print(result.output)

LangChain

from langchain_core.messages import HumanMessage, SystemMessage

from promptree import Promptree

prompts = Promptree("./prompts")

messages = [
    SystemMessage(content=prompts.system(name="Claude")),
    HumanMessage(content=prompts.user.greeting(name="Tim")),
]

Raw OpenAI Client

from openai import OpenAI

from promptree import Promptree

client = OpenAI()
prompts = Promptree("./prompts")

client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": prompts.system(name="Claude")},
        {"role": "user", "content": prompts.user.greeting(name="Tim")},
    ],
)

Generated Package

When you run promptree generate ./prompts, promptree writes two files into the prompt directory:

• __init__.py with a tree object backed by Promptree
• __init__.pyi with nested classes and typed call signatures for autocomplete

Generated template stubs also embed:

• a Markdown source link
• the first 10 non-empty lines of the underlying template text

This does not force VS Code to jump directly into the .md or .jinja file on Go to Definition, but it does make the generated symbol carry a useful source reference and prompt excerpt in the stub itself.

Stub source links support two modes:

• relative (default): emits links like [Source](./src/docmist/prompts/...), suitable for portable, committable generated files
• file-uri: emits links like [Source](file:///...), useful when VS Code only treats absolute local file links as clickable

Configure this with --stub-link-mode relative or --stub-link-mode file-uri.

You can tune the excerpt length with --stub-source-lines N on both generate and check.

That means you can import the generated package and get both runtime access and IDE support from the same directory.