agentic-ai-framework 1.0.0

package/src/llm/providers/OpenAIProvider.js

@@ -0,0 +1,194 @@
+// OpenAI LLM Provider
+// Uses the OpenAI Chat Completions API (same format as Grok)
+
+import { BaseLLMProvider } from '../BaseLLMProvider.js';
+
+const OPENAI_API_BASE = 'https://api.openai.com/v1';
+const DEFAULT_MODEL = 'gpt-4o';
+const DEFAULT_TIMEOUT = 60000;
+
+export class OpenAIProvider extends BaseLLMProvider {
+    /**
+     * @param {string} apiKey  - OpenAI API key
+     * @param {string} [model] - Model to use
+     * @param {Object} [opts] - Additional options
+     * @param {string} [opts.baseUrl] - Override base URL (useful for Azure or local proxies)
+     * @param {number} [opts.timeout] - Request timeout in ms
+     */
+    constructor(apiKey, model = DEFAULT_MODEL, opts = {}) {
+        super();
+        if (!apiKey) throw new Error('OpenAIProvider: apiKey is required');
+        this.apiKey = apiKey;
+        this.model = model;
+        this.baseUrl = opts.baseUrl ?? OPENAI_API_BASE;
+        this.timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+    }
+
+    async _makeRequest(endpoint, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    errorMessage = errorJson.error?.message || errorBody;
+                } catch {
+                    errorMessage = errorBody;
+                }
+                throw new Error(`OpenAI API error (${response.status}): ${errorMessage}`);
+            }
+
+            return response.json();
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') throw new Error('OpenAI API request timed out');
+            throw error;
+        }
+    }
+
+    _buildMessages(prompt, options) {
+        if (options.messages && Array.isArray(options.messages)) return options.messages;
+        const messages = [];
+        if (options.systemPrompt) messages.push({ role: 'system', content: options.systemPrompt });
+        messages.push({ role: 'user', content: prompt });
+        return messages;
+    }
+
+    _formatTools(tools) {
+        if (!tools?.length) return [];
+        return tools.map(tool => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters || { type: 'object', properties: {} },
+            },
+        }));
+    }
+
+    async complete(prompt, options = {}) {
+        const messages = this._buildMessages(prompt, options);
+
+        const requestBody = {
+            model: options.model || this.model,
+            messages,
+            temperature: options.temperature ?? 0.1,
+            max_tokens: options.maxTokens ?? 4096,
+        };
+
+        if (options.enableTools && options.tools) {
+            requestBody.tools = this._formatTools(options.tools);
+            requestBody.tool_choice = 'auto';
+        }
+
+        if (options.jsonMode && !options.enableTools) {
+            requestBody.response_format = { type: 'json_object' };
+        }
+
+        const response = await this._makeRequest('/chat/completions', requestBody);
+        const choice = response.choices?.[0];
+        if (!choice) throw new Error('No completion returned from OpenAI API');
+
+        const content = choice.message?.content || '';
+        const rawToolCalls = choice.message?.tool_calls;
+        const hasToolCalls = !!(rawToolCalls?.length > 0);
+        const updatedMessages = [...messages];
+
+        let toolCalls;
+        if (hasToolCalls) {
+            toolCalls = rawToolCalls.map(tc => {
+                let args;
+                try {
+                    args = typeof tc.function.arguments === 'string'
+                        ? JSON.parse(tc.function.arguments)
+                        : tc.function.arguments ?? {};
+                } catch {
+                    args = {};
+                }
+                return { id: tc.id, name: tc.function.name, arguments: args };
+            });
+            updatedMessages.push({
+                role: 'assistant',
+                content: content || null,
+                tool_calls: rawToolCalls,
+            });
+        } else {
+            updatedMessages.push({ role: 'assistant', content });
+        }
+
+        let parsed = null;
+        if (options.jsonMode && content && !hasToolCalls) {
+            try {
+                parsed = JSON.parse(content);
+            } catch (error) {
+                throw new Error(`Failed to parse JSON response: ${error.message}`);
+            }
+        }
+
+        return {
+            content,
+            parsed,
+            usage: {
+                promptTokens: response.usage?.prompt_tokens || 0,
+                completionTokens: response.usage?.completion_tokens || 0,
+                totalTokens: response.usage?.total_tokens || 0,
+            },
+            model: response.model || this.model,
+            finishReason: choice.finish_reason || 'unknown',
+            toolCalls: toolCalls?.length ? toolCalls : undefined,
+            messages: updatedMessages,
+        };
+    }
+
+    async completeWithSchema(prompt, schema, options = {}) {
+        if (options.enableTools) {
+            const response = await this.complete(prompt, { ...options, jsonMode: false });
+            if (response.content && !response.toolCalls) {
+                try { response.parsed = JSON.parse(response.content); } catch {}
+            }
+            return response;
+        }
+
+        const schemaPrompt = `${prompt}\n\nYou MUST respond with a valid JSON object that matches this structure:\n${JSON.stringify(schema, null, 2)}\n\nRespond ONLY with the JSON object, no additional text.`;
+        const response = await this.complete(schemaPrompt, { ...options, jsonMode: true });
+
+        if (response.parsed && schema?.required) {
+            const missing = schema.required.filter(f => !(f in response.parsed));
+            if (missing.length > 0) {
+                throw new Error(`Response missing required fields: ${missing.join(', ')}`);
+            }
+        }
+
+        return response;
+    }
+
+    async testConnection() {
+        try {
+            const response = await this.complete("Say 'ok'", { maxTokens: 10, temperature: 0 });
+            return !!response.content;
+        } catch {
+            return false;
+        }
+    }
+
+    listModels() {
+        return ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-3.5-turbo'];
+    }
+}
+
+export default OpenAIProvider;

