Overview ¶

Package promptloom provides a modular prompt management system for LLM applications.

PromptLoom allows you to define reusable prompt components, organize them into profiles with inheritance, and assemble complete prompts based on runtime context.

Core Concepts ¶

Components are reusable prompt fragments defined in YAML:

name: greeting
description: A friendly greeting component
instructions: |
  Hello! I'm here to help you today.

Profiles combine components and can inherit from other profiles:

name: assistant
inherits: base
components:
  - greeting
  - instructions
  - formatting

Context provides runtime values for conditional assembly:

ctx := promptloom.NewContext().
    SetFlag("has_agent", true).
    SetValue("user_name", "Alice").
    SetNumber("max_tokens", 4096)

Basic Usage ¶

Load components and profiles from a filesystem:

registry := promptloom.NewRegistry()
store := storage.NewEmbedStorage(promptsFS, "prompts")
if err := registry.LoadFromFS(store.FS(), store.RootPath()); err != nil {
    log.Fatal(err)
}

Assemble a prompt:

assembler := promptloom.NewAssembler(registry)
ctx := promptloom.NewContext().SetFlag("verbose", true)
prompt, err := assembler.Assemble("my-profile", ctx)

Conditional Components ¶

Components can have conditions that determine when they're included:

name: agent_mode
condition: has_agent
instructions: |
  You have access to tools and can take actions.

Conditions support boolean logic, comparisons, and advanced operators:

Boolean operators:

• Simple flags: "has_agent"
• Negation: "!has_agent"
• AND: "has_agent && is_premium"
• OR: "has_agent || is_demo"
• Parentheses: "(a || b) && c" for grouping

Comparison operators:

• String equality: "tier == 'premium'", "model != 'gpt-3'"
• Numeric: "count > 10", "limit <= 100", "value == 42"

Membership operator:

• In arrays: "tier in ['free', 'premium', 'enterprise']"
• Numeric arrays: "priority in [1, 2, 3]"

Existence checks:

• Exists: "tier exists" (true if variable is set, even if empty)
• Not exists: "legacy_field !exists"

Dot notation for nested Data access:

• Simple: "user.role == 'admin'"
• Deep: "config.features.beta exists"
• With operators: "user.role in ['admin', 'mod']"

Ordered Sections with Conditions and Priorities ¶

Components can have ordered sections with individual conditions and priorities:

name: features
instructions: Base instructions.
ordered_sections:
  - name: safety
    priority: 100
    content: Safety guidelines (always first).
  - name: premium
    priority: 50
    condition: is_premium
    content: Premium features enabled.
  - name: basic
    priority: 25
    content: Basic features.

Sections are sorted by priority (highest first) and can have their own condition expressions using the same syntax as component conditions. Sections with equal priority maintain their definition order. Sections inherit both the component's role and template setting.

Component Dependencies ¶

Components can declare dependencies on other components using depends_on:

name: advanced_features
depends_on: base_features    # Single dependency
instructions: |
  Advanced features that require base features.

name: premium_advanced
depends_on: [base, premium]  # Multiple dependencies (all required)
instructions: |
  Premium advanced features.

If any dependency was not included (due to condition evaluation or not being in the profile), the dependent component is automatically skipped. Dependencies must appear earlier in the profile's component list. This naturally prevents circular dependencies.

Template Variables ¶

Enable template processing to inject Context values into prompts:

name: personalized
template: true
instructions: |
  Hello {{.Values.user_name}}! You have {{.Numbers.message_count}} messages.
  {{if .Flags.premium}}Premium features are enabled.{{end}}

Available template variables:

• {{.Flags.name}} - boolean flags
• {{.Values.name}} - string values
• {{.Numbers.name}} - integer values
• {{.Data.name}} - arbitrary data
• {{.Component.Name}} - current component name
• {{.Component.Data.key}} - component's custom data

Profile Inheritance ¶

Profiles can inherit from parent profiles:

