POM Docs

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

@@ -0,0 +1 @@
+label: Prompt Object Model (POM)

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

@@ -0,0 +1,33 @@
+```json
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://example.com/pom.schema.json",
+  "title": "Prompt Object Model",
+  "type": "array",
+  "items": { "$ref": "#/$defs/section" },
+  "$defs": {
+    "section": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" },
+        "body": { "type": "string" },
+        "bullets": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "subsections": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/section" }
+        },
+        "numbered": { "type": "boolean" },
+        "numberedBullets": { "type": "boolean" }
+      },
+      "anyOf": [
+        { "required": ["body"] },
+        { "required": ["bullets"] }
+      ],
+      "additionalProperties": false
+    }
+  }
+}
+```

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

@@ -0,0 +1,341 @@
+---
+title: 'Prompt object model (POM)'
+description: 'A lightweight Python library for structured prompt management with LLMs'
+sidebar_position: 0
+slug: /ai/pom
+---
+
+[technical-reference]: /ai/pom/technical-reference
+[sw-ai-services]: /ai
+
+## 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][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][sw-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:
+
+```bash
+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.
+
+```python
+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:
+
+```markdown
+## 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:
+
+```python
+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()`:
+
+<Tabs>
+<TabItem value="markdown" label="Markdown Output">
+
+```markdown
+## 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
+```
+
+</TabItem>
+
+<TabItem value="json" label="JSON Output">
+
+```json
+[
+  {
+    "title": "Objective",
+    "body": "You are an AI assistant built to help users draft professional emails.",
+    "bullets": [
+      "Listen carefully to the user's requirements",
+      "Draft concise, clear, and professional emails",
+      "Provide options when appropriate"
+    ],
+    "subsections": []
+  },
+  {
+    "title": "Personality",
+    "body": "You should present yourself with these traits:",
+    "bullets": [
+      "Professional but approachable",
+      "Clear and concise in communication",
+      "Helpful without being overly verbose"
+    ],
+    "subsections": []
+  },
+  {
+    "title": "Capabilities",
+    "body": "You can perform the following email-related tasks:",
+    "bullets": [],
+    "subsections": [
+      {
+        "title": "Email drafting",
+        "body": "Create email drafts based on user specifications.",
+        "bullets": [
+          "Format emails properly with greeting, body, and signature",
+          "Adjust tone based on recipient and purpose",
+          "Include necessary information while being concise"
+        ],
+        "subsections": []
+      },
+      {
+        "title": "Email review",
+        "body": "Analyze and improve existing email drafts.",
+        "bullets": [
+          "Check for grammar and spelling issues",
+          "Suggest improvements for clarity and tone",
+          "Identify missing information"
+        ],
+        "subsections": []
+      }
+    ]
+  }
+]
+```
+
+</TabItem>
+<TabItem value="xml" label="XML Output">
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<prompt>
+  <section>
+    <title>Objective</title>
+    <body>You are an AI assistant built to help users draft professional emails.</body>
+    <bullets>
+      <bullet>Listen carefully to the user's requirements</bullet>
+      <bullet>Draft concise, clear, and professional emails</bullet>
+      <bullet>Provide options when appropriate</bullet>
+    </bullets>
+  </section>
+  <section>
+    <title>Personality</title>
+    <body>You should present yourself with these traits:</body>
+    <bullets>
+      <bullet>Professional but approachable</bullet>
+      <bullet>Clear and concise in communication</bullet>
+      <bullet>Helpful without being overly verbose</bullet>
+    </bullets>
+  </section>
+  <section>
+    <title>Capabilities</title>
+    <body>You can perform the following email-related tasks:</body>
+    <subsections>
+      <section>
+        <title>Email drafting</title>
+        <body>Create email drafts based on user specifications.</body>
+        <bullets>
+          <bullet>Format emails properly with greeting, body, and signature</bullet>
+          <bullet>Adjust tone based on recipient and purpose</bullet>
+          <bullet>Include necessary information while being concise</bullet>
+        </bullets>
+      </section>
+      <section>
+        <title>Email review</title>
+        <body>Analyze and improve existing email drafts.</body>
+        <bullets>
+          <bullet>Check for grammar and spelling issues</bullet>
+          <bullet>Suggest improvements for clarity and tone</bullet>
+          <bullet>Identify missing information</bullet>
+        </bullets>
+      </section>
+    </subsections>
+  </section>
+</prompt>
+```
+</TabItem>
+</Tabs>
+
+## Next steps
+
+<GuidesList />