Skip to content

Commit 6de6477

Browse files
Devon-WhiteDevon-White
authored
POM Docs (#176)
* POM * POM docs * POM Documentation additions, SWML pom, css conditional arg add docusaurus types and jsonmodule resolution to tsconfig * fix broken link
1 parent 9f5b2e7 commit 6de6477

File tree

12 files changed

+1382
-43
lines changed

12 files changed

+1382
-43
lines changed

‎docs/home/calling/ai/pom/_category_.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
label: Prompt Object Model (POM)

‎docs/home/calling/ai/pom/_schema.mdx

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
```json
2+
{
3+
"$schema": "https://json-schema.org/draft-07/schema",
4+
"$id": "https://example.com/pom.schema.json",
5+
"title": "Prompt Object Model",
6+
"type": "array",
7+
"items": { "$ref": "#/$defs/section" },
8+
"$defs": {
9+
"section": {
10+
"type": "object",
11+
"properties": {
12+
"title": { "type": "string" },
13+
"body": { "type": "string" },
14+
"bullets": {
15+
"type": "array",
16+
"items": { "type": "string" }
17+
},
18+
"subsections": {
19+
"type": "array",
20+
"items": { "$ref": "#/$defs/section" }
21+
},
22+
"numbered": { "type": "boolean" },
23+
"numberedBullets": { "type": "boolean" }
24+
},
25+
"anyOf": [
26+
{ "required": ["body"] },
27+
{ "required": ["bullets"] }
28+
],
29+
"additionalProperties": false
30+
}
31+
}
32+
}
33+
```

‎docs/home/calling/ai/pom/index.mdx

+341
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
title: 'Prompt object model (POM)'
3+
description: 'A lightweight Python library for structured prompt management with LLMs'
4+
sidebar_position: 0
5+
slug: /ai/pom
6+
---
7+
8+
[technical-reference]: /ai/pom/technical-reference
9+
[sw-ai-services]: /ai
10+
11+
## What is the prompt object model?
12+
13+
The prompt object model (POM) is a structured data format and accompanying Python SDK for composing, organizing,
14+
and rendering prompt instructions for large language models (LLMs).
15+
16+
It provides a tree-based representation of a prompt document composed of nested sections, each of which can include:
17+
18+
- A title.
19+
- A body of explanatory or instructional text.
20+
- An optional list of bullet points, which are additional formatting instructions for the body.
21+
- Optional nested sections, which act as sub-instructions.
22+
23+
:::important
24+
To learn more about how to use the Prompt Object Model, see the [technical reference][technical-reference].
25+
:::
26+
27+
POM supports both machine-readability (via JSON) and structured rendering (via Markdown), making it ideal for prompt templating,
28+
modular editing, and traceable documentation - whether you're using [SignalWire's AI services][sw-ai-services] or another LLM provider.
29+
30+
---
31+
32+
## Why structured prompts matter
33+
34+
Creating effective prompts for LLMs is more than just writing good instructions - the structure and organization of those instructions
35+
significantly impact how well the model responds. Having a poor structured prompt can lead to
36+
inconsistent results, hallucinations, and the AI agent not following the instructions you provided.
37+
38+
### The challenge of prompt engineering
39+
40+
When working with large language models, the structure of your prompts significantly impacts model performance.
41+
Well-structured prompts lead to better results, but maintaining this structure manually becomes challenging.
42+
43+
Manual prompt management introduces formatting inconsistencies, resulting in prompt variability across different application components.
44+
Complex prompt modifications frequently produce formatting errors or unintended behavioral changes.
45+
Development efficiency suffers as common prompt patterns require reimplementation across multiple projects.
46+
Standard version control systems struggle to effectively track changes to complex text prompts, complicating collaborative development.
47+
48+
### How POM solves these challenges
49+
50+
The Prompt Object Model abstracts away the structural maintenance of prompts, allowing you to focus on the content.
51+
52+
POM implements automatic formatting that generates properly structured markdown or JSON, ensuring adherence to prompt engineering
53+
best practices. The framework provides modular organization capabilities that enable logical section and subsection arrangement
54+
mirroring design intent. Programmatic manipulation functions allow targeted modifications to specific prompt elements without
55+
affecting surrounding content. The structured format enhances version control integration, facilitating meaningful change
56+
tracking throughout development cycles.
57+
58+
### Benefits for evolving prompts
59+
60+
As prompt engineering grows more sophisticated, POM provides several key advantages. The framework enables clarity through
61+
logical separation of instruction types (system, task-specific, constraints). Its architecture supports scalability,
62+
allowing engineers to effortlessly add, remove, or reorder sections as prompt complexity increases.
63+
64+
POM furnishes granular control for precise adjustments to specific prompt components while enforcing consistency across multiple prompts.
65+
The model's template system facilitates reusability, enabling customization for diverse contexts. Additionally,
66+
POM's markdown rendering capabilities enhance auditability, supporting both human review and direct LLM consumption of prompt documents.
67+
68+
---
69+
70+
## Getting started
71+
72+
### Installation
73+
74+
To get started, install the `signalwire-pom` package using pip:
75+
76+
```bash
77+
pip install signalwire-pom
78+
```
79+
80+
### Basic usage
81+
82+
The following example demonstrates how to create a new POM and add a section with a title and body with a list of bullets.
83+
84+
```python
85+
from signalwire_pom import PromptObjectModel
86+
87+
# Create a new POM
88+
pom = PromptObjectModel()
89+
90+
# Add a section with title and body
91+
section = pom.add_section(
92+
"System instructions",
93+
body="You are a helpful AI assistant."
94+
)
95+
96+
# Add bullet points
97+
section.add_bullets([
98+
"Answer user questions accurately",
99+
"Be concise and clear"
100+
])
101+
102+
# Render as markdown
103+
markdown = pom.render_markdown()
104+
print(markdown)
105+
```
106+
107+
The above code will produce the following output:
108+
109+
```markdown
110+
## System instructions
111+
112+
You are a helpful AI assistant.
113+
114+
- Answer user questions accurately
115+
- Be concise and clear
116+
```
117+
118+
### Complete example
119+
120+
Here's a more complete example showing how to create a structured prompt for an AI assistant:
121+
122+
```python
123+
from signalwire_pom import PromptObjectModel
124+
125+
# Create a new POM
126+
pom = PromptObjectModel()
127+
128+
# Create main sections for an LLM prompt
129+
objective = pom.add_section(
130+
"Objective",
131+
body="You are an AI assistant built to help users draft professional emails."
132+
)
133+
objective.add_bullets([
134+
"Listen carefully to the user's requirements",
135+
"Draft concise, clear, and professional emails",
136+
"Provide options when appropriate"
137+
])
138+
139+
# Add personality section
140+
personality = pom.add_section(
141+
"Personality",
142+
body="You should present yourself with these traits:"
143+
)
144+
personality.add_bullets([
145+
"Professional but approachable",
146+
"Clear and concise in communication",
147+
"Helpful without being overly verbose"
148+
])
149+
150+
# Add capabilities section with nested subsections
151+
capabilities = pom.add_section(
152+
"Capabilities",
153+
body="You can perform the following email-related tasks:"
154+
)
155+
156+
# Add subsections
157+
drafting = capabilities.add_subsection(
158+
"Email drafting",
159+
body="Create email drafts based on user specifications."
160+
)
161+
drafting.add_bullets([
162+
"Format emails properly with greeting, body, and signature",
163+
"Adjust tone based on recipient and purpose",
164+
"Include necessary information while being concise"
165+
])
166+
167+
reviewing = capabilities.add_subsection(
168+
"Email review",
169+
body="Analyze and improve existing email drafts."
170+
)
171+
reviewing.add_bullets([
172+
"Check for grammar and spelling issues",
173+
"Suggest improvements for clarity and tone",
174+
"Identify missing information"
175+
])
176+
177+
# Generate markdown
178+
markdown = pom.render_markdown()
179+
print(markdown)
180+
181+
json = pom.to_json()
182+
print(json)
183+
```
184+
185+
#### Output
186+
187+
The above code will produce the two outputs, depending on whether you call `render_markdown()` or `to_json()`:
188+
189+
<Tabs>
190+
<TabItem value="markdown" label="Markdown Output">
191+
192+
```markdown
193+
## Objective
194+
195+
You are an AI assistant built to help users draft professional emails.
196+
197+
- Listen carefully to the user's requirements
198+
- Draft concise, clear, and professional emails
199+
- Provide options when appropriate
200+
201+
## Personality
202+
203+
You should present yourself with these traits:
204+
205+
- Professional but approachable
206+
- Clear and concise in communication
207+
- Helpful without being overly verbose
208+
209+
## Capabilities
210+
211+
You can perform the following email-related tasks:
212+
213+
### Email drafting
214+
215+
Create email drafts based on user specifications.
216+
217+
- Format emails properly with greeting, body, and signature
218+
- Adjust tone based on recipient and purpose
219+
- Include necessary information while being concise
220+
221+
### Email review
222+
223+
Analyze and improve existing email drafts.
224+
225+
- Check for grammar and spelling issues
226+
- Suggest improvements for clarity and tone
227+
- Identify missing information
228+
```
229+
230+
</TabItem>
231+
232+
<TabItem value="json" label="JSON Output">
233+
234+
```json
235+
[
236+
{
237+
"title": "Objective",
238+
"body": "You are an AI assistant built to help users draft professional emails.",
239+
"bullets": [
240+
"Listen carefully to the user's requirements",
241+
"Draft concise, clear, and professional emails",
242+
"Provide options when appropriate"
243+
],
244+
"subsections": []
245+
},
246+
{
247+
"title": "Personality",
248+
"body": "You should present yourself with these traits:",
249+
"bullets": [
250+
"Professional but approachable",
251+
"Clear and concise in communication",
252+
"Helpful without being overly verbose"
253+
],
254+
"subsections": []
255+
},
256+
{
257+
"title": "Capabilities",
258+
"body": "You can perform the following email-related tasks:",
259+
"bullets": [],
260+
"subsections": [
261+
{
262+
"title": "Email drafting",
263+
"body": "Create email drafts based on user specifications.",
264+
"bullets": [
265+
"Format emails properly with greeting, body, and signature",
266+
"Adjust tone based on recipient and purpose",
267+
"Include necessary information while being concise"
268+
],
269+
"subsections": []
270+
},
271+
{
272+
"title": "Email review",
273+
"body": "Analyze and improve existing email drafts.",
274+
"bullets": [
275+
"Check for grammar and spelling issues",
276+
"Suggest improvements for clarity and tone",
277+
"Identify missing information"
278+
],
279+
"subsections": []
280+
}
281+
]
282+
}
283+
]
284+
```
285+
286+
</TabItem>
287+
<TabItem value="xml" label="XML Output">
288+
289+
```xml
290+
<?xml version="1.0" encoding="UTF-8"?>
291+
<prompt>
292+
<section>
293+
<title>Objective</title>
294+
<body>You are an AI assistant built to help users draft professional emails.</body>
295+
<bullets>
296+
<bullet>Listen carefully to the user's requirements</bullet>
297+
<bullet>Draft concise, clear, and professional emails</bullet>
298+
<bullet>Provide options when appropriate</bullet>
299+
</bullets>
300+
</section>
301+
<section>
302+
<title>Personality</title>
303+
<body>You should present yourself with these traits:</body>
304+
<bullets>
305+
<bullet>Professional but approachable</bullet>
306+
<bullet>Clear and concise in communication</bullet>
307+
<bullet>Helpful without being overly verbose</bullet>
308+
</bullets>
309+
</section>
310+
<section>
311+
<title>Capabilities</title>
312+
<body>You can perform the following email-related tasks:</body>
313+
<subsections>
314+
<section>
315+
<title>Email drafting</title>
316+
<body>Create email drafts based on user specifications.</body>
317+
<bullets>
318+
<bullet>Format emails properly with greeting, body, and signature</bullet>
319+
<bullet>Adjust tone based on recipient and purpose</bullet>
320+
<bullet>Include necessary information while being concise</bullet>
321+
</bullets>
322+
</section>
323+
<section>
324+
<title>Email review</title>
325+
<body>Analyze and improve existing email drafts.</body>
326+
<bullets>
327+
<bullet>Check for grammar and spelling issues</bullet>
328+
<bullet>Suggest improvements for clarity and tone</bullet>
329+
<bullet>Identify missing information</bullet>
330+
</bullets>
331+
</section>
332+
</subsections>
333+
</section>
334+
</prompt>
335+
```
336+
</TabItem>
337+
</Tabs>
338+
339+
## Next steps
340+
341+
<GuidesList />

0 commit comments

Comments
 (0)