packc compile

Compile all prompts from an arena.yaml configuration into a single pack file.

Synopsis

packc compile --config <arena.yaml> --output <pack-file> --id <pack-id>

Description

The compile command reads an Arena configuration file (arena.yaml) that references multiple prompt YAML files and compiles them all into a single optimized .pack.json file.

This is the primary command for building production packs that contain multiple prompts for your application.

Options

Required

--config <path>

Path to the arena.yaml configuration file
This file lists all prompts to include in the pack
Default: config.arena.yaml

--output <path>

Path where the compiled pack file will be written
Should end in .pack.json
Example: packs/customer-support.pack.json

--id <string>

Unique identifier for this pack
Used by the SDK to reference the pack
Should be kebab-case (e.g., customer-support)
Example: --id customer-support

Examples

Basic Compilation

packc compile \
  --config arena.yaml \
  --output packs/app.pack.json \
  --id my-app

Production Pack

packc compile \
  --config configs/production/arena.yaml \
  --output dist/production.pack.json \
  --id prod-assistant

Multiple Environments

# Development pack
packc compile \
  --config arena.dev.yaml \
  --output packs/app.dev.pack.json \
  --id app-dev

# Production pack
packc compile \
  --config arena.prod.yaml \
  --output packs/app.prod.pack.json \
  --id app-prod

Input: arena.yaml Structure

The arena.yaml file references prompt configurations:

version: "1.0"

prompts:
  - id: customer-support
    path: prompts/support.yaml
  
  - id: sales-assistant
    path: prompts/sales.yaml
  
  - id: technical-expert
    path: prompts/technical.yaml

tools_dir: tools/

Output: Pack File

The command produces a .pack.json file:

{
  "id": "customer-support",
  "name": "Customer Support Pack",
  "version": "1.0.0",
  "template_engine": "go",
  "prompts": {
    "customer-support": {
      "system": "You are a customer support agent...",
      "parameters": {
        "temperature": 0.7,
        "max_tokens": 1000
      }
    },
    "sales-assistant": {
      "system": "You are a sales assistant...",
      "parameters": {
        "temperature": 0.8
      }
    }
  },
  "compilation": {
    "compiled_with": "packc-v0.1.0",
    "created_at": "2024-01-15T10:30:00Z",
    "schema": "1.0"
  }
}

Compilation Process

The compile command performs these steps:

Load Configuration - Read arena.yaml
Parse Prompts - Load all referenced YAML files
Validate - Check for errors and warnings
Compile - Transform to pack format
Optimize - Remove unused data
Write - Save to output file

Exit Codes

0 - Success
1 - Error (invalid config, compilation failure, etc.)

Common Errors

Missing Required Options

$ packc compile --config arena.yaml
Error: --output and --id are required

Solution: Provide both --output and --id:

packc compile --config arena.yaml --output app.pack.json --id my-app

Config File Not Found

Error loading arena config: open arena.yaml: no such file or directory

Solution: Check that the config file exists:

ls -la arena.yaml

Invalid YAML Syntax

Error loading arena config: yaml: line 5: mapping values are not allowed

Solution: Fix YAML syntax errors in arena.yaml or prompt files.

Missing Prompt Files

Error: prompt file not found: prompts/support.yaml

Solution: Ensure all referenced prompt files exist.

Validation Warnings

The compiler may emit warnings for non-fatal issues:

⚠ Media validation warnings for customer-support:
  - Referenced image not found: images/logo.png
  - Template variable 'user_name' not defined

These warnings don’t stop compilation but should be addressed.

Performance

Compilation is fast:

Small packs (1-5 prompts): <100ms
Medium packs (10-20 prompts): <500ms
Large packs (50+ prompts): <2s

Best Practices

1. Organize by Environment

configs/
├── arena.dev.yaml
├── arena.staging.yaml
└── arena.prod.yaml

packs/
├── app.dev.pack.json
├── app.staging.pack.json
└── app.prod.pack.json

2. Use Descriptive Pack IDs

# Good
--id customer-support-v2
--id sales-assistant-prod
--id technical-docs-staging

# Bad
--id pack1
--id app
--id test

3. Version Your Packs

Include version in pack metadata:

# arena.yaml
version: "1.0"
metadata:
  pack_version: "2.1.0"

4. Validate After Compilation

Always validate after compiling:

packc compile --config arena.yaml --output app.pack.json --id my-app
packc validate app.pack.json

5. Store Packs in Version Control

Commit compiled packs to track changes:

git add packs/app.pack.json
git commit -m "chore: update customer support pack"

Integration with CI/CD

GitHub Actions

name: Compile Packs

on: [push]

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install packc
        run: go install github.com/AltairaLabs/PromptKit/tools/packc@latest
      
      - name: Compile packs
        run: |
          packc compile --config arena.yaml --output packs/app.pack.json --id my-app
          packc validate packs/app.pack.json
      
      - name: Upload packs
        uses: actions/upload-artifact@v3
        with:
          name: compiled-packs
          path: packs/

Makefile

.PHONY: compile-packs
compile-packs:
	packc compile --config arena.yaml --output packs/app.pack.json --id my-app
	packc validate packs/app.pack.json

.PHONY: compile-all
compile-all:
	packc compile --config arena.dev.yaml --output packs/app.dev.pack.json --id app-dev
	packc compile --config arena.prod.yaml --output packs/app.prod.pack.json --id app-prod