Interface IPromptEngine

Core interface for the PromptEngine, responsible for intelligent and adaptive prompt construction based on rich contextual information and persona definitions.

The PromptEngine serves as the central orchestrator for AgentOS's sophisticated prompting system, capable of dynamically selecting contextual elements, managing token budgets, integrating multi-modal content, and optimizing prompts for different AI models and interaction patterns.

IPromptEngine

interface IPromptEngine {
    initialize(config, utilityAI?): Promise<void>;
    constructPrompt(baseComponents, modelTargetInfo, executionContext?, templateName?): Promise<PromptEngineResult>;
    evaluateCriteria(criteria, context): Promise<boolean>;
    estimateTokenCount(content, modelId?): Promise<number>;
    registerTemplate(templateName, templateFunction): Promise<void>;
    validatePromptConfiguration(components, modelTargetInfo, executionContext?): Promise<{
        isValid: boolean;
        issues: {
            type: "error" | "warning";
            code: string;
            message: string;
            suggestion?: string;
            component?: string;
        }[];
        recommendations?: string[];
    }>;
    clearCache(selectivePattern?): Promise<void>;
    getEngineStatistics(): Promise<{
        totalPromptsConstructed: number;
        averageConstructionTimeMs: number;
        cacheStats: {
            hits: number;
            misses: number;
            currentSize: number;
            maxSize?: number;
            effectivenessRatio: number;
        };
        tokenCountingStats: {
            operations: number;
            averageAccuracy?: number;
        };
        contextualElementUsage: Record<string, {
            count: number;
            averageEvaluationTimeMs?: number;
        }>;
        errorRatePerType: Record<string, number>;
        performanceTimers: Record<string, {
            count: number;
            totalTimeMs: number;
            averageTimeMs: number;
        }>;
    }>;
}

Methods

initialize constructPrompt evaluateCriteria estimateTokenCount registerTemplate validatePromptConfiguration clearCache getEngineStatistics

Methods

initialize

  • initialize(config, utilityAI?): Promise<void>

  • Initializes the PromptEngine with its configuration and an optional utility AI service. This method must be called successfully before any prompt construction.

    Parameters

    • config: PromptEngineConfig

      The comprehensive configuration for the engine, including template definitions, token counting strategies, history management rules, contextual element selection parameters, performance settings, and debugging options.

    • Optional utilityAI: IPromptEngineUtilityAI

      An optional utility AI service instance, conforming to IPromptEngineUtilityAI, used for advanced content processing tasks like summarization of conversation history or RAG context within the prompt construction pipeline.

    Returns Promise<void>

    A promise that resolves when the engine is fully initialized and ready.

    Async

    Throws

    If the provided configuration is invalid or if a critical initialization step fails (e.g., loading default templates).

    Example

    const engine = new PromptEngine();
    await engine.initialize(myAppConfig.promptEngine, myUtilityAIService);

constructPrompt

  • constructPrompt(baseComponents, modelTargetInfo, executionContext?, templateName?): Promise<PromptEngineResult>

  • The primary method for constructing an adaptive and contextually relevant prompt. This orchestrates the entire pipeline: contextual element evaluation and selection, augmentation of base components, token budget management (including truncation and summarization), and final formatting using a model-appropriate template.

    Parameters

    • baseComponents: Readonly<PromptComponents>

      The core, static components of the prompt, such as system instructions, conversation history, and current user input. These are read-only to prevent unintended modification by the method.

    • modelTargetInfo: Readonly<ModelTargetInfo>

      Detailed information about the target AI model, including its ID, provider, capabilities, token limits, and expected prompt format. This is crucial for tailoring the prompt effectively.

    • Optional executionContext: Readonly<PromptExecutionContext>

      Optional. The rich runtime context, including active persona, working memory, user state, and task details. This drives the dynamic selection and application of contextual prompt elements.

    • Optional templateName: string

      Optional. The explicit name of a prompt template to use. If not provided, the engine selects a default template based on modelTargetInfo.promptFormatType or the defaultTemplateName from its configuration.

    Returns Promise<PromptEngineResult>

    A promise resolving to a PromptEngineResult object, which contains the final formatted prompt, along with metadata about its construction, token counts, any issues encountered, and modifications made.

    Async

    Throws

    If a non-recoverable error occurs during any stage of prompt construction (e.g., template not found, critical component missing, tokenization failure).

evaluateCriteria

  • evaluateCriteria(criteria, context): Promise<boolean>

  • Evaluates whether a given set of ContextualPromptElementCriteria is satisfied by the current PromptExecutionContext. This method is the core of the dynamic adaptation logic, determining which contextual elements are relevant and should be incorporated into the prompt. It supports checking various context aspects like mood, user skill, task hints, working memory values, etc.

    Parameters

    • criteria: Readonly<ContextualPromptElementCriteria>

      The criteria defined within a ContextualPromptElement from the persona definition. These criteria specify the conditions under which the element applies.

    • context: Readonly<PromptExecutionContext>

      The current execution context against which the criteria are evaluated.

    Returns Promise<boolean>

    A promise resolving to true if all conditions within the criteria are met (respecting logical operators like AND/OR if defined in criteria), false otherwise.

    Async

    Throws

    If criteria evaluation encounters an unexpected error (e.g., accessing a non-existent working memory key specified in a query).