name: claude-sonnet
inherits: claude
overrides:
  preferred_keywords:
    - "step by step"

Child profiles inherit components and overrides from parents, with child values taking precedence.

Provider-Aware Profiles ¶

Profiles can be organized by LLM provider using a naming convention. Provider-specific variants use the pattern "{base}.{provider}":

# profiles/assistant.yaml - universal base
name: assistant
components:
  - base_instructions
  - safety_rules

# profiles/assistant.anthropic.yaml - Anthropic variant
name: assistant.anthropic
inherits: assistant           # REQUIRED for provider variants
provider: anthropic
components:
  - anthropic_persona

When assembling with a provider set in context, the assembler automatically resolves to the provider-specific variant if it exists:

ctx := promptloom.NewContext().SetProvider("anthropic")
messages, _ := assembler.AssembleMessages("assistant", ctx)
// Uses "assistant.anthropic" because it exists

ctx2 := promptloom.NewContext().SetProvider("unknown")
messages2, _ := assembler.AssembleMessages("assistant", ctx2)
// Falls back to "assistant" because "assistant.unknown" doesn't exist

Provider variant profiles MUST inherit from their base profile. This is validated at registry validation time. The naming convention ensures that updating the base profile automatically affects all variants through inheritance.

Helper methods for querying provider variants:

providers := registry.GetProviderVariants("assistant")
// Returns []string{"anthropic", "openai"} if those variants exist

exists := registry.HasProviderVariant("assistant", "anthropic")
// Returns true if assistant.anthropic exists and inherits from assistant

Validation ¶

Validate the registry to catch configuration errors:

if err := registry.Validate(); err != nil {
    log.Fatal(err) // Catches circular inheritance
}

// Strict mode also checks for unknown component references
if err := registry.ValidateStrict(); err != nil {
    log.Fatal(err)
}

Debugging ¶

Use AssembleWithTrace to debug complex profiles and access profile metadata:

prompt, trace, err := assembler.AssembleWithTrace("profile", ctx)
fmt.Println("Included:", trace.IncludedComponents)
fmt.Println("Skipped:", trace.SkippedComponents)
fmt.Println("Conditions:", trace.ConditionResults)

// Access resolved profile with overrides and metadata
profile := trace.ResolvedProfile
keywords := profile.Overrides.PreferredKeywords
modelID := profile.GetDataString("model_id")

Message-Based Assembly ¶

For LLM APIs that expect structured messages (like OpenAI, Anthropic), use AssembleMessages to get a slice of Message structs instead of a single string:

messages, err := assembler.AssembleMessages("profile", ctx)
// messages is []Message with Role and Content fields

Components can specify a role (system, user, assistant):

name: user_input
role: user
instructions: |
  What is the weather today?

If no role is specified, components default to "system". Adjacent components with the same role are automatically merged into a single message:

// Two system components back-to-back become one system message
messages, _ := assembler.AssembleMessages("profile", ctx)
// messages[0].Role == "system"
// messages[0].Content == "First component.\n\nSecond component."

ModelInstructions and Overrides.Suffix are appended to the last system message. If no system message exists (all components are user/assistant roles), these values are skipped as they are supplementary to system content.

Provider Formatters ¶

Different LLM APIs have different message formats. Optional sub-packages under format/ convert PromptLoom messages to provider-specific formats:

import "github.com/lirancohen/promptloom/format/openai"
import "github.com/lirancohen/promptloom/format/anthropic"

messages, _ := assembler.AssembleMessages("profile", ctx)

// Convert to OpenAI format (keeps system messages in array)
openaiMsgs := openai.Format(messages)

// Convert to Anthropic format (extracts system to top-level field)
anthropicReq := anthropic.Format(messages)

OpenAI's format keeps system messages in the messages array, while Anthropic requires system messages as a separate top-level parameter. The formatters handle these differences automatically.

Users can implement the format.Formatter interface for custom providers.

Prompt Chaining ¶

