PromptPack CRD

The PromptPack custom resource defines a versioned collection of prompts for AI agents. The ConfigMap it references must contain a valid PromptPack - a structured JSON/YAML format for packaging multi-prompt conversational systems.

API Version

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: PromptPack

Spec Fields

source

Source of the compiled PromptPack content.

Field	Type	Required
source.configMapRef.name	string	Yes
source.configMapRef.key	string	Yes

spec:
  source:
    configMapRef:
      name: my-prompts
      key: promptpack.json  # Key containing the compiled PromptPack

rollout

Rollout strategy for prompt updates.

Field	Type	Default	Required
rollout.strategy	string	immediate	No
rollout.canary.weight	integer	-	No

spec:
  rollout:
    strategy: canary
    canary:
      weight: 20  # 20% of traffic uses new prompts

Strategies:

• immediate - Updates apply immediately to all agents
• canary - Gradual rollout with traffic splitting

Status Fields

phase

Current phase of the PromptPack.

Value	Description
Pending	Validating source
Active	Prompts are valid and in use
Canary	Canary rollout in progress
Failed	Source validation failed

activeVersion

The currently active prompt version (content hash).

canaryVersion

The canary version during rollout (if applicable).

conditions

Type	Description
SourceValid	ConfigMap exists and has valid content
AgentsNotified	Referencing agents have been notified

ConfigMap Format

The referenced ConfigMap must contain a compiled PromptPack following the PromptPack specification:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-prompts
data:
  promptpack.json: |
    {
      "id": "customer-service",
      "name": "Customer Service Assistant",
      "version": "1.0.0",
      "template_engine": {
        "version": "v1",
        "syntax": "{{variable}}"
      },
      "prompts": {
        "support": {
          "id": "support",
          "name": "General Support",
          "version": "1.0.0",
          "system_template": "You are a helpful customer service agent for {{company_name}}. Be professional, empathetic, and solution-oriented.",
          "variables": [
            {
              "name": "company_name",
              "type": "string",
              "required": true,
              "description": "Name of the company"
            }
          ],
          "parameters": {
            "temperature": 0.7,
            "max_tokens": 1024
          },
          "validators": {
            "banned_words": ["competitor", "lawsuit"]
          }
        }
      },
      "metadata": {
        "domain": "customer-service",
        "language": "en",
        "tags": ["support", "helpdesk"]
      }
    }

PromptPack Structure

Field	Type	Required	Description
id	string	Yes	Unique identifier (lowercase, hyphens allowed)
name	string	Yes	Human-readable name
version	string	Yes	Semantic version (MAJOR.MINOR.PATCH)
template_engine	object	Yes	Template configuration
prompts	object	Yes	Map of prompt definitions
metadata	object	No	Domain, language, tags
tools	object	No	Tool definitions for function calling
fragments	object	No	Reusable template fragments

For the complete specification, see promptpack.org.

Canary Rollout

Start Canary

spec:
  rollout:
    strategy: canary
    canary:
      weight: 10  # Start with 10%

Increase Traffic

Update the weight to increase canary traffic:

spec:
  rollout:
    canary:
      weight: 50  # Increase to 50%

Promote to Active

Set weight to 100 to promote canary:

spec:
  rollout:
    canary:
      weight: 100  # Promotes canary to active

The status will transition from Canary to Active.

Example

Complete PromptPack example with canary rollout:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: PromptPack
metadata:
  name: customer-service
  namespace: agents
spec:
  source:
    configMapRef:
      name: cs-prompts-v2
      key: promptpack.json
  rollout:
    strategy: canary
    canary:
      weight: 25

Status after deployment:

status:
  phase: Canary
  activeVersion: "abc123"
  canaryVersion: "def456"
  conditions:
    - type: SourceValid
      status: "True"
    - type: AgentsNotified
      status: "True"
      message: "Notified 3 AgentRuntimes"

Authoring PromptPacks

PromptPacks can be authored in YAML for readability and compiled to JSON:

id: customer-service
name: Customer Service Assistant
version: 1.0.0

template_engine:
  version: v1
  syntax: "{{variable}}"

prompts:
  support:
    id: support
    name: General Support
    version: 1.0.0
    system_template: |
      You are a helpful customer service agent for {{company_name}}.
      Be professional, empathetic, and solution-oriented.

      Guidelines:
      - Always greet the customer warmly
      - Listen actively and acknowledge concerns
      - Provide clear, actionable solutions
    variables:
      - name: company_name
        type: string
        required: true
    parameters:
      temperature: 0.7
      max_tokens: 1024

metadata:
  domain: customer-service
  language: en

Compile with packc:

packc compile customer-service.promptpack.yaml -o promptpack.json