@agentionai/agents 0.3.0-beta

package/dist/agents/openai/OpenAiAgent.js

@@ -0,0 +1,338 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAiAgent = void 0;
+const openai_1 = __importDefault(require("openai"));
+const BaseAgent_1 = require("../BaseAgent");
+const AgentEvent_1 = require("../AgentEvent");
+const AgentError_1 = require("../errors/AgentError");
+const transformers_1 = require("../../history/transformers");
+const VizReporter_1 = require("../../viz/VizReporter");
+const VizConfig_1 = require("../../viz/VizConfig");
+/**
+ * Agent for OpenAI models using the Responses API.
+ *
+ * @example
+ * ```typescript
+ * const agent = new OpenAiAgent({
+ *   id: "1",
+ *   name: "Assistant",
+ *   description: "A helpful assistant",
+ *   apiKey: process.env.OPENAI_API_KEY,
+ * });
+ *
+ * const response = await agent.execute("Hello!");
+ * ```
+ */
+class OpenAiAgent extends BaseAgent_1.BaseAgent {
+    constructor(config, history) {
+        super({ ...config, vendor: "openai" }, history);
+        /** Count of tool calls in current execution */
+        this.currentToolCallCount = 0;
+        this.client = new openai_1.default({
+            apiKey: config.apiKey,
+        });
+        // Merge flat config (deprecated) with nested vendorConfig
+        // Flat config takes precedence for backward compatibility
+        const vendorConfig = config.vendorConfig?.openai || {};
+        const disableParallelToolUse = config.disableParallelToolUse ??
+            vendorConfig.disableParallelToolUse ??
+            false;
+        const disableReasoning = config.disableReasoning ?? vendorConfig.disableReasoning ?? false;
+        const reasoningEffort = config.reasoningEffort ?? vendorConfig.reasoningEffort;
+        const user = config.user ?? vendorConfig.user;
+        this.config = {
+            model: config.model || "gpt-4.1-mini",
+            maxTokens: config.maxTokens || 1024,
+            disableParallelToolUse,
+            disableReasoning,
+            reasoningEffort,
+            user,
+            apiKey: config.apiKey,
+            temperature: config.temperature,
+            topP: config.topP,
+            seed: config.seed,
+            presencePenalty: config.presencePenalty,
+            frequencyPenalty: config.frequencyPenalty,
+            stopSequences: config.stopSequences,
+        };
+        // Add system message to history (skips if already exists with same content)
+        this.addSystemMessage(this.getSystemMessage());
+    }
+    getToolDefinitions() {
+        return Array.from(this.tools.values()).map((tool) => {
+            const prompt = tool.getPrompt();
+            return {
+                type: "function",
+                name: prompt.name,
+                description: prompt.description,
+                parameters: {
+                    type: prompt.input_schema.type,
+                    properties: prompt.input_schema.properties,
+                    required: prompt.input_schema.required,
+                    additionalProperties: false,
+                },
+                strict: true,
+            };
+        });
+    }
+    async process(_input) {
+        return "";
+    }
+    async execute(input) {
+        this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
+        // Reset token usage for this execution
+        this.lastTokenUsage = undefined;
+        this.currentToolCallCount = 0;
+        // Start visualization reporting
+        if (VizConfig_1.vizConfig.isEnabled()) {
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "openai", input);
+        }
+        if (this.history.transient) {
+            this.history.clear();
+            // Re-add system message after clear
+            this.addSystemMessage(this.getSystemMessage());
+        }
+        this.addTextToHistory("user", input);
+        try {
+            const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
+            const response = await this.client.responses.create({
+                model: this.config.model,
+                max_output_tokens: this.config.maxTokens,
+                input: inputMessages,
+                tools: this.getToolDefinitions(),
+                store: false,
+                temperature: this.config.temperature,
+                top_p: this.config.topP,
+                // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
+                user: this.config.user,
+                ...(this.config.disableReasoning && { reasoning: { effort: null } }),
+                reasoning: { effort: this.config.reasoningEffort },
+            });
+            this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
+            return await this.handleResponse(response);
+        }
+        catch (error) {
+            if (error && typeof error === "object" && "error" in error) {
+                const openAIError = error;
+                const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
+                if (openAIError.error.code === "insufficient_quota") {
+                    apiError.message =
+                        "OpenAI API quota exceeded. Please check your billing details.";
+                }
+                this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
+                // Report error to viz
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.error.code === "rate_limit_exceeded");
+                    this.vizEventId = undefined;
+                }
+                throw apiError;
+            }
+            else {
+                const executionError = new AgentError_1.ExecutionError(`Error executing agent: ${error instanceof Error ? error.message : "Unknown error"}`);
+                this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
+                // Report error to viz
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", executionError.message, false);
+                    this.vizEventId = undefined;
+                }
+                throw executionError;
+            }
+        }
+    }
+    async handleResponse(response) {
+        if (!response.output || !response.output.length) {
+            const error = new AgentError_1.ExecutionError("Invalid response format: missing output");
+            this.emit(AgentEvent_1.AgentEvent.ERROR, error);
+            throw error;
+        }
+        // Track token usage if available
+        if (response.usage) {
+            const usage = this.parseUsage(response.usage);
+            if (this.lastTokenUsage) {
+                this.lastTokenUsage.input_tokens += usage.input_tokens;
+                this.lastTokenUsage.output_tokens += usage.output_tokens;
+                this.lastTokenUsage.total_tokens += usage.total_tokens;
+            }
+            else {
+                this.lastTokenUsage = { ...usage };
+            }
+        }
+        const toolCalls = response.output.filter((output) => output.type === "function_call");
+        // Find the message output (skip reasoning outputs)
+        const messageOutput = response.output.find((output) => output.type === "message");
+        // Handle incomplete responses (e.g., reasoning hit token limit)
+        if (!toolCalls.length &&
+            messageOutput &&
+            messageOutput.type === "message" &&
+            messageOutput.status === "incomplete") {
+            const error = new AgentError_1.ExecutionError(`Response incomplete: ${response.incomplete_details?.reason || "unknown reason"}. ` +
+                `Try increasing maxTokens or setting disableReasoning: true for this agent.`);
+            this.emit(AgentEvent_1.AgentEvent.ERROR, error);
+            // Report error to viz
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", error.message, false);
+                this.vizEventId = undefined;
+            }
+            throw error;
+        }
+        if (!toolCalls.length &&
+            messageOutput &&
+            messageOutput.type === "message" &&
+            messageOutput.status === "completed") {
+            // Normal text response - add to history in normalized format
+            const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text);
+            this.addToHistory(entry);
+            this.emit(AgentEvent_1.AgentEvent.DONE, response, this.lastTokenUsage);
+            // Report completion to viz
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentComplete(this.vizEventId, {
+                    input: this.lastTokenUsage?.input_tokens || 0,
+                    output: this.lastTokenUsage?.output_tokens || 0,
+                    total: this.lastTokenUsage?.total_tokens || 0,
+                }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, response.output_text);
+                this.vizEventId = undefined;
+            }
+            return response.output_text;
+        }
+        else if (toolCalls.length) {
+            try {
+                // Add assistant message with tool calls to history (normalized)
+                const functionCalls = toolCalls.map((tc) => ({
+                    id: tc.id || tc.call_id,
+                    call_id: tc.call_id,
+                    name: tc.name,
+                    arguments: tc.arguments,
+                }));
+                const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
+                this.addToHistory(assistantEntry);
+                const toolResponses = await this.handleToolUse(toolCalls);
+                // Add tool results to history (normalized)
+                for (const result of toolResponses) {
+                    const resultEntry = transformers_1.openAiTransformer.toolResultEntry(result.call_id, result.output, false);
+                    this.addToHistory(resultEntry);
+                }
+                // Continue conversation
+                try {
+                    const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.entries);
+                    const newResponse = await this.client.responses.create({
+                        model: this.config.model,
+                        max_output_tokens: this.config.maxTokens,
+                        input: inputMessages,
+                        tools: this.getToolDefinitions(),
+                        store: false,
+                        temperature: this.config.temperature,
+                        top_p: this.config.topP,
+                        // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
+                        user: this.config.user,
+                        ...(this.config.disableReasoning && {
+                            reasoning: { effort: null },
+                        }),
+                        ...(this.config.reasoningEffort &&
+                            !this.config.disableReasoning && {
+                            reasoning: { effort: this.config.reasoningEffort },
+                        }),
+                    });
+                    this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
+                    return this.handleResponse(newResponse);
+                }
+                catch (error) {
+                    if (error && typeof error === "object" && "error" in error) {
+                        const openAIError = error;
+                        const apiError = new AgentError_1.ApiError(`OpenAI API error during tool response: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
+                        this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
+                        throw apiError;
+                    }
+                    else {
+                        throw new AgentError_1.ExecutionError(`Error processing tool response: ${error instanceof Error ? error.message : "Unknown error"}`);
+                    }
+                }
+            }
+            catch (error) {
+                if (this.debug) {
+                    console.error(error);
+                }
+                if (error instanceof AgentError_1.ToolExecutionError) {
+                    this.emit(AgentEvent_1.AgentEvent.TOOL_ERROR, error);
+                    throw error;
+                }
+                const executionError = new AgentError_1.ExecutionError(`Error during tool execution: ${error instanceof Error ? error.message : "Unknown error"}`);
+                this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
+                throw executionError;
+            }
+        }
+        else {
+            const error = new AgentError_1.ExecutionError(`Unexpected response format: ${JSON.stringify(response.output)}`);
+            this.emit(AgentEvent_1.AgentEvent.ERROR, error);
+            // Report error to viz
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", error.message, false);
+                this.vizEventId = undefined;
+            }
+            throw error;
+        }
+    }
+    async handleToolUse(content) {
+        if (!content || !content.length) {
+            throw new AgentError_1.ExecutionError("Invalid tool calls content");
+        }
+        // Track tool call count for viz reporting
+        this.currentToolCallCount += content.length;
+        const toolResults = await Promise.all(content.map(async (toolCall) => {
+            if (!toolCall.name) {
+                throw new AgentError_1.ExecutionError("Invalid tool call format");
+            }
+            const toolName = toolCall.name;
+            const tool = this.tools.get(toolName);
+            if (!tool) {
+                const errorMessage = `Tool '${toolName}' not found`;
+                const error = new AgentError_1.ToolExecutionError(errorMessage, toolName, toolCall.arguments);
+                if (this.debug) {
+                    console.error(error);
+                }
+                return {
+                    call_id: toolCall.call_id,
+                    output: errorMessage,
+                };
+            }
+            try {
+                let toolArgs;
+                try {
+                    toolArgs = JSON.parse(toolCall.arguments);
+                }
+                catch (parseError) {
+                    throw new AgentError_1.ToolExecutionError(`Invalid tool arguments: ${parseError instanceof Error ? parseError.message : "Parse error"}`, toolName, toolCall.arguments);
+                }
+                const result = await tool.execute(this.getId(), this.getName(), toolArgs, toolCall.id || "", this.config.model, "openai");
+                return {
+                    call_id: toolCall.call_id,
+                    output: JSON.stringify(result),
+                };
+            }
+            catch (error) {
+                const errorMessage = `Error executing tool '${toolName}': ${error instanceof Error ? error.message : "Unknown error"}`;
+                const toolError = new AgentError_1.ToolExecutionError(errorMessage, toolName, toolCall.arguments);
+                this.emit(AgentEvent_1.AgentEvent.TOOL_ERROR, toolError);
+                if (this.debug) {
+                    console.error(toolError);
+                }
+                return {
+                    call_id: toolCall.call_id,
+                    output: errorMessage,
+                };
+            }
+        }));
+        return toolResults;
+    }
+    parseUsage(input) {
+        return {
+            input_tokens: input.input_tokens,
+            output_tokens: input.output_tokens,
+            total_tokens: input.total_tokens,
+        };
+    }
+}
+exports.OpenAiAgent = OpenAiAgent;
+//# sourceMappingURL=OpenAiAgent.js.map

package/dist/chunkers/Chunker.d.ts

@@ -0,0 +1,53 @@
+import { Chunk, ChunkerConfig, ChunkOptions } from "./types";
+/**
+ * Abstract base class for text chunkers.
+ * Provides common utilities for ID generation, hashing, and chunk linking.
+ */
+export declare abstract class Chunker {
+    /** Name identifier for this chunker type */
+    abstract readonly name: string;
+    protected config: ChunkerConfig;
+    constructor(config: ChunkerConfig);
+    /**
+     * Split text into chunks with metadata.
+     * @param text - The text to chunk
+     * @param options - Optional chunking options
+     * @returns Array of chunks with metadata
+     */
+    chunk(text: string, options?: ChunkOptions): Promise<Chunk[]>;
+    /**
+     * Split the text into raw string segments.
+     * Must be implemented by subclasses.
+     */
+    protected abstract splitText(text: string): Promise<string[]> | string[];
+    /**
+     * Generate a unique ID for a chunk.
+     */
+    protected generateId(content: string, index: number, sourceId?: string): string;
+    /**
+     * Compute SHA-256 hash of content.
+     */
+    protected computeHash(content: string): string;
+    /**
+     * Link chunks with previousChunkId and nextChunkId.
+     */
+    protected linkChunks(chunks: Chunk[]): void;
+    /**
+     * Apply the chunk processor, filtering out null results.
+     */
+    protected applyProcessor(chunks: Chunk[]): Promise<Chunk[]>;
+    /**
+     * Detect section titles from content.
+     * Looks for markdown headers (# Title) or lines ending with colon.
+     */
+    protected detectSectionTitle(content: string): string | undefined;
+    /**
+     * Get the chunk size configuration.
+     */
+    getChunkSize(): number;
+    /**
+     * Get the chunk overlap configuration.
+     */
+    getChunkOverlap(): number;
+}
+//# sourceMappingURL=Chunker.d.ts.map

package/dist/chunkers/Chunker.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Chunker = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Abstract base class for text chunkers.
+ * Provides common utilities for ID generation, hashing, and chunk linking.
+ */
+class Chunker {
+    constructor(config) {
+        if (config.chunkSize <= 0) {
+            throw new Error("chunkSize must be greater than 0");
+        }
+        if (config.chunkOverlap !== undefined && config.chunkOverlap < 0) {
+            throw new Error("chunkOverlap must be non-negative");
+        }
+        if (config.chunkOverlap !== undefined &&
+            config.chunkOverlap >= config.chunkSize) {
+            throw new Error("chunkOverlap must be less than chunkSize");
+        }
+        this.config = {
+            chunkOverlap: 0,
+            ...config,
+        };
+    }
+    /**
+     * Split text into chunks with metadata.
+     * @param text - The text to chunk
+     * @param options - Optional chunking options
+     * @returns Array of chunks with metadata
+     */
+    async chunk(text, options) {
+        if (!text || text.length === 0) {
+            return [];
+        }
+        // Get raw splits from the subclass implementation
+        const splits = await this.splitText(text);
+        if (splits.length === 0) {
+            return [];
+        }
+        // Build chunks with metadata
+        const chunks = [];
+        let currentOffset = 0;
+        let currentSection;
+        for (let i = 0; i < splits.length; i++) {
+            const content = splits[i];
+            const startOffset = text.indexOf(content, currentOffset);
+            const endOffset = startOffset + content.length;
+            // Detect section titles (markdown headers or lines ending with :)
+            const detectedSection = this.detectSectionTitle(content);
+            if (detectedSection) {
+                currentSection = detectedSection;
+            }
+            const id = this.generateId(content, i, options?.sourceId);
+            const metadata = {
+                chunkIndex: i,
+                totalChunks: splits.length,
+                previousChunkId: null, // Will be linked after
+                nextChunkId: null, // Will be linked after
+                startOffset,
+                endOffset,
+                sourceId: options?.sourceId,
+                sourcePath: options?.sourcePath,
+                charCount: content.length,
+                hash: this.computeHash(content),
+                sectionTitle: currentSection,
+                ...options?.metadata,
+            };
+            chunks.push({ id, content, metadata });
+            currentOffset = startOffset + 1; // Move past current match for next search
+        }
+        // Link chunks together
+        this.linkChunks(chunks);
+        // Update totalChunks now that we know the final count
+        for (const chunk of chunks) {
+            chunk.metadata.totalChunks = chunks.length;
+        }
+        // Apply processor if provided
+        if (this.config.chunkProcessor) {
+            return this.applyProcessor(chunks);
+        }
+        return chunks;
+    }
+    /**
+     * Generate a unique ID for a chunk.
+     */
+    generateId(content, index, sourceId) {
+        if (this.config.idGenerator) {
+            return this.config.idGenerator(content, index, sourceId);
+        }
+        // Default: hash-based ID with source prefix
+        const hash = this.computeHash(content).substring(0, 8);
+        const prefix = sourceId ? `${sourceId}-` : "";
+        return `${prefix}chunk-${index}-${hash}`;
+    }
+    /**
+     * Compute SHA-256 hash of content.
+     */
+    computeHash(content) {
+        return (0, crypto_1.createHash)("sha256").update(content).digest("hex");
+    }
+    /**
+     * Link chunks with previousChunkId and nextChunkId.
+     */
+    linkChunks(chunks) {
+        for (let i = 0; i < chunks.length; i++) {
+            if (i > 0) {
+                chunks[i].metadata.previousChunkId = chunks[i - 1].id;
+            }
+            if (i < chunks.length - 1) {
+                chunks[i].metadata.nextChunkId = chunks[i + 1].id;
+            }
+        }
+    }
+    /**
+     * Apply the chunk processor, filtering out null results.
+     */
+    async applyProcessor(chunks) {
+        if (!this.config.chunkProcessor) {
+            return chunks;
+        }
+        const processed = [];
+        for (let i = 0; i < chunks.length; i++) {
+            const result = await this.config.chunkProcessor(chunks[i], i, chunks);
+            if (result !== null) {
+                processed.push(result);
+            }
+        }
+        // Re-link after filtering and update indices
+        for (let i = 0; i < processed.length; i++) {
+            processed[i].metadata.chunkIndex = i;
+            processed[i].metadata.totalChunks = processed.length;
+            processed[i].metadata.previousChunkId =
+                i > 0 ? processed[i - 1].id : null;
+            processed[i].metadata.nextChunkId =
+                i < processed.length - 1 ? processed[i + 1].id : null;
+        }
+        return processed;
+    }
+    /**
+     * Detect section titles from content.
+     * Looks for markdown headers (# Title) or lines ending with colon.
+     */
+    detectSectionTitle(content) {
+        const lines = content.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Markdown header
+            const headerMatch = trimmed.match(/^#{1,6}\s+(.+)$/);
+            if (headerMatch) {
+                return headerMatch[1].trim();
+            }
+            // Line ending with colon (common section pattern)
+            if (trimmed.endsWith(":") && trimmed.length > 1 && trimmed.length < 100) {
+                return trimmed.slice(0, -1).trim();
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get the chunk size configuration.
+     */
+    getChunkSize() {
+        return this.config.chunkSize;
+    }
+    /**
+     * Get the chunk overlap configuration.
+     */
+    getChunkOverlap() {
+        return this.config.chunkOverlap ?? 0;
+    }
+}
+exports.Chunker = Chunker;
+//# sourceMappingURL=Chunker.js.map

package/dist/chunkers/RecursiveChunker.d.ts

@@ -0,0 +1,52 @@
+import { Chunker } from "./Chunker";
+import { RecursiveChunkerConfig } from "./types";
+/**
+ * Recursive text chunker that tries to split on semantic boundaries.
+ * It attempts to split by larger separators first (paragraphs), then
+ * falls back to smaller ones (sentences, words) to keep semantic units together.
+ *
+ * @example
+ * ```typescript
+ * const chunker = new RecursiveChunker({
+ *   chunkSize: 1000,
+ *   chunkOverlap: 100,
+ *   separators: ["\n\n", "\n", ". ", " "],
+ * });
+ *
+ * const chunks = await chunker.chunk(document);
+ * ```
+ */
+export declare class RecursiveChunker extends Chunker {
+    readonly name = "RecursiveChunker";
+    private separators;
+    constructor(config: RecursiveChunkerConfig);
+    /**
+     * Split text recursively using the separator hierarchy.
+     */
+    protected splitText(text: string): string[];
+    /**
+     * Recursively split text using separators at the given index.
+     */
+    private recursiveSplit;
+    /**
+     * Split text by separator, keeping the parts clean.
+     */
+    private splitBySeparator;
+    /**
+     * Force split text by character count when no separator works.
+     */
+    private forceSplit;
+    /**
+     * Apply overlap between chunks by prepending context from previous chunk.
+     */
+    private applyOverlap;
+    /**
+     * Extract overlap text from the end of a chunk, trying to break at separator.
+     */
+    private getOverlapText;
+    /**
+     * Get the configured separators.
+     */
+    getSeparators(): string[];
+}
+//# sourceMappingURL=RecursiveChunker.d.ts.map