connectonion 0.0.1

package/dist/llm/openai.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * @purpose OpenAI LLM provider with support for GPT models, O-series models, and OpenOnion managed keys via configurable baseURL
+ * @llm-note
+ *   Dependencies: imports from [openai npm package, src/types.ts] | imported by [src/llm/index.ts, src/index.ts] | tested by [tests/e2e/realProviders.test.ts]
+ *   Data flow: receives Message[] + FunctionSchema[] → converts to OpenAI format → calls client.chat.completions.create() → parses tool_calls → returns LLMResponse
+ *   State/Effects: makes HTTP POST to OpenAI API (or baseURL override) | reads env OPENAI_API_KEY/OPENONION_API_KEY | no persistent state
+ *   Integration: implements LLM interface | exposes complete(), structuredComplete() | default model 'o4-mini' | supports baseURL override for co/* models via createLLM factory
+ *   Performance: direct API call, no caching | tool_choice: 'auto' for parallel tool execution
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAILLM = void 0;
+const openai_1 = __importDefault(require("openai"));
+class OpenAILLM {
+    constructor(apiKey, model = 'o4-mini', options) {
+        const key = apiKey || process.env.OPENAI_API_KEY || process.env.OPENONION_API_KEY;
+        if (!key) {
+            throw new Error('OpenAI-compatible API key required. Set OPENAI_API_KEY (or OPENONION_API_KEY) or pass apiKey.');
+        }
+        // Allow overriding base URL to support managed/proxy endpoints
+        const envBase = process.env.OPENAI_BASE_URL || process.env.OPENONION_BASE_URL;
+        const baseURL = options?.baseURL || envBase;
+        this.client = new openai_1.default(baseURL ? { apiKey: key, baseURL } : { apiKey: key });
+        this.model = model;
+    }
+    async complete(messages, tools) {
+        const openAIMessages = this.convertMessages(messages);
+        const params = {
+            model: this.model,
+            messages: openAIMessages,
+        };
+        if (tools && tools.length > 0) {
+            params.tools = tools.map(tool => ({
+                type: 'function',
+                function: tool,
+            }));
+            params.tool_choice = 'auto';
+        }
+        const response = await this.client.chat.completions.create(params);
+        const message = response.choices[0].message;
+        // Parse tool calls
+        const toolCalls = [];
+        if (message.tool_calls) {
+            for (const tc of message.tool_calls) {
+                toolCalls.push({
+                    name: tc.function.name,
+                    arguments: JSON.parse(tc.function.arguments),
+                    id: tc.id,
+                });
+            }
+        }
+        return {
+            content: message.content,
+            toolCalls,
+            rawResponse: response,
+        };
+    }
+    convertMessages(messages) {
+        return messages.map(msg => {
+            const converted = {
+                role: msg.role,
+                content: msg.content,
+            };
+            if (msg.name) {
+                converted.name = msg.name;
+            }
+            if (msg.tool_calls) {
+                converted.tool_calls = msg.tool_calls.map(tc => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: {
+                        name: tc.name,
+                        arguments: JSON.stringify(tc.arguments),
+                    },
+                }));
+            }
+            if (msg.tool_call_id) {
+                converted.tool_call_id = msg.tool_call_id;
+            }
+            return converted;
+        });
+    }
+    async structuredComplete(messages, schema) {
+        // Prefer responses.parse if available in the SDK
+        const anyClient = this.client;
+        try {
+            if (anyClient.responses && typeof anyClient.responses.parse === 'function') {
+                const response = await anyClient.responses.parse({
+                    model: this.model,
+                    input: this.convertMessages(messages),
+                    // Not all SDKs accept arbitrary objects; if it errors, fallback below.
+                    text_format: schema,
+                });
+                // Try common shapes for parsed output
+                if (response?.output_parsed)
+                    return response.output_parsed;
+                if (response?.parsed)
+                    return response.parsed;
+            }
+        }
+        catch (_err) {
+            // Fall through to chat JSON fallback
+        }
+        // Fallback: ask the model to return only JSON matching the schema
+        const system = `You are a JSON generator. Return ONLY valid minified JSON matching this schema: ${JSON.stringify(schema)}. No prose.`;
+        const openAIMessages = this.convertMessages([
+            { role: 'system', content: system },
+            ...messages,
+        ]);
+        const res = await this.client.chat.completions.create({
+            model: this.model,
+            messages: openAIMessages,
+            temperature: 0,
+        });
+        const content = res.choices?.[0]?.message?.content || '{}';
+        try {
+            return JSON.parse(content);
+        }
+        catch (e) {
+            // Try to extract JSON substring if the model added extra text
+            const match = content.match(/\{[\s\S]*\}/);
+            if (match)
+                return JSON.parse(match[0]);
+            throw new Error(`Failed to parse structured JSON: ${String(e)} | content=${content}`);
+        }
+    }
+}
+exports.OpenAILLM = OpenAILLM;

package/dist/src/core/agent.js

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * Core Agent implementation for ConnectOnion TypeScript SDK
+ *
+ * The Agent class is the main orchestrator that combines LLM capabilities
+ * with tool execution to create powerful AI agents that can perform actions.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const llm_1 = require("../llm");
+const history_1 = require("../history");
+const tool_utils_1 = require("../tools/tool-utils");
+const dotenv = __importStar(require("dotenv"));
+// Load environment variables from .env file
+dotenv.config();
+/**
+ * Agent class - The core of ConnectOnion
+ *
+ * An Agent combines:
+ * - LLM for intelligence and reasoning
+ * - Tools for taking actions
+ * - History for behavior tracking
+ * - System prompts for personality
+ *
+ * @example
+ * ```typescript
+ * // Create a simple agent with a calculator tool
+ * function add(a: number, b: number): number {
+ *   return a + b;
+ * }
+ *
+ * const agent = new Agent({
+ *   name: 'calculator',
+ *   tools: [add],
+ *   systemPrompt: 'You are a helpful math assistant.'
+ * });
+ *
+ * const response = await agent.input('What is 5 plus 3?');
+ * console.log(response); // "5 plus 3 equals 8"
+ * ```
+ */
+class Agent {
+    /**
+     * Creates a new Agent instance
+     *
+     * @param config - Configuration object for the agent
+     * @param config.name - Unique name for the agent (used for behavior tracking)
+     * @param config.llm - Optional custom LLM instance
+     * @param config.tools - Array of tools (functions, class instances, or Tool objects)
+     * @param config.systemPrompt - System prompt defining agent behavior
+     * @param config.apiKey - API key for LLM provider (uses env var if not provided)
+     * @param config.model - Model to use (default: 'gpt-4o-mini')
+     * @param config.maxIterations - Max iterations for tool calling (default: 10)
+     *
+     * @example
+     * ```typescript
+     * // With environment variable for API key
+     * const agent = new Agent({
+     *   name: 'my-agent',
+     *   tools: [myTool1, myTool2]
+     * });
+     *
+     * // With explicit API key
+     * const agent = new Agent({
+     *   name: 'my-agent',
+     *   apiKey: 'sk-...',
+     *   model: 'gpt-4',
+     *   tools: [myTool]
+     * });
+     * ```
+     */
+    constructor(config) {
+        this.name = config.name;
+        this.systemPrompt = config.systemPrompt || `You are ${config.name}, a helpful AI assistant.`;
+        this.maxIterations = config.maxIterations || 10;
+        // Process tools: convert functions, class instances, etc. to Tool objects
+        this.tools = (0, tool_utils_1.processTools)(config.tools || []);
+        // Create a map for O(1) tool lookup by name
+        this.toolMap = new Map(this.tools.map(tool => [tool.name, tool]));
+        // Initialize behavior history tracking
+        // All behaviors are saved to ~/.connectonion/agents/{name}/behavior.json
+        this.history = new history_1.History(this.name);
+        // Initialize LLM - either use provided instance or create one
+        if (config.llm) {
+            this.llm = config.llm;
+        }
+        else {
+            // Create LLM based on model name (currently supports OpenAI)
+            this.llm = (0, llm_1.createLLM)(config.model || 'gpt-4o-mini', config.apiKey);
+        }
+        // Trust parameter handling can be added later if needed
+    }
+    /**
+     * Process user input and generate a response
+     *
+     * This is the main entry point for interacting with the agent.
+     * The agent will:
+     * 1. Process the input prompt
+     * 2. Decide whether to use tools
+     * 3. Execute any necessary tool calls
+     * 4. Generate a final response
+     *
+     * @param prompt - The user's input prompt
+     * @param maxIterations - Override the default max iterations for this request
+     * @returns The agent's response as a string
+     *
+     * @example
+     * ```typescript
+     * const response = await agent.input('What is the weather in NYC?');
+     * console.log(response);
+     *
+     * // With custom iteration limit for complex tasks
+     * const response = await agent.input(
+     *   'Analyze this data and create a report',
+     *   20 // Allow more iterations for complex task
+     * );
+     * ```
+     */
+    async input(prompt, maxIterations) {
+        const iterations = maxIterations || this.maxIterations;
+        // Record the input in history
+        this.history.addInput(prompt);
+        // Initialize conversation with system prompt and user input
+        const messages = [
+            { role: 'system', content: this.systemPrompt },
+            { role: 'user', content: prompt }
+        ];
+        // Convert tools to OpenAI-compatible function schemas
+        const toolSchemas = this.tools.map(tool => tool.toFunctionSchema());
+        let finalResponse = '';
+        // Main execution loop - allows for multiple rounds of tool calling
+        for (let i = 0; i < iterations; i++) {
+            // Call LLM with current conversation and available tools
+            const llmResponse = await this.llm.complete(messages, toolSchemas);
+            // Record the LLM response in history
+            this.history.addLLMResponse(llmResponse);
+            // Add assistant's response to the conversation
+            if (llmResponse.content || llmResponse.toolCalls.length > 0) {
+                const assistantMessage = {
+                    role: 'assistant',
+                    content: llmResponse.content || '',
+                };
+                // Include tool calls in the message if present
+                if (llmResponse.toolCalls.length > 0) {
+                    assistantMessage.tool_calls = llmResponse.toolCalls;
+                }
+                messages.push(assistantMessage);
+            }
+            // Process tool calls if the LLM requested any
+            if (llmResponse.toolCalls.length > 0) {
+                // Execute all tool calls in parallel for efficiency
+                const toolResults = await this.executeToolCalls(llmResponse.toolCalls);
+                // Add tool results back to the conversation
+                // This allows the LLM to see the results and continue reasoning
+                for (const result of toolResults) {
+                    messages.push({
+                        role: 'tool',
+                        content: JSON.stringify(result.result),
+                        tool_call_id: result.callId,
+                    });
+                }
+            }
+            else {
+                // No more tool calls - we have our final response
+                finalResponse = llmResponse.content || '';
+                break;
+            }
+        }
+        // Record the final output in history
+        this.history.addOutput(finalResponse);
+        return finalResponse;
+    }
+    /**
+     * Execute multiple tool calls in parallel
+     *
+     * @param toolCalls - Array of tool calls to execute
+     * @returns Array of results with their corresponding call IDs
+     *
+     * @private
+     */
+    async executeToolCalls(toolCalls) {
+        // Execute all tool calls in parallel using Promise.all
+        // This significantly improves performance when multiple tools are called
+        const results = await Promise.all(toolCalls.map(async (toolCall) => {
+            const result = await this.executeToolCall(toolCall.name, toolCall.arguments, toolCall.id);
+            return { result, callId: toolCall.id };
+        }));
+        return results;
+    }
+    /**
+     * Execute a single tool call
+     *
+     * @param name - Name of the tool to execute
+     * @param args - Arguments to pass to the tool
+     * @param callId - Unique identifier for this tool call
+     * @returns The result of the tool execution
+     *
+     * @private
+     */
+    async executeToolCall(name, args, callId) {
+        // Look up the tool by name
+        const tool = this.toolMap.get(name);
+        // Handle case where tool doesn't exist
+        if (!tool) {
+            const result = {
+                status: 'not_found',
+                error: `Tool ${name} not found`,
+            };
+            // Record the failed tool call in history
+            this.history.addToolCall(name, args, result, callId);
+            return result;
+        }
+        try {
+            // Execute the tool with provided arguments
+            const output = await tool.run(args);
+            const result = {
+                status: 'success',
+                result: output,
+            };
+            // Record successful tool call in history
+            this.history.addToolCall(name, args, result, callId);
+            return result;
+        }
+        catch (error) {
+            // Handle tool execution errors gracefully
+            const result = {
+                status: 'error',
+                error: error instanceof Error ? error.message : String(error),
+            };
+            // Record the error in history
+            this.history.addToolCall(name, args, result, callId);
+            return result;
+        }
+    }
+    /**
+     * Get the complete conversation history
+     *
+     * @returns Array of all behavior entries
+     *
+     * @example
+     * ```typescript
+     * const history = agent.getHistory();
+     * console.log(`Total interactions: ${history.length}`);
+     *
+     * // Filter for tool calls
+     * const toolCalls = history.filter(h => h.type === 'tool_call');
+     * ```
+     */
+    getHistory() {
+        return this.history.getBehaviors();
+    }
+    /**
+     * Clear the conversation history
+     *
+     * This removes all recorded behaviors for this agent.
+     * Use with caution as this action cannot be undone.
+     *
+     * @example
+     * ```typescript
+     * agent.clearHistory();
+     * console.log('History cleared');
+     * ```
+     */
+    clearHistory() {
+        this.history.clear();
+    }
+    /**
+     * Get all available tools for this agent
+     *
+     * @returns Array of Tool objects
+     *
+     * @example
+     * ```typescript
+     * const tools = agent.getTools();
+     * console.log('Available tools:');
+     * tools.forEach(tool => {
+     *   console.log(`- ${tool.name}: ${tool.description}`);
+     * });
+     * ```
+     */
+    getTools() {
+        return this.tools;
+    }
+    /**
+     * Dynamically add a new tool to the agent
+     *
+     * @param tool - Tool to add (function, class instance, or Tool object)
+     *
+     * @example
+     * ```typescript
+     * // Add a function as a tool
+     * function newTool(param: string): string {
+     *   return `Processed: ${param}`;
+     * }
+     * agent.addTool(newTool);
+     *
+     * // Add a class instance
+     * class MyService {
+     *   getData(): string { return 'data'; }
+     * }
+     * agent.addTool(new MyService());
+     * ```
+     */
+    addTool(tool) {
+        const processed = (0, tool_utils_1.processTools)([tool]);
+        for (const t of processed) {
+            this.tools.push(t);
+            this.toolMap.set(t.name, t);
+        }
+    }
+    /**
+     * Remove a tool by name
+     *
+     * @param name - Name of the tool to remove
+     * @returns true if the tool was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const removed = agent.removeTool('oldTool');
+     * if (removed) {
+     *   console.log('Tool removed successfully');
+     * }
+     * ```
+     */
+    removeTool(name) {
+        const index = this.tools.findIndex(t => t.name === name);
+        if (index !== -1) {
+            this.tools.splice(index, 1);
+            this.toolMap.delete(name);
+            return true;
+        }
+        return false;
+    }
+}
+exports.Agent = Agent;