For multi-step workflows where one LLM response feeds into the next prompt, reuse the same Context object and set intermediate results as values:

ctx := promptloom.NewContext()

// Step 1: Analyze
messages1, _ := assembler.AssembleMessages("analyze", ctx)
response1 := callLLM(messages1)

// Step 2: Use analysis in next prompt
ctx.SetValue("analysis", response1)
messages2, _ := assembler.AssembleMessages("synthesize", ctx)
response2 := callLLM(messages2)

The "synthesize" profile uses a template component to inject the previous response:

name: synthesize_prompt
template: true
instructions: |
  Based on this analysis:
  {{.Values.analysis}}

  Please synthesize the key findings.

This pattern keeps orchestration logic in your application code while PromptLoom handles prompt composition. You can chain any number of steps by continuing to set values and assemble new prompts.

Assembly Behavior ¶

Assemble fails fast on missing components and validates inputs automatically:

prompt, err := assembler.Assemble("profile", ctx)
if err != nil {
    log.Fatal(err) // Fails if component missing or required inputs missing
}

If a profile has an InputSchema, defaults are applied and required inputs are validated automatically during assembly. No separate validation call needed.

Profile Metadata ¶

Profiles can store arbitrary metadata with type-safe accessors:

name: my-profile
metadata:
  model_id: "gpt-4"
  max_tokens: 4096
  preferred_keywords: ["helpful", "concise"]

profile := registry.GetProfile("my-profile")
modelID := profile.GetDataString("model_id")
maxTokens := profile.GetDataInt("max_tokens")
keywords := profile.GetDataStrings("preferred_keywords")

Version and Tags ¶

Profiles can have versions and tags for organization and inheritance:

name: assistant-v2
version: "2.0.0"
tags:
  - production
  - vision
  - premium

Tags are inherited when a profile inherits from another. Access tags directly via profile.Tags or use slices.Contains for membership checks.

Input Schema ¶

Profiles can declare expected inputs for documentation and validation:

name: my-profile
input_schema:
  inputs:
    - name: user_name
      type: string
      required: true
      description: The user's display name
    - name: is_premium
      type: flag
      default: false

When a profile has an InputSchema, Assemble automatically:

• Applies default values to the context
• Validates required inputs are present
• Checks input types match the schema

If validation fails, Assemble returns an error. No separate validation call needed.

Input types: "flag" (bool), "string", "number" (int), "data" (any)

Configurable Directory Structure ¶

By default, LoadFromFS expects "components" and "profiles" directories. Customize these with options:

registry.LoadFromFS(fsys, rootPath,
    WithComponentsDir("snippets"),
    WithProfilesDir("configs"),
)

Storage Backends ¶

PromptLoom supports multiple storage backends:

• storage.NewMemoryStorage() - In-memory storage for testing
• storage.NewEmbedStorage(fs, path) - Embedded files (go:embed)

Thread Safety ¶

Registry and Assembler are safe for concurrent use. The Assembler caches resolved profiles for performance; use ClearCache() if you modify profiles after initial assembly.

package main

import (
	"fmt"

	"github.com/lirancohen/promptloom"
	"github.com/lirancohen/promptloom/storage"
)

func main() {
	// Create a memory storage for this example
	store := storage.NewMemoryStorage()
	store.AddComponent("greeting", `
name: greeting
instructions: Hello! I'm your AI assistant.
`)
	store.AddComponent("task", `
name: task
instructions: How can I help you today?
`)
	store.AddProfile("assistant", `
name: assistant
components:
  - greeting
  - task
`)

	// Load into registry
	registry := promptloom.NewRegistry()
	_ = registry.LoadFromFS(store.FS(), store.RootPath())

	// Assemble the prompt
	assembler := promptloom.NewAssembler(registry)
	ctx := promptloom.NewContext()
	prompt, _ := assembler.Assemble("assistant", ctx)

	fmt.Println(prompt)
}

Output:
Hello! I'm your AI assistant.

How can I help you today?