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.

The controller validates the pack.json content against the published PromptPack JSON Schema to ensure conformance before activating the prompts.

API version

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

Short name: pp (e.g. kubectl get pp).

Spec fields

packName

Logical pack identity. Required, and immutable after create — versions of the same pack share a packName.

spec:
  packName: customer-service

source

Source of the compiled PromptPack content.

Field	Type	Required	Description
source.type	string	Yes	Source type: configmap
source.configMapRef.name	string	Yes	Name of the ConfigMap

The ConfigMap must contain a pack.json key with valid PromptPack JSON content.

spec:
  source:
    type: configmap
    configMapRef:
      name: my-prompts  # ConfigMap must have pack.json key

Status fields

phase

Current phase of the PromptPack.

Value	Description
Pending	Validating source
Active	Prompts are valid and in use
Superseded	A newer version has replaced this pack
Failed	Source validation failed

activeVersion

The currently active prompt version (content hash).

conditions

Type	Description
SourceValid	ConfigMap exists and contains pack.json key
SchemaValid	pack.json content conforms to the PromptPack schema
AgentsNotified	Referencing agents have been notified

The controller performs two-phase validation:

1. Source Validation - Verifies the ConfigMap exists and contains the pack.json key
2. Schema Validation - Validates the JSON content against the published PromptPack schema

If either validation fails, Kubernetes events are emitted with detailed error messages:

# View validation events
kubectl describe promptpack my-prompts

# Events:
#   Warning  SchemaValidationFailed  pack.json validation failed: (root): id is required

ConfigMap format

The referenced ConfigMap must contain a pack.json key with a compiled PromptPack following the PromptPack specification:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-prompts
data:
  pack.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.

Example

Complete PromptPack example:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: PromptPack
metadata:
  name: customer-service
  namespace: agents
spec:
  packName: customer-service
  version: "2.0.0"
  source:
    type: configmap
    configMapRef:
      name: cs-prompts-v2

Status after deployment:

status:
  phase: Active
  activeVersion: "2.0.0"
  conditions:
    - type: SourceValid
      status: "True"
      reason: SourceValid
      message: "Source configuration is valid"
    - type: SchemaValid
      status: "True"
      reason: SchemaValid
      message: "pack.json content is valid"
    - type: AgentsNotified
      status: "True"
      reason: AgentsNotified
      message: "Notified 3 AgentRuntime(s)"

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 --config arena.yaml --output pack.json --id customer-service

Then create a ConfigMap:

kubectl create configmap my-prompts --from-file=pack.json