estimateTokenCount

  • estimateTokenCount(content, modelId?): Promise<number>

  • Estimates the token count for a given piece of text, optionally using a specific model ID to inform a more precise estimation if available (e.g., using a model-specific tokenizer). This is used internally for token budgeting and can also be exposed as a utility.

    Parameters

    • content: string

      The text content for which to estimate token count.

    • Optional modelId: string

      Optional. The ID of the target model. If provided, the engine may attempt a more precise tokenization based on this model's characteristics.

    Returns Promise<number>

    A promise resolving to the estimated number of tokens.

    Async

registerTemplate

  • registerTemplate(templateName, templateFunction): Promise<void>

  • Registers a new prompt template function with the engine. This allows for extending the engine's capabilities to support new LLM providers, model families, or specialized prompt formatting requirements dynamically at runtime.

    Parameters

    • templateName: string

      A unique name to identify the template. If a template with this name already exists, it will be overwritten (a warning may be logged).

    • templateFunction: PromptTemplateFunction

      The function that implements the template logic. It receives PromptComponents, ModelTargetInfo, selected ContextualPromptElement[], engine config, and a tokenEstimatorFn, and must return a FormattedPrompt.

    Returns Promise<void>

    A promise that resolves when the template is successfully registered.

    Async

    Throws

    If the templateName is invalid or templateFunction is not a function.

validatePromptConfiguration

  • validatePromptConfiguration(components, modelTargetInfo, executionContext?): Promise<{
        isValid: boolean;
        issues: {
            type: "error" | "warning";
            code: string;
            message: string;
            suggestion?: string;
            component?: string;
        }[];
        recommendations?: string[];
    }>

  • Validates a given set of prompt components and model information against the engine's understanding of best practices and potential issues. Useful for development, debugging persona definitions, or providing feedback to users designing prompts.

    Parameters

    • components: Readonly<PromptComponents>

      The prompt components to validate.

    • modelTargetInfo: Readonly<ModelTargetInfo>

      Information about the target model.

    • Optional executionContext: Readonly<PromptExecutionContext>

      Optional. The context in which these components would be used, allowing for context-aware validation.

    Returns Promise<{
        isValid: boolean;
        issues: {
            type: "error" | "warning";
            code: string;
            message: string;
            suggestion?: string;
            component?: string;
        }[];
        recommendations?: string[];
    }>

    An object containing a boolean isValid (true if no errors), a list of issues found (errors or warnings with messages and suggestions), and a list of recommendations for improvement.

    Async

clearCache

  • clearCache(selectivePattern?): Promise<void>

  • Clears internal caches used by the PromptEngine (e.g., for prompt construction results or token counts). This can be used to free memory or to force re-computation for debugging or after configuration changes.

    Parameters

    • Optional selectivePattern: string

      Optional. A pattern or key to clear only specific cache entries (e.g., "modelId:gpt-4o*"). If omitted, the entire cache is cleared. The exact format of the pattern is implementation-dependent.

    Returns Promise<void>

    A promise that resolves when the cache clearing operation is complete.

    Async

getEngineStatistics

  • getEngineStatistics(): Promise<{
        totalPromptsConstructed: number;
        averageConstructionTimeMs: number;
        cacheStats: {
            hits: number;
            misses: number;
            currentSize: number;
            maxSize?: number;
            effectivenessRatio: number;
        };
        tokenCountingStats: {
            operations: number;
            averageAccuracy?: number;
        };
        contextualElementUsage: Record<string, {
            count: number;
            averageEvaluationTimeMs?: number;
        }>;
        errorRatePerType: Record<string, number>;
        performanceTimers: Record<string, {
            count: number;
            totalTimeMs: number;
            averageTimeMs: number;
        }>;
    }>

  • Retrieves current performance and usage statistics from the PromptEngine. This data can be used for monitoring, optimization, and understanding engine behavior.

    Returns Promise<{
        totalPromptsConstructed: number;
        averageConstructionTimeMs: number;
        cacheStats: {
            hits: number;
            misses: number;
            currentSize: number;
            maxSize?: number;
            effectivenessRatio: number;
        };
        tokenCountingStats: {
            operations: number;
            averageAccuracy?: number;
        };
        contextualElementUsage: Record<string, {
            count: number;
            averageEvaluationTimeMs?: number;
        }>;
        errorRatePerType: Record<string, number>;
        performanceTimers: Record<string, {
            count: number;
            totalTimeMs: number;
            averageTimeMs: number;
        }>;
    }>

    A promise resolving to an object containing various statistics like total prompts constructed, average construction time, cache hit rate, error rates, and usage of contextual elements.

    Async

Settings

Member Visibility

Theme

On This Page

initializeconstructPromptevaluateCriteriaestimateTokenCountregisterTemplatevalidatePromptConfigurationclearCachegetEngineStatistics