package/src/memory/FileStore.js

@@ -0,0 +1,102 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { MemoryError } from '../utils/errors.js';
+
+/**
+ * Persists session snapshots as JSON files on disk.
+ * One file per session: {dir}/{sessionId}.json
+ *
+ * This is the only shared resource between concurrent requests.
+ * Since each session has its own file, different sessions never conflict.
+ * Same-session concurrent writes are an application-level concern.
+ */
+export class FileStore {
+    /**
+     * @param {string} dir - Directory where session files are stored.
+     *   Created automatically if it doesn't exist.
+     */
+    constructor(dir) {
+        if (!dir) throw new Error('FileStore: dir is required');
+        this._dir = dir;
+    }
+
+    _filePath(sessionId) {
+        // Sanitize sessionId to prevent path traversal
+        const safe = path.basename(sessionId).replace(/[^a-zA-Z0-9_\-]/g, '_');
+        return path.join(this._dir, `${safe}.json`);
+    }
+
+    /**
+     * Load a session snapshot from disk.
+     * @param {string} sessionId
+     * @returns {Promise<Object | null>} Snapshot, or null if session does not exist
+     */
+    async load(sessionId) {
+        try {
+            const raw = await fs.readFile(this._filePath(sessionId), 'utf-8');
+            return JSON.parse(raw);
+        } catch (err) {
+            if (err.code === 'ENOENT') return null; // session doesn't exist yet
+            throw new MemoryError(`Failed to load session "${sessionId}"`, {
+                cause: err,
+                sessionId,
+            });
+        }
+    }
+
+    /**
+     * Save a session snapshot to disk.
+     * @param {string} sessionId
+     * @param {Object} snapshot
+     */
+    async save(sessionId, snapshot) {
+        const filePath = this._filePath(sessionId);
+        const tmpPath = `${filePath}.${Date.now()}.tmp`;
+        try {
+            await fs.mkdir(this._dir, { recursive: true });
+            // Write to temp file first, then atomically rename to prevent corruption
+            await fs.writeFile(tmpPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+            await fs.rename(tmpPath, filePath);
+        } catch (err) {
+            // Clean up temp file if rename failed
+            try { await fs.unlink(tmpPath); } catch { /* ignore */ }
+            throw new MemoryError(`Failed to save session "${sessionId}"`, {
+                cause: err,
+                sessionId,
+            });
+        }
+    }
+
+    /**
+     * Delete a session file from disk.
+     * @param {string} sessionId
+     */
+    async delete(sessionId) {
+        try {
+            await fs.unlink(this._filePath(sessionId));
+        } catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw new MemoryError(`Failed to delete session "${sessionId}"`, {
+                    cause: err,
+                    sessionId,
+                });
+            }
+        }
+    }
+
+    /**
+     * List all session IDs stored in the directory.
+     * @returns {Promise<string[]>}
+     */
+    async list() {
+        try {
+            const files = await fs.readdir(this._dir);
+            return files
+                .filter(f => f.endsWith('.json'))
+                .map(f => f.slice(0, -5)); // strip .json
+        } catch (err) {
+            if (err.code === 'ENOENT') return [];
+            throw new MemoryError('Failed to list sessions', { cause: err });
+        }
+    }
+}

