@framers/agentos 0.1.0

package/dist/core/llm/IPromptEngine.js

@@ -0,0 +1,81 @@
+// File: backend/agentos/core/llm/IPromptEngine.ts
+/**
+ * @fileoverview Defines the IPromptEngine interface and related types that form the core
+ * of AgentOS's adaptive and contextual prompting system. The PromptEngine is responsible
+ * for dynamically constructing prompts based on rich contextual information, persona
+ * definitions, and runtime state. It supports contextual element selection, token budgeting,
+ * content summarization, and multiple prompt template formats.
+ *
+ * This interface is central to the GMI (Generalized Mind Instance) architecture, enabling
+ * sophisticated prompt adaptation based on user skill level, mood, task complexity,
+ * conversation state, and persona-specific rules.
+ *
+ * Key responsibilities include:
+ * - Dynamic contextual element selection based on PromptExecutionContext.
+ * - Intelligent token budgeting and content truncation/summarization using an IUtilityAI helper.
+ * - Multi-modal prompt component integration (text, vision, audio data references, tools).
+ * - Template-based prompt formatting for different LLM providers and models.
+ * - Comprehensive error handling and issue reporting within the PromptEngineResult.
+ * - Performance optimization strategies such as caching.
+ *
+ * @module backend/agentos/core/llm/IPromptEngine
+ * @see {@link ../../../docs/PROMPTS.MD} for detailed architectural documentation.
+ * @see {@link ../../cognitive_substrate/personas/IPersonaDefinition.ts} for persona-driven prompting.
+ */
+/**
+ * Represents different types of contextual prompt elements that can be dynamically
+ * selected and integrated into prompts based on execution context.
+ * These elements allow for fine-grained adaptation of prompts.
+ * @enum {string}
+ */
+export var ContextualElementType;
+(function (ContextualElementType) {
+    /** Additional system-level instructions appended to base system prompt. */
+    ContextualElementType["SYSTEM_INSTRUCTION_ADDON"] = "system_instruction_addon";
+    /** Dynamic few-shot examples selected based on context to guide the LLM. */
+    ContextualElementType["FEW_SHOT_EXAMPLE"] = "few_shot_example";
+    /** Behavioral guidance or tone adjustments for the persona. */
+    ContextualElementType["BEHAVIORAL_GUIDANCE"] = "behavioral_guidance";
+    /** Specific instructions or constraints related to the current task. */
+    ContextualElementType["TASK_SPECIFIC_INSTRUCTION"] = "task_specific_instruction";
+    /** Instructions for handling errors or recovering from unexpected situations. */
+    ContextualElementType["ERROR_HANDLING_GUIDANCE"] = "error_handling_guidance";
+    /** Adjustments to the GMI's interaction style with the user. */
+    ContextualElementType["INTERACTION_STYLE_MODIFIER"] = "interaction_style_modifier";
+    /** Domain-specific knowledge, facts, or context relevant to the current query. */
+    ContextualElementType["DOMAIN_CONTEXT"] = "domain_context";
+    /** Ethical guidelines or safety instructions to ensure responsible AI behavior. */
+    ContextualElementType["ETHICAL_GUIDELINE"] = "ethical_guideline";
+    /** Specifications for the desired output format (e.g., JSON, Markdown). */
+    ContextualElementType["OUTPUT_FORMAT_SPEC"] = "output_format_spec";
+    /** Instructions for specific reasoning protocols (e.g., chain-of-thought, tree-of-thought). */
+    ContextualElementType["REASONING_PROTOCOL"] = "reasoning_protocol";
+    /** Dynamic content to be injected directly into the user part of the prompt. */
+    ContextualElementType["USER_PROMPT_AUGMENTATION"] = "user_prompt_augmentation";
+    /** Content to be injected into the assistant part for few-shot or role-play setup. */
+    ContextualElementType["ASSISTANT_PROMPT_AUGMENTATION"] = "assistant_prompt_augmentation";
+})(ContextualElementType || (ContextualElementType = {}));
+/**
+ * Custom error class for all errors originating from the PromptEngine.
+ * This allows for specific catching and handling of prompt construction failures.
+ * @class PromptEngineError
+ * @extends {Error}
+ */
+export class PromptEngineError extends Error {
+    /**
+     * Creates an instance of PromptEngineError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A specific error code (e.g., 'TEMPLATE_NOT_FOUND').
+     * @param {string} [component] - The engine component where the error originated.
+     * @param {unknown} [details] - Additional context or the underlying error.
+     */
+    constructor(message, code, component, details) {
+        super(message);
+        this.name = 'PromptEngineError';
+        this.code = code;
+        this.component = component;
+        this.details = details;
+        Object.setPrototypeOf(this, PromptEngineError.prototype); // Ensure instanceof works correctly
+    }
+}
+//# sourceMappingURL=IPromptEngine.js.map

