@agentionai/agents 0.3.0-beta

package/dist/graph/VotingSystem.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VotingSystem = void 0;
+const BaseExecutor_1 = require("./BaseExecutor");
+const DEFAULT_PROMPT_TEMPLATE = `You are a judge who must select the best answer from multiple experts.
+
+Original question: {originalQuestion}
+
+Expert answers:
+{expertAnswers}
+
+Select the best answer, or synthesize a better answer from the experts' inputs.
+Your response should be the final answer without explanation or preamble.`;
+/**
+ * A voting system that uses a judge agent to select or synthesize
+ * the best answer from multiple solutions.
+ *
+ * Typically used after a ParallelExecutor to evaluate multiple expert opinions.
+ *
+ * @example
+ * ```typescript
+ * const voting = new VotingSystem(judgeAgent);
+ * const result = await voting.execute({
+ *   originalInput: "What is the best approach?",
+ *   solutions: [expertA_answer, expertB_answer, expertC_answer]
+ * });
+ * ```
+ */
+class VotingSystem extends BaseExecutor_1.BaseExecutor {
+    constructor(judge, options = {}) {
+        super();
+        this.name = "VotingSystem";
+        this.nodeType = "voting";
+        this.judge = judge;
+        this.promptTemplate = options.promptTemplate || DEFAULT_PROMPT_TEMPLATE;
+    }
+    /**
+     * Evaluates the solutions and returns the judge's verdict.
+     * @param input - Object containing originalInput and solutions array
+     * @returns The judge's selected or synthesized answer
+     * @throws Error if input is a string (must be VotingInput object)
+     */
+    async execute(input) {
+        const collector = this.getCollector();
+        const execId = collector?.startExecution(this.name, "voting", input);
+        if (typeof input === "string") {
+            const error = new Error("VotingSystem requires an object with originalInput and solutions properties. " +
+                "Use as part of a pipeline after a parallel executor, or provide a VotingInput object.");
+            if (execId)
+                collector?.endExecution(execId, false, undefined, undefined, error.message);
+            throw error;
+        }
+        const { originalInput, solutions } = input;
+        if (!solutions || solutions.length === 0) {
+            const error = new Error("VotingSystem requires at least one solution to evaluate");
+            if (execId)
+                collector?.endExecution(execId, false, undefined, undefined, error.message);
+            throw error;
+        }
+        const formattedAnswers = solutions
+            .map((solution, index) => `Expert ${index + 1}: ${solution}`)
+            .join("\n\n");
+        const votingPrompt = this.promptTemplate
+            .replace("{originalQuestion}", originalInput || "")
+            .replace("{expertAnswers}", formattedAnswers);
+        // Track judge execution
+        const judgeName = this.judge.getName?.() ?? "Judge";
+        const judgeExecId = collector?.startExecution(judgeName, "agent", votingPrompt);
+        try {
+            const result = (await this.judge.execute(votingPrompt));
+            // Extract token usage from judge
+            const tokenUsage = this.extractTokenUsage(this.judge);
+            if (judgeExecId)
+                collector?.endExecution(judgeExecId, true, result, tokenUsage);
+            if (execId)
+                collector?.endExecution(execId, true, result, tokenUsage);
+            return result;
+        }
+        catch (error) {
+            if (judgeExecId) {
+                collector?.endExecution(judgeExecId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            if (execId) {
+                collector?.endExecution(execId, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Attempt to extract token usage from an agent.
+     * Converts from agent's snake_case format to metrics camelCase format.
+     */
+    extractTokenUsage(agent) {
+        const agentWithUsage = agent;
+        if (!agentWithUsage.lastTokenUsage)
+            return undefined;
+        // Convert from snake_case to camelCase
+        return {
+            inputTokens: agentWithUsage.lastTokenUsage.input_tokens,
+            outputTokens: agentWithUsage.lastTokenUsage.output_tokens,
+            totalTokens: agentWithUsage.lastTokenUsage.total_tokens,
+        };
+    }
+}
+exports.VotingSystem = VotingSystem;
+//# sourceMappingURL=VotingSystem.js.map

package/dist/history/History.d.ts

@@ -0,0 +1,107 @@
+import EventEmitter from "events";
+import { HistoryEntry, MessageRole, MessageContent } from "./types";
+export type { HistoryEntry, MessageRole, MessageContent } from "./types";
+export { text, toolUse, toolResult, textMessage, isTextContent, isToolUseContent, isToolResultContent, } from "./types";
+/**
+ * Internal entry with metadata
+ */
+type EntryWithMetadata = HistoryEntry & {
+    __metadata: {
+        date: string;
+        contentLength: number;
+    };
+};
+/**
+ * History configuration options
+ */
+type HistoryOptions = {
+    maxLength?: number;
+    transient?: boolean;
+};
+/**
+ * Manages conversation history in a provider-agnostic format.
+ *
+ * This class stores history entries in a normalized format that can be
+ * transformed to any LLM provider's native format using the transformers.
+ *
+ * History can be shared between agents of different providers, enabling
+ * cross-provider conversations and handoffs.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const history = new History();
+ * history.addText("user", "Hello!");
+ * history.addText("assistant", "Hi there!");
+ * ```
+ *
+ * @example Sharing between agents
+ * ```typescript
+ * const history = new History();
+ * const claudeAgent = new ClaudeAgent({ ... }, history);
+ * const openAiAgent = new OpenAiAgent({ ... }, history);
+ * // Both agents share the same conversation history
+ * ```
+ */
+export declare class History extends EventEmitter {
+    protected _entries: EntryWithMetadata[];
+    private options;
+    transient: boolean;
+    constructor(entries?: HistoryEntry[], options?: HistoryOptions);
+    /**
+     * Add a complete history entry
+     */
+    addEntry(entry: HistoryEntry): void;
+    /**
+     * Add a simple text message
+     */
+    addText(role: MessageRole, content: string): void;
+    /**
+     * Add a message with multiple content blocks
+     */
+    addMessage(role: MessageRole, content: MessageContent[]): void;
+    /**
+     * Add a system message
+     */
+    addSystem(content: string): void;
+    /**
+     * Get all entries (without internal metadata)
+     */
+    get entries(): HistoryEntry[];
+    /**
+     * Get the number of entries
+     */
+    get length(): number;
+    /**
+     * Get total content size in characters
+     */
+    get size(): number;
+    /**
+     * Get the last entry
+     */
+    lastEntry(): HistoryEntry | undefined;
+    /**
+     * Get system message if present
+     */
+    getSystemMessage(): string | undefined;
+    /**
+     * Get entries without system messages
+     */
+    getMessagesWithoutSystem(): HistoryEntry[];
+    /**
+     * Clear all history entries
+     */
+    clear(): void;
+    /**
+     * Serialize history to JSON
+     */
+    toJSON(): string;
+    /**
+     * Create a History instance from JSON
+     */
+    static fromJSON(json: string, options?: HistoryOptions): History;
+    /**
+     * Create a copy of this history
+     */
+    clone(options?: HistoryOptions): History;
+}
+//# sourceMappingURL=History.d.ts.map

package/dist/history/History.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.History = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.textMessage = exports.toolResult = exports.toolUse = exports.text = void 0;
+const events_1 = __importDefault(require("events"));
+const types_1 = require("./types");
+var types_2 = require("./types");
+Object.defineProperty(exports, "text", { enumerable: true, get: function () { return types_2.text; } });
+Object.defineProperty(exports, "toolUse", { enumerable: true, get: function () { return types_2.toolUse; } });
+Object.defineProperty(exports, "toolResult", { enumerable: true, get: function () { return types_2.toolResult; } });
+Object.defineProperty(exports, "textMessage", { enumerable: true, get: function () { return types_2.textMessage; } });
+Object.defineProperty(exports, "isTextContent", { enumerable: true, get: function () { return types_2.isTextContent; } });
+Object.defineProperty(exports, "isToolUseContent", { enumerable: true, get: function () { return types_2.isToolUseContent; } });
+Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: function () { return types_2.isToolResultContent; } });
+/**
+ * Manages conversation history in a provider-agnostic format.
+ *
+ * This class stores history entries in a normalized format that can be
+ * transformed to any LLM provider's native format using the transformers.
+ *
+ * History can be shared between agents of different providers, enabling
+ * cross-provider conversations and handoffs.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const history = new History();
+ * history.addText("user", "Hello!");
+ * history.addText("assistant", "Hi there!");
+ * ```
+ *
+ * @example Sharing between agents
+ * ```typescript
+ * const history = new History();
+ * const claudeAgent = new ClaudeAgent({ ... }, history);
+ * const openAiAgent = new OpenAiAgent({ ... }, history);
+ * // Both agents share the same conversation history
+ * ```
+ */
+class History extends events_1.default {
+    constructor(entries = [], options = {}) {
+        super();
+        this._entries = [];
+        this.transient = false;
+        this.options = options;
+        this.transient = Boolean(options?.transient);
+        // Convert initial entries to internal format with metadata
+        for (const entry of entries) {
+            this.addEntry(entry);
+        }
+    }
+    /**
+     * Add a complete history entry
+     */
+    addEntry(entry) {
+        const __metadata = {
+            date: new Date().toISOString(),
+            contentLength: JSON.stringify(entry.content).length,
+        };
+        this._entries.push({
+            ...entry,
+            __metadata,
+        });
+        this.emit("entry", entry);
+    }
+    /**
+     * Add a simple text message
+     */
+    addText(role, content) {
+        this.addEntry({
+            role,
+            content: [(0, types_1.text)(content)],
+        });
+    }
+    /**
+     * Add a message with multiple content blocks
+     */
+    addMessage(role, content) {
+        this.addEntry({ role, content });
+    }
+    /**
+     * Add a system message
+     */
+    addSystem(content) {
+        this.addText("system", content);
+    }
+    /**
+     * Get all entries (without internal metadata)
+     */
+    get entries() {
+        return this._entries.map((entry) => {
+            const { __metadata, ...rest } = entry;
+            return rest;
+        });
+    }
+    /**
+     * Get the number of entries
+     */
+    get length() {
+        return this._entries.length;
+    }
+    /**
+     * Get total content size in characters
+     */
+    get size() {
+        return this._entries.reduce((total, { __metadata }) => {
+            return total + __metadata.contentLength;
+        }, 0);
+    }
+    /**
+     * Get the last entry
+     */
+    lastEntry() {
+        if (this._entries.length === 0)
+            return undefined;
+        const { __metadata, ...entry } = this._entries[this._entries.length - 1];
+        return entry;
+    }
+    /**
+     * Get system message if present
+     */
+    getSystemMessage() {
+        const systemEntry = this._entries.find((e) => e.role === "system");
+        if (!systemEntry)
+            return undefined;
+        return systemEntry.content
+            .filter(types_1.isTextContent)
+            .map((c) => c.text)
+            .join("\n");
+    }
+    /**
+     * Get entries without system messages
+     */
+    getMessagesWithoutSystem() {
+        return this.entries.filter((e) => e.role !== "system");
+    }
+    /**
+     * Clear all history entries
+     */
+    clear() {
+        this._entries = [];
+        this.emit("clear");
+    }
+    /**
+     * Serialize history to JSON
+     */
+    toJSON() {
+        return JSON.stringify(this.entries);
+    }
+    /**
+     * Create a History instance from JSON
+     */
+    static fromJSON(json, options) {
+        const entries = JSON.parse(json);
+        return new History(entries, options);
+    }
+    /**
+     * Create a copy of this history
+     */
+    clone(options) {
+        return new History(this.entries, options ?? this.options);
+    }
+}
+exports.History = History;
+//# sourceMappingURL=History.js.map

package/dist/history/RedisHistory.d.ts

@@ -0,0 +1,27 @@
+import { History } from "./History";
+interface RedisInstance {
+    get(key: string): Promise<string | null>;
+    set(key: string, content: string): Promise<"OK">;
+}
+export declare class RedisHistory extends History {
+    private redisInstance;
+    constructor(redisInstance: RedisInstance);
+    /**
+     * Loads history entries from Redis using the specified key
+     *
+     * @param {string} key - The Redis key to retrieve history entries from
+     * @returns {Promise<void>} A promise that resolves when history is loaded
+     * @throws {Error} If there's an issue retrieving or parsing the history entries
+     */
+    load(key: string): Promise<void>;
+    /**
+     * Saves the current history entries to Redis using the specified key
+     *
+     * @param {string} key - The Redis key to save history entries under
+     * @returns {Promise<void>} A promise that resolves when history is saved
+     * @throws {Error} If there's an issue serializing or saving the history entries
+     */
+    save(key: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=RedisHistory.d.ts.map

package/dist/history/RedisHistory.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisHistory = void 0;
+const History_1 = require("./History");
+class RedisHistory extends History_1.History {
+    constructor(redisInstance) {
+        super([], { transient: false });
+        this.redisInstance = redisInstance;
+    }
+    /**
+     * Loads history entries from Redis using the specified key
+     *
+     * @param {string} key - The Redis key to retrieve history entries from
+     * @returns {Promise<void>} A promise that resolves when history is loaded
+     * @throws {Error} If there's an issue retrieving or parsing the history entries
+     */
+    async load(key) {
+        try {
+            // Retrieve the serialized history from Redis
+            const serializedHistory = await this.redisInstance.get(key);
+            // If no history exists for the key, return early
+            if (!serializedHistory) {
+                return;
+            }
+            // Parse the serialized history and create a new History instance
+            const entries = JSON.parse(serializedHistory);
+            this._entries = entries;
+        }
+        catch (error) {
+            console.error(`Error loading history from Redis key "${key}":`, error);
+            throw new Error(`Failed to load history: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Saves the current history entries to Redis using the specified key
+     *
+     * @param {string} key - The Redis key to save history entries under
+     * @returns {Promise<void>} A promise that resolves when history is saved
+     * @throws {Error} If there's an issue serializing or saving the history entries
+     */
+    async save(key) {
+        try {
+            // Serialize the current history entries
+            const serializedHistory = this.toJSON();
+            // Save the serialized history to Redis
+            await this.redisInstance.set(key, serializedHistory);
+        }
+        catch (error) {
+            console.error(`Error saving history to Redis key "${key}":`, error);
+            throw new Error(`Failed to save history: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+exports.RedisHistory = RedisHistory;
+//# sourceMappingURL=RedisHistory.js.map

package/dist/history/transformers.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Provider Transformers
+ *
+ * Transform between normalized HistoryEntry format and provider-specific formats.
+ */
+import type { MessageParam, ContentBlock } from "@anthropic-ai/sdk/resources";
+import type { ResponseInputItem } from "openai/resources/responses/responses";
+import type { Content, Part } from "@google/generative-ai";
+import { HistoryEntry } from "./types";
+export declare const anthropicTransformer: {
+    /**
+     * Convert normalized entries to Anthropic MessageParam format
+     */
+    toProvider(entries: HistoryEntry[]): MessageParam[];
+    /**
+     * Convert Anthropic response content to normalized HistoryEntry
+     */
+    fromProviderContent(role: "user" | "assistant", content: ContentBlock[]): HistoryEntry;
+    /**
+     * Extract system message from entries
+     */
+    getSystemMessage(entries: HistoryEntry[]): string | undefined;
+};
+export declare const openAiTransformer: {
+    /**
+     * Convert normalized entries to OpenAI ResponseInputItem format
+     */
+    toProvider(entries: HistoryEntry[]): ResponseInputItem[];
+    /**
+     * Convert OpenAI response to normalized HistoryEntry
+     */
+    fromProviderMessage(role: "assistant" | "user", outputText: string, functionCalls?: Array<{
+        id: string;
+        call_id: string;
+        name: string;
+        arguments: string;
+    }>): HistoryEntry;
+    /**
+     * Create a tool result entry from OpenAI function call output
+     */
+    toolResultEntry(call_id: string, output: string, is_error?: boolean): HistoryEntry;
+};
+type MistralMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    name?: string;
+    toolCallId?: string;
+};
+type MistralResponseMessage = {
+    content?: string | null | Array<{
+        type: string;
+        text?: string;
+    } | string>;
+    toolCalls?: Array<{
+        id?: string;
+        function: {
+            name: string;
+            arguments: unknown;
+        };
+    }> | null;
+};
+export declare const mistralTransformer: {
+    /**
+     * Convert normalized entries to Mistral message format
+     */
+    toProvider(entries: HistoryEntry[]): MistralMessage[];
+    /**
+     * Convert Mistral response to normalized HistoryEntry
+     */
+    fromProviderMessage(message: MistralResponseMessage): HistoryEntry;
+    /**
+     * Create a tool result entry for Mistral
+     */
+    toolResultEntry(tool_call_id: string, name: string, output: string): HistoryEntry;
+};
+export declare const geminiTransformer: {
+    /**
+     * Convert normalized entries to Gemini Content format
+     */
+    toProvider(entries: HistoryEntry[]): Content[];
+    /**
+     * Convert Gemini response parts to normalized HistoryEntry
+     */
+    fromProviderContent(role: "user" | "assistant", parts: Part[]): HistoryEntry;
+    /**
+     * Create a tool result entry for Gemini
+     */
+    toolResultEntry(functionName: string, output: string, is_error?: boolean): HistoryEntry;
+    /**
+     * Extract system message from entries
+     */
+    getSystemMessage(entries: HistoryEntry[]): string | undefined;
+};
+export {};
+//# sourceMappingURL=transformers.d.ts.map