Skip to content

prompt-builder.md

Latest commit

 

History

History
144 lines (109 loc) · 5.96 KB

prompt-builder.md

File metadata and controls

144 lines (109 loc) · 5.96 KB
Raw

PromptBuilder Pattern

Since: 0.2.5

The PromptBuilder provides unified directive management for AI requests with priority-based ordering and agent-specific targeting. It replaces the previous scattered filter-based directive application with a structured builder pattern.

Overview

Prior to v0.2.5, AI directives were applied through separate datamachine_global_directives and datamachine_agent_directives filters, creating inconsistent ordering and maintenance overhead. The PromptBuilder centralizes this functionality into a single, priority-ordered system.

Architecture

┌─────────────────────────────────────────────────────┐
│              PromptBuilder Pattern                 │
│  (/inc/Engine/AI/PromptBuilder.php)                │
│                                                    │
│  ┌──────────────────┐      ┌──────────────────┐   │
│  │ Directive        │      │ Priority-Based   │   │
│  │ Registration     │      │ Ordering         │   │
│  │ (addDirective)   │      │ (usort by pri)   │   │
│  └──────────────────┘      └──────────────────┘   │
│                                                    │
│  ┌──────────────────┐      ┌──────────────────┐   │
│  │ Agent Type       │      │ Sequential       │   │
│  │ Targeting        │      │ Application      │   │
│  │ ('all', 'pipeline│      │ (build method)   │   │
│  │  'chat')         │      └──────────────────┘   │
│  └──────────────────┘                             │
└─────────────────────────────────────────────────────┘

Key Features

  • Priority-Based Ordering: Lower priority numbers applied first (10=core, 20=global, 30=pipeline, 40=context, 50=site)
  • Agent Targeting: Directives can target 'all' agents or specific types ('pipeline', 'chat')
  • Unified Registration: Single datamachine_directives filter replaces multiple filter types
  • Structured Builder Pattern: Fluent interface for directive configuration and request building

Usage

Basic Usage

use DataMachine\Engine\AI\PromptBuilder;

// Create builder instance
$builder = new PromptBuilder();

// Set initial messages and tools
$builder->setMessages($messages)
        ->setTools($tools);

// Add directives with priorities
$builder->addDirective(MyDirective::class, 20, ['all'])
        ->addDirective(PipelineDirective::class, 30, ['pipeline']);

// Build final request
$request = $builder->build('pipeline', 'openai', $payload);

Directive Registration

Directives are registered via the datamachine_directives filter:

add_filter('datamachine_directives', function($directives) {
    $directives[] = [
        'class' => MyDirective::class,
        'priority' => 20,
        'modes' => ['all']
    ];

    return $directives;
});

Priority Guidelines

Priority Order (lower = applied first):

  • 20: Registered memory files
  • 22: Runtime agent-mode guidance
  • 25-35: Caller, daily memory, and client-reported context
  • 40-50: Pipeline, flow, chat inventory, and workflow-specific directives

Current Directive Implementations

  • CoreMemoryFilesDirective - Registered memory files from shared, agent, and user layers (priority 20)
  • AgentModeDirective - Runtime mode guidance for chat, pipeline, system, and extension modes (priority 22)
  • CallerContextDirective - Authenticated cross-site caller identity (priority 25)
  • AgentDailyMemoryDirective and ClientContextDirective - Optional daily memory and client context (priority 35)
  • PipelineMemoryFilesDirective, FlowMemoryFilesDirective, and PipelineSystemPromptDirective - Pipeline-specific context (priorities 40, 45, 50)
  • ChatPipelinesDirective - Pipeline and flow inventory for chat (priority 45)

Integration with RequestBuilder

The PromptBuilder is integrated into the RequestBuilder for seamless directive application:

// In RequestBuilder.php
$promptBuilder = new PromptBuilder();
$promptBuilder->setMessages($messages)
              ->setTools($structured_tools);

// Apply directives via PromptBuilder
$request = $promptBuilder->build($agent_modes, $provider, $context);

Migration from Legacy System

Before (v0.2.4 and earlier)

// Separate filters with inconsistent ordering
add_filter('datamachine_global_directives', 'apply_global_directive', 10, 5); // LEGACY - use datamachine_directives instead
add_filter('datamachine_agent_directives', 'apply_agent_directive', 10, 5); // LEGACY - use datamachine_directives with modes to target 'pipeline'/'chat'

After (v0.2.5+)

// Unified registration with explicit priorities
add_filter('datamachine_directives', function($directives) {
    $directives[] = [
        'class' => MyDirective::class,
        'priority' => 25,
        'modes' => ['all']
    ];
    return $directives;
});

Benefits

  • Consistent Ordering: Priority-based system ensures predictable directive application
  • Agent Targeting: Fine-grained control over which directives apply to which agents
  • Maintainability: Single registration point reduces filter complexity
  • Extensibility: Easy to add new directives with proper ordering
  • Debugging: Clear priority logging helps troubleshoot directive conflicts

Related Components

  • RequestBuilder Pattern - Uses PromptBuilder for directive application
  • Universal Engine Architecture - Overall AI infrastructure
  • AI Conversation Loop - Multi-turn conversation execution