package/dist/src/history/index.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * History tracking for ConnectOnion TypeScript SDK
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.History = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+class History {
+    constructor(name) {
+        this.behaviors = [];
+        // Set up behavior tracking directory
+        const homeDir = os.homedir();
+        const connectonionDir = path.join(homeDir, '.connectonion', 'agents', name);
+        // Create directory if it doesn't exist
+        if (!fs.existsSync(connectonionDir)) {
+            fs.mkdirSync(connectonionDir, { recursive: true });
+        }
+        this.behaviorPath = path.join(connectonionDir, 'behavior.json');
+        // Load existing behaviors if file exists
+        if (fs.existsSync(this.behaviorPath)) {
+            try {
+                const data = fs.readFileSync(this.behaviorPath, 'utf-8');
+                const parsed = JSON.parse(data);
+                // Ensure behaviors is always an array
+                if (Array.isArray(parsed)) {
+                    this.behaviors = parsed;
+                }
+                else {
+                    console.warn('Behavior file does not contain an array, initializing empty');
+                    this.behaviors = [];
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to load existing behaviors: ${error}`);
+                this.behaviors = [];
+            }
+        }
+    }
+    /**
+     * Add an entry to the behavior history
+     */
+    add(type, data) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            type,
+            data,
+        };
+        this.behaviors.push(entry);
+        this.save();
+    }
+    /**
+     * Add input to history
+     */
+    addInput(prompt) {
+        this.add('input', { prompt });
+    }
+    /**
+     * Add LLM response to history
+     */
+    addLLMResponse(response) {
+        this.add('llm_response', response);
+    }
+    /**
+     * Add tool call to history
+     */
+    addToolCall(name, args, result, callId) {
+        this.add('tool_call', {
+            name,
+            arguments: args,
+            result,
+            call_id: callId,
+        });
+    }
+    /**
+     * Add output to history
+     */
+    addOutput(output) {
+        this.add('output', { output });
+    }
+    /**
+     * Get all behaviors
+     */
+    getBehaviors() {
+        return this.behaviors;
+    }
+    /**
+     * Clear history
+     */
+    clear() {
+        this.behaviors = [];
+        this.save();
+    }
+    /**
+     * Save behaviors to file
+     */
+    save() {
+        try {
+            fs.writeFileSync(this.behaviorPath, JSON.stringify(this.behaviors, null, 2), 'utf-8');
+        }
+        catch (error) {
+            console.error(`Failed to save behaviors: ${error}`);
+        }
+    }
+}
+exports.History = History;

package/dist/src/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * ConnectOnion TypeScript SDK
+ * A framework for creating AI agents with behavior tracking
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processTools = exports.extractMethodsFromInstance = exports.isClassInstance = exports.createToolFromFunction = exports.History = exports.OpenAILLM = exports.createLLM = exports.Agent = void 0;
+var agent_1 = require("./core/agent");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_1.Agent; } });
+var llm_1 = require("./llm");
+Object.defineProperty(exports, "createLLM", { enumerable: true, get: function () { return llm_1.createLLM; } });
+Object.defineProperty(exports, "OpenAILLM", { enumerable: true, get: function () { return llm_1.OpenAILLM; } });
+var history_1 = require("./history");
+Object.defineProperty(exports, "History", { enumerable: true, get: function () { return history_1.History; } });
+var tool_utils_1 = require("./tools/tool-utils");
+Object.defineProperty(exports, "createToolFromFunction", { enumerable: true, get: function () { return tool_utils_1.createToolFromFunction; } });
+Object.defineProperty(exports, "isClassInstance", { enumerable: true, get: function () { return tool_utils_1.isClassInstance; } });
+Object.defineProperty(exports, "extractMethodsFromInstance", { enumerable: true, get: function () { return tool_utils_1.extractMethodsFromInstance; } });
+Object.defineProperty(exports, "processTools", { enumerable: true, get: function () { return tool_utils_1.processTools; } });
+__exportStar(require("./types"), exports);

package/dist/src/llm/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * LLM factory and exports for ConnectOnion TypeScript SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAILLM = void 0;
+exports.createLLM = createLLM;
+const openai_1 = require("./openai");
+var openai_2 = require("./openai");
+Object.defineProperty(exports, "OpenAILLM", { enumerable: true, get: function () { return openai_2.OpenAILLM; } });
+/**
+ * Create an LLM instance based on the model name
+ */
+function createLLM(model = 'gpt-4o-mini', apiKey) {
+    // For now, we only support OpenAI models
+    // In the future, we can add support for Anthropic, Google, etc.
+    if (model.startsWith('gpt-') || model.startsWith('o1-')) {
+        return new openai_1.OpenAILLM(apiKey, model);
+    }
+    // Default to OpenAI
+    return new openai_1.OpenAILLM(apiKey, model);
+}