package/dist/core/llm/IPromptEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IPromptEngine.js","sourceRoot":"","sources":["../../../src/core/llm/IPromptEngine.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH;;;;;GAKG;AACH,MAAM,CAAN,IAAY,qBAyBX;AAzBD,WAAY,qBAAqB;IAC/B,2EAA2E;IAC3E,8EAAqD,CAAA;IACrD,4EAA4E;IAC5E,8DAAqC,CAAA;IACrC,+DAA+D;IAC/D,oEAA2C,CAAA;IAC3C,wEAAwE;IACxE,gFAAuD,CAAA;IACvD,iFAAiF;IACjF,4EAAmD,CAAA;IACnD,gEAAgE;IAChE,kFAAyD,CAAA;IACzD,kFAAkF;IAClF,0DAAiC,CAAA;IACjC,mFAAmF;IACnF,gEAAuC,CAAA;IACvC,2EAA2E;IAC3E,kEAAyC,CAAA;IACzC,+FAA+F;IAC/F,kEAAyC,CAAA;IACzC,gFAAgF;IAChF,8EAAqD,CAAA;IACrD,sFAAsF;IACtF,wFAA+D,CAAA;AACjE,CAAC,EAzBW,qBAAqB,KAArB,qBAAqB,QAyBhC;AA0hBD;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IA2B1C;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,SAAkB,EAAE,OAAiB;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC,oCAAoC;IAChG,CAAC;CACF"}

package/dist/core/llm/PromptEngine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Implements the sophisticated PromptEngine that serves as the core of
+ * AgentOS's adaptive and contextual prompting system. This implementation provides
+ * intelligent prompt construction with dynamic contextual element selection,
+ * token budgeting, multi-modal content integration, and optimization strategies.
+ *
+ * The PromptEngine orchestrates the entire prompt construction pipeline:
+ * 1. Context Analysis: Evaluates execution context against persona-defined criteria.
+ * 2. Element Selection: Dynamically selects applicable contextual prompt elements.
+ * 3. Content Augmentation: Integrates selected elements with base prompt components.
+ * 4. Token Management: Applies intelligent budgeting and content optimization.
+ * 5. Template Formatting: Renders final prompts using model-specific templates.
+ * 6. Quality Assurance: Validates output and reports issues/optimizations.
+ *
+ * @module backend/agentos/core/llm/PromptEngine
+ * @implements {IPromptEngine}
+ */
+import { IPromptEngine, PromptEngineConfig, PromptComponents, ModelTargetInfo, PromptExecutionContext, PromptEngineResult, PromptTemplateFunction, IPromptEngineUtilityAI } from './IPromptEngine';
+import { ContextualPromptElementCriteria } from '../../cognitive_substrate/personas/IPersonaDefinition';
+/**
+ * Comprehensive implementation of the IPromptEngine interface, providing
+ * sophisticated adaptive prompting capabilities for AgentOS GMIs.
+ *
+ * @class PromptEngine
+ * @implements {IPromptEngine}
+ */
+export declare class PromptEngine implements IPromptEngine {
+    private config;
+    private utilityAI?;
+    private isInitialized;
+    /**
+     * Current execution context used implicitly for operations (e.g., tool manifest filtering) when
+     * a context is not passed directly. This is set via `setCurrentExecutionContext` by orchestration layers.
+     * Avoids leaking context through multiple method signatures while still enabling persona-scoped behavior.
+     */
+    private currentExecutionContext?;
+    private cache;
+    private statistics;
+    private readonly defaultTemplates;
+    constructor();
+    initialize(config: PromptEngineConfig, utilityAI?: IPromptEngineUtilityAI): Promise<void>;
+    /**
+     * Sets the current execution context for implicit persona-aware operations (e.g., tool filtering).
+     * Passing undefined clears the context.
+     */
+    setCurrentExecutionContext(ctx?: Readonly<PromptExecutionContext>): void;
+    private ensureInitialized;
+    private getInitialStatistics;
+    constructPrompt(baseComponents: Readonly<PromptComponents>, modelTargetInfo: Readonly<ModelTargetInfo>, executionContext?: Readonly<PromptExecutionContext>, templateName?: string): Promise<PromptEngineResult>;
+    evaluateCriteria(criteria: Readonly<ContextualPromptElementCriteria>, context: Readonly<PromptExecutionContext>): Promise<boolean>;
+    estimateTokenCount(content: string, modelId?: string): Promise<number>;
+    registerTemplate(templateName: string, templateFunction: PromptTemplateFunction): Promise<void>;
+    validatePromptConfiguration(components: Readonly<PromptComponents>, modelTargetInfo: Readonly<ModelTargetInfo>, executionContext?: Readonly<PromptExecutionContext>): Promise<{
+        isValid: boolean;
+        issues: Array<{
+            type: 'error' | 'warning';
+            code: string;
+            message: string;
+            suggestion?: string;
+            component?: string;
+        }>;
+        recommendations?: string[];
+    }>;
+    clearCache(selectivePattern?: string): 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;
+        }>;
+    }>;
+    private validateEngineConfiguration;
+    private generateCacheKey;
+    private setupCacheEviction;
+    private startPerformanceTimer;
+    private recordPerformanceTimer;
+    private augmentBaseComponents;
+    private applyTokenBudget;
+    private calculateTotalTokens;
+    private calculateTokensForMessages;
+    private truncateMessages;
+    private formatToolSchemasForModel;
+    private buildToolDefinition;
+    private serializeToolArguments;
+    private normalizeToolCalls;
+    private createOpenAIChatTemplate;
+    private createAnthropicMessagesTemplate;
+    private createGenericCompletionTemplate;
+}
+//# sourceMappingURL=PromptEngine.d.ts.map

package/dist/core/llm/PromptEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromptEngine.d.ts","sourceRoot":"","sources":["../../../src/core/llm/PromptEngine.ts"],"names":[],"mappings":"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"}