package/src/memory/MemoryManager.js

@@ -0,0 +1,55 @@
+import { FileStore } from './FileStore.js';
+
+/**
+ * Facade over FileStore that provides load/save/delete operations
+ * on SessionMemory snapshots.
+ *
+ * Usage:
+ *   const manager = new MemoryManager({ dir: './sessions' });
+ *   const snapshot = await manager.load('session-123'); // null if new
+ *   await manager.save('session-123', memory.snapshot());
+ *   await manager.delete('session-123');
+ */
+export class MemoryManager {
+    /**
+     * @param {Object} options
+     * @param {string} options.dir - Directory for session JSON files
+     */
+    constructor({ dir }) {
+        this._store = new FileStore(dir);
+    }
+
+    /**
+     * Load a session snapshot. Returns null if the session doesn't exist yet.
+     * @param {string} sessionId
+     * @returns {Promise<{ history: Array, context: Object } | null>}
+     */
+    async load(sessionId) {
+        return this._store.load(sessionId);
+    }
+
+    /**
+     * Persist a session snapshot.
+     * @param {string} sessionId
+     * @param {{ history: Array, context: Object }} snapshot
+     */
+    async save(sessionId, snapshot) {
+        return this._store.save(sessionId, snapshot);
+    }
+
+    /**
+     * Delete a session file from disk.
+     * @param {string} sessionId
+     */
+    async delete(sessionId) {
+        return this._store.delete(sessionId);
+    }
+
+    /**
+     * List all persisted session IDs.
+     * @returns {Promise<string[]>}
+     */
+    async list() {
+        return this._store.list();
+    }
+}

package/src/memory/SessionMemory.js

