PromptFrame

LLM-agnostic prompt management — YAML storage, typed loading, structured output support, composable builder API, markdown skills, and a full CLI.

Quick links: [PYPI] - [Full documentation] - [API Reference]

Documentation

📘 [Full documentation]:

Features

• Typed YAML prompt loading — store prompts as structured YAML files and load them as typed Python objects with attribute access
• Environment-aware registry — resolve prompts across layered dev / staging / prod / common directories
• Structured output schema — extend LLMBaseModel to auto-generate input/output JSON schema instructions for any LLM
• Per-field YAML instructions — decouple LLM field instructions from Pydantic models via model_attribute_id
• Fluent builder API — compose prompts from reusable components using >> or | operators
• Markdown skill files — inject rich SKILL.md instruction documents into prompts as reusable context
• Robust JSON parsing — parse LLM responses including partial JSON and markdown-fenced blocks
• Full CLI — scaffold, inspect, validate, lint, render, diff, and export prompt and skill files

Installation

pip install promptframe

Quick Start

1. Loading and using prompts

from promptframe import PromptRegistry

reg = PromptRegistry(base="prompts/", environment="prod", common="shared")

# Load a prompt YAML file
prompts = reg.load_prompt("my_prompts")

# Attribute or dict access
text = prompts.summarize_text.format(text="The quick brown fox...")
text = prompts.prompt_dict["summarize_text"].prompt

2. Assembling prompts with the builder

from promptframe import StructuredPromptBuilder
from promptframe.components import SimplePromptComponent, PromptSectionComponent, InputComponent

prompt = (
    StructuredPromptBuilder()
    >> SimplePromptComponent("You are a helpful assistant.")
    >> PromptSectionComponent(["Be concise", "Avoid jargon"], header="Rules:")
    >> InputComponent()
).build({"input": "What is 2+2?"})

3. Structured output with LLMBaseModel

from pydantic import Field
from promptframe import LLMBaseModel
from promptframe.fields import LLMField

class CustomerOutput(LLMBaseModel):
    name: str = LLMField(..., description="Customer full name", model_attribute_id="customer_name")
    score: int = Field(..., description="Risk score 0-100")

# Plain schema instructions
instructions = CustomerOutput.get_format_instructions()

# With per-field YAML instructions injected
mp = reg.load_model_prompt("field_prompts")
instructions = CustomerOutput.get_format_instructions_with_prompt(
    prompt_model_dict=mp.prompt_model_dict
)

4. Using skills

from promptframe import SkillRegistry, StructuredPromptBuilder
from promptframe.components import SimplePromptComponent, SkillComponent

registry = SkillRegistry("skills/")
skill = registry.get("frontend-design")

prompt = (
    StructuredPromptBuilder()
    >> SimplePromptComponent("You are a frontend expert.")
    >> SkillComponent(skill, sections=["Guidelines"])
    >> SimplePromptComponent("Task: {task}")
).build({"task": "Build a login page"})

5. Parsing LLM responses

from promptframe.parsers import json_parser

result = json_parser(llm_response)          # plain JSON or markdown-fenced
result = json_parser('```json\n{...}\n```') # fenced block

YAML File Formats

type: prompt

version: 1.0

metadata:
  type: prompt
  name: my_prompts
  description: General prompt collection
  tags: [nlp, summarization]
  project: my_project

prompts:
  - pid: summarize_text
    description: Summarize a block of text.
    input_variables:
      - text
    prompt: |
      Summarize the following text:
      {text}

type: model_prompt

Bind per-field LLM instructions to model attributes via model_attribute_id:

version: 1.0

metadata:
  type: model_prompt
  name: field_prompts
  description: Per-field LLM instructions

prompts:
  - pid: clean_name
    description: Clean and normalize a name field.
    model_attribute_id: customer_name
    input_instruction: |
      The input contains {raw_name}.
    output_instruction: |
      Return a cleaned human-readable name.

Skill file (.md with YAML frontmatter)

---
name: frontend-design
description: When to use this skill.
tags: [frontend, react, css]
version: "1.0"
---

## Guidelines

- Use semantic HTML
- Prefer CSS variables for theming

## Examples

Provide examples here.

Project Layout

The recommended directory structure for a promptframe project:

prompts/
├── common/          # shared prompts across all environments
├── dev/
├── staging/
└── prod/            # environment-specific overrides

skills/
├── frontend-design/
│   └── SKILL.md
└── data-analysis/
    └── SKILL.md

Scaffold this structure with the CLI:

promptframe scaffold prompts/ --example

Prompt Components

CLI Reference

promptframe --help

API Documentation

Full API reference is available in the docs/ folder:

• Overview & Quick Start
• Models
• PromptRegistry
• LLMBaseModel
• Prompt Components
• StructuredPromptBuilder
• Skills
• LLMField
• Parsers
• Exceptions
• CLI