Skip to main content

Prompt object model (POM)

What is the prompt object model?​

The prompt object model (POM) is a structured data format and accompanying Python SDK for composing, organizing, and rendering prompt instructions for large language models (LLMs).

It provides a tree-based representation of a prompt document composed of nested sections, each of which can include:

  • A title.
  • A body of explanatory or instructional text.
  • An optional list of bullet points, which are additional formatting instructions for the body.
  • Optional nested sections, which act as sub-instructions.
important

To learn more about how to use the Prompt Object Model, see the technical reference.

POM supports both machine-readability (via JSON) and structured rendering (via Markdown), making it ideal for prompt templating, modular editing, and traceable documentation - whether you're using SignalWire's AI services or another LLM provider.

Why structured prompts matter​

Creating effective prompts for LLMs is more than just writing good instructions - the structure and organization of those instructions significantly impact how well the model responds. Having a poor structured prompt can lead to inconsistent results, hallucinations, and the AI agent not following the instructions you provided.

The challenge of prompt engineering​

When working with large language models, the structure of your prompts significantly impacts model performance. Well-structured prompts lead to better results, but maintaining this structure manually becomes challenging.

Manual prompt management introduces formatting inconsistencies, resulting in prompt variability across different application components. Complex prompt modifications frequently produce formatting errors or unintended behavioral changes. Development efficiency suffers as common prompt patterns require reimplementation across multiple projects. Standard version control systems struggle to effectively track changes to complex text prompts, complicating collaborative development.

How POM solves these challenges​

The Prompt Object Model abstracts away the structural maintenance of prompts, allowing you to focus on the content.

POM implements automatic formatting that generates properly structured markdown or JSON, ensuring adherence to prompt engineering best practices. The framework provides modular organization capabilities that enable logical section and subsection arrangement mirroring design intent. Programmatic manipulation functions allow targeted modifications to specific prompt elements without affecting surrounding content. The structured format enhances version control integration, facilitating meaningful change tracking throughout development cycles.

Benefits for evolving prompts​

As prompt engineering grows more sophisticated, POM provides several key advantages. The framework enables clarity through logical separation of instruction types (system, task-specific, constraints). Its architecture supports scalability, allowing engineers to effortlessly add, remove, or reorder sections as prompt complexity increases.

POM furnishes granular control for precise adjustments to specific prompt components while enforcing consistency across multiple prompts. The model's template system facilitates reusability, enabling customization for diverse contexts. Additionally, POM's markdown rendering capabilities enhance auditability, supporting both human review and direct LLM consumption of prompt documents.

Getting started​

Installation​

To get started, install the signalwire-pom package using pip:

pip install signalwire-pom

Basic usage​

The following example demonstrates how to create a new POM and add a section with a title and body with a list of bullets.

from signalwire_pom import PromptObjectModel

# Create a new POM
pom = PromptObjectModel()

# Add a section with title and body
section = pom.add_section(
    "System instructions", 
    body="You are a helpful AI assistant."
)

# Add bullet points
section.add_bullets([
    "Answer user questions accurately",
    "Be concise and clear"
])

# Render as markdown
markdown = pom.render_markdown()
print(markdown)

The above code will produce the following output:

## System instructions

You are a helpful AI assistant.

- Answer user questions accurately
- Be concise and clear

Complete example​

Here's a more complete example showing how to create a structured prompt for an AI assistant:

from signalwire_pom import PromptObjectModel

# Create a new POM
pom = PromptObjectModel()

# Create main sections for an LLM prompt
objective = pom.add_section(
    "Objective", 
    body="You are an AI assistant built to help users draft professional emails."
)
objective.add_bullets([
    "Listen carefully to the user's requirements",
    "Draft concise, clear, and professional emails",
    "Provide options when appropriate"
])

# Add personality section
personality = pom.add_section(
    "Personality",
    body="You should present yourself with these traits:"
)
personality.add_bullets([
    "Professional but approachable",
    "Clear and concise in communication",
    "Helpful without being overly verbose"
])

# Add capabilities section with nested subsections
capabilities = pom.add_section(
    "Capabilities",
    body="You can perform the following email-related tasks:"
)

# Add subsections
drafting = capabilities.add_subsection(
    "Email drafting",
    body="Create email drafts based on user specifications."
)
drafting.add_bullets([
    "Format emails properly with greeting, body, and signature",
    "Adjust tone based on recipient and purpose",
    "Include necessary information while being concise"
])

reviewing = capabilities.add_subsection(
    "Email review",
    body="Analyze and improve existing email drafts."
)
reviewing.add_bullets([
    "Check for grammar and spelling issues",
    "Suggest improvements for clarity and tone",
    "Identify missing information"
])

# Generate markdown
markdown = pom.render_markdown()
print(markdown)

json = pom.to_json()
print(json)

Output​

The above code will produce the two outputs, depending on whether you call render_markdown() or to_json():

## Objective

You are an AI assistant built to help users draft professional emails.

- Listen carefully to the user's requirements
- Draft concise, clear, and professional emails
- Provide options when appropriate

## Personality

You should present yourself with these traits:

- Professional but approachable
- Clear and concise in communication
- Helpful without being overly verbose

## Capabilities

You can perform the following email-related tasks:

### Email drafting

Create email drafts based on user specifications.

- Format emails properly with greeting, body, and signature
- Adjust tone based on recipient and purpose
- Include necessary information while being concise

### Email review

Analyze and improve existing email drafts.

- Check for grammar and spelling issues
- Suggest improvements for clarity and tone
- Identify missing information

Next steps​