@@ -0,0 +1,124 @@
+/**
+ * In-memory storage for a single agent session.
+ *
+ * Holds two things:
+ *   - history: conversation messages [{role, content}] inserted between system
+ *     prompt and new user message on each agent.run() call.
+ *   - context: key-value working state that is injected into the system prompt
+ *     template as ${key} variables.
+ *
+ * Cross-session persistence is handled externally by MemoryManager.
+ */
+export class SessionMemory {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.maxMessages=50] - Max conversation messages to keep.
+     *   Always trims in pairs (user + assistant) to maintain conversation alignment.
+     */
+    constructor({ maxMessages = 50 } = {}) {
+        this._history = [];   // Array<{ role: 'user' | 'assistant', content: string }>
+        this._context = {};   // Record<string, any>
+        this._maxMessages = maxMessages;
+    }
+
+    // ── History ───────────────────────────────────────────────────────────────
+
+    /**
+     * Append a completed exchange to history.
+     * @param {string} userInput
+     * @param {string} assistantOutput
+     */
+    appendExchange(userInput, assistantOutput) {
+        this._history.push({ role: 'user', content: userInput });
+        this._history.push({ role: 'assistant', content: assistantOutput });
+
+        // Trim oldest pairs to stay within limit
+        while (this._history.length > this._maxMessages) {
+            this._history.splice(0, 2);
+        }
+    }
+
+    /**
+     * Get a copy of the conversation history.
+     * @returns {Array<{ role: string, content: string }>}
+     */
+    getHistory() {
+        return [...this._history];
+    }
+
+    /**
+     * Number of messages currently in history.
+     * @returns {number}
+     */
+    get historyLength() {
+        return this._history.length;
+    }
+
+    // ── Working context ───────────────────────────────────────────────────────
+
+    /**
+     * Store a named value in the working context.
+     * These values are injected into the system prompt as ${key} variables.
+     * @param {string} key
+     * @param {*} value
+     */
+    setContext(key, value) {
+        // Reject non-serializable types (functions, symbols, etc.)
+        const type = typeof value;
+        if (type === 'function' || type === 'symbol' || type === 'undefined') {
+            throw new Error(`SessionMemory.setContext: value for "${key}" must be JSON-serializable (got ${type})`);
+        }
+        this._context[key] = value;
+    }
+
+    /**
+     * Retrieve a context value by key.
+     * @param {string} key
+     * @returns {*}
+     */
+    getContext(key) {
+        return this._context[key];
+    }
+
+    /**
+     * Get a shallow copy of the entire context object.
+     * @returns {Record<string, any>}
+     */
+    getContextSnapshot() {
+        return { ...this._context };
+    }
+
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    /**
+     * Clear all history and context (reset to empty state).
+     */
+    clear() {
+        this._history = [];
+        this._context = {};
+    }
+
+    /**
+     * Serialize the full session state for persistence.
+     * @returns {{ history: Array, context: Record<string, any> }}
+     */
+    snapshot() {
+        return {
+            version: 1,
+            history: [...this._history],
+            context: { ...this._context },
+            savedAt: new Date().toISOString(),
+        };
+    }
+
+    /**
+     * Restore session state from a snapshot (e.g., loaded from disk).
+     * @param {{ history?: Array, context?: Record<string, any> }} snapshot
+     */
+    restore(snapshot) {
+        this._history = Array.isArray(snapshot?.history) ? [...snapshot.history] : [];
+        this._context = (snapshot?.context && typeof snapshot.context === 'object')
+            ? { ...snapshot.context }
+            : {};
+    }
+}

package/src/prompt/PromptBuilder.js

@@ -0,0 +1,95 @@
+import { PromptTemplate } from './PromptTemplate.js';
+
+// ── Built-in CoT blocks ──────────────────────────────────────────────────────
+
+const COT_BLOCKS = {
+    'step-by-step': `
+
+### Reasoning Approach
+Before producing your final answer, reason step by step through the problem:
+1. Identify what is being asked.
+2. Determine what information or tool results you need.
+3. Plan your approach.
+4. Execute and verify your reasoning before responding.
+`,
+    'pros-cons': `
+
+### Reasoning Approach
+Before answering, briefly consider:
+- What approaches are available?
+- What are the trade-offs of each?
+- Which approach best fits the question?
+Then proceed with the best approach.
+`,
+};
+
+/**
+ * Assembles the system prompt by rendering a PromptTemplate and optionally
+ * appending a Chain-of-Thought block.
+ *
+ * CoT modes:
+ *   - 'prompt' (default): CoT block appended to the rendered system prompt.
+ *     Zero extra LLM calls. Controlled by cotStyle.
+ *   - 'reflect': No CoT appended here; AgentRunner makes a second LLM call
+ *     after the tool-calling loop to verify the answer. PromptBuilder is not
+ *     involved in that step.
+ */
+export class PromptBuilder {
+    /**
+     * @param {Object} options
+     * @param {string} [options.systemPromptTemplate]   - Inline template string
+     * @param {string} [options.systemPromptFile]       - Path to template file
+     * @param {boolean} [options.cotEnabled=true]       - Whether to inject CoT
+     * @param {string}  [options.cotMode='prompt']      - 'prompt' | 'reflect'
+     * @param {string}  [options.cotStyle='step-by-step'] - 'step-by-step' | 'pros-cons' | 'custom'
+     * @param {string}  [options.cotCustomInstructions] - Custom CoT text (when cotStyle='custom')
+     */
+    constructor({
+        systemPromptTemplate,
+        systemPromptFile,
+        cotEnabled = true,
+        cotMode = 'prompt',
+        cotStyle = 'step-by-step',
+        cotCustomInstructions = null,
+    } = {}) {
+        this._template = new PromptTemplate({
+            inline: systemPromptTemplate,
+            file: systemPromptFile,
+        });
+
+        this._cotEnabled = cotEnabled;
+        this._cotMode = cotMode;
+
+        // Only 'prompt' mode appends the block here
+        if (cotEnabled && cotMode === 'prompt') {
+            if (cotCustomInstructions) {
+                this._cotBlock = `\n\n### Reasoning Approach\n${cotCustomInstructions}\n`;
+            } else {
+                this._cotBlock = COT_BLOCKS[cotStyle] ?? COT_BLOCKS['step-by-step'];
+            }
+        } else {
+            this._cotBlock = '';
+        }
+    }
+
+    /**
+     * Whether this builder is configured for reflect-mode CoT.
+     * AgentRunner checks this to know whether to run the reflection call.
+     * @returns {boolean}
+     */
+    get isReflectMode() {
+        return this._cotEnabled && this._cotMode === 'reflect';
+    }
+
+    /**
+     * Build and return the final system prompt string.
+     *
+     * @param {Object} [opts]
+     * @param {Record<string, string | number | boolean>} [opts.vars={}]  - Template variables
+     * @returns {Promise<string>}
+     */
+    async build({ vars = {} } = {}) {
+        const rendered = await this._template.render(vars);
+        return rendered + this._cotBlock;
+    }
+}

package/src/prompt/PromptTemplate.js

@@ -0,0 +1,58 @@
+import fs from 'fs/promises';
+
+/**
+ * Loads a prompt template from an inline string or a file on disk.
+ * Supports ${variable} interpolation.
+ *
+ * Template variables that are not present in vars are left as-is.
+ */
+export class PromptTemplate {
+    /**
+     * @param {Object} options
+     * @param {string} [options.inline]  - Inline template string
+     * @param {string} [options.file]    - Absolute path to a .md or .txt template file
+     */
+    constructor({ inline, file } = {}) {
+        if (!inline && !file) {
+            throw new Error('PromptTemplate: provide either inline or file');
+        }
+        this._inline = inline ?? null;
+        this._file = file ?? null;
+        this._cache = null; // raw template string, cached after first load
+    }
+
+    /**
+     * Load and cache the raw template string.
+     * @returns {Promise<string>}
+     */
+    async _load() {
+        if (this._cache !== null) return this._cache;
+        if (this._inline) {
+            this._cache = this._inline;
+            return this._cache;
+        }
+        this._cache = await fs.readFile(this._file, 'utf-8');
+        return this._cache;
+    }
+
+    /**
+     * Invalidate the cache (useful if the file changes on disk).
+     */
+    invalidateCache() {
+        this._cache = null;
+    }
+
+    /**
+     * Render the template by replacing ${key} placeholders with values from vars.
+     * Unknown placeholders are left intact.
+     *
+     * @param {Record<string, string | number | boolean>} [vars={}]
+     * @returns {Promise<string>}
+     */
+    async render(vars = {}) {
+        const raw = await this._load();
+        return raw.replace(/\$\{([\w.\-]+)\}/g, (match, key) => {
+            return key in vars ? String(vars[key]) : match;
+        });
+    }
+}