@toolplex/ai-engine 0.1.0

package/src/mcp/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @toolplex/ai-engine - MCP Module
+ *
+ * MCP (Model Context Protocol) client for ToolPlex.
+ */
+
+export { MCPClient } from "./MCPClient.js";
+export type {
+  MCPSession,
+  MCPResult,
+  MCPTool,
+  MCPToolResult,
+  TransportFactory,
+  MCPClientConfig,
+} from "./types.js";
+
+// Path utilities
+export { getToolplexClientPath } from "./paths.js";
+
+// Default transport factory (uses system Node.js)
+export {
+  DefaultStdioTransportFactory,
+  defaultStdioTransportFactory,
+} from "./DefaultStdioTransportFactory.js";

package/src/mcp/paths.ts

@@ -0,0 +1,91 @@
+/**
+ * @toolplex/ai-engine - MCP Paths
+ *
+ * Utilities for locating @toolplex/client MCP server.
+ */
+
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+// Create __dirname equivalent for ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Create require function for ESM (for require.resolve)
+const require = createRequire(import.meta.url);
+
+/**
+ * Get the path to @toolplex/client's MCP server entry point.
+ *
+ * This resolves the path regardless of where npm installs the package
+ * (hoisted or nested in node_modules).
+ *
+ * @returns Path to the MCP server index.js
+ * @throws Error if @toolplex/client cannot be found
+ */
+export function getToolplexClientPath(): string {
+  // Try to resolve using require.resolve
+  try {
+    const clientPackageJson = require.resolve("@toolplex/client/package.json");
+    const clientDir = path.dirname(clientPackageJson);
+    const mcpServerPath = path.join(
+      clientDir,
+      "dist",
+      "mcp-server",
+      "index.js",
+    );
+
+    if (fs.existsSync(mcpServerPath)) {
+      return mcpServerPath;
+    }
+  } catch {
+    // require.resolve failed, try fallback paths
+  }
+
+  // Fallback: try common paths
+  const fallbackPaths = [
+    // From process.cwd() (development)
+    path.resolve(
+      process.cwd(),
+      "node_modules/@toolplex/client/dist/mcp-server/index.js",
+    ),
+    // From this module's location (when installed as dependency)
+    path.resolve(
+      __dirname,
+      "../../node_modules/@toolplex/client/dist/mcp-server/index.js",
+    ),
+    path.resolve(
+      __dirname,
+      "../../../node_modules/@toolplex/client/dist/mcp-server/index.js",
+    ),
+    path.resolve(
+      __dirname,
+      "../../../../node_modules/@toolplex/client/dist/mcp-server/index.js",
+    ),
+  ];
+
+  // Add Electron production path if available (process.resourcesPath is Electron-specific)
+  const electronProcess = process as typeof process & {
+    resourcesPath?: string;
+  };
+  if (electronProcess.resourcesPath) {
+    fallbackPaths.push(
+      path.resolve(
+        electronProcess.resourcesPath,
+        "app/node_modules/@toolplex/client/dist/mcp-server/index.js",
+      ),
+    );
+  }
+
+  for (const fallbackPath of fallbackPaths) {
+    if (fs.existsSync(fallbackPath)) {
+      return fallbackPath;
+    }
+  }
+
+  throw new Error(
+    "@toolplex/client not found. Make sure @toolplex/ai-engine is properly installed.",
+  );
+}

package/src/mcp/types.ts

@@ -0,0 +1,93 @@
+/**
+ * @toolplex/ai-engine - MCP Types
+ *
+ * Type definitions for MCP (Model Context Protocol) integration.
+ */
+
+/**
+ * MCP Session - holds the client connection
+ * Client type is 'any' to avoid version mismatches between ai-engine and consumers
+ */
+export interface MCPSession {
+  client: any; // MCP Client instance
+  transport: any; // Transport type varies by platform
+}
+
+/**
+ * Result from MCP operations
+ */
+export interface MCPResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+}
+
+/**
+ * MCP Tool definition from server
+ */
+export interface MCPTool {
+  name: string;
+  description?: string;
+  inputSchema?: any;
+}
+
+/**
+ * MCP Tool call result
+ */
+export interface MCPToolResult {
+  content: Array<{
+    type: string;
+    text?: string;
+    data?: any;
+    [key: string]: any;
+  }>;
+  isError?: boolean;
+  [key: string]: any;
+}
+
+/**
+ * Transport factory interface - platforms implement this
+ */
+export interface TransportFactory {
+  /**
+   * Create a transport and connect to the MCP server
+   * @param apiKey - ToolPlex API key
+   * @param sessionResumeHistory - Optional session history for resuming
+   * @returns Connected MCP session
+   */
+  createTransport(
+    apiKey: string,
+    sessionResumeHistory?: string,
+  ): Promise<MCPSession>;
+
+  /**
+   * Close a transport
+   */
+  closeTransport(session: MCPSession): Promise<void>;
+}
+
+/**
+ * MCP Client configuration
+ */
+export interface MCPClientConfig {
+  transportFactory: TransportFactory;
+  logger?: {
+    debug: (message: string, meta?: any) => void;
+    info: (message: string, meta?: any) => void;
+    warn: (message: string, meta?: any) => void;
+    error: (message: string, meta?: any) => void;
+  };
+  /**
+   * Optional image handler for processing image results
+   */
+  imageHandler?: {
+    initialize(userId: string): Promise<void>;
+    processToolResult(
+      result: any,
+    ): Promise<{ content: any[]; savedImages?: any[] }>;
+  };
+  /**
+   * Optional function to get current user ID (for image handling)
+   */
+  getCurrentUserId?: () => string | null;
+}

package/src/providers/index.ts

@@ -0,0 +1,177 @@
+/**
+ * @toolplex/ai-engine - Provider Factory
+ *
+ * Central provider management for the AI engine.
+ * Handles instantiation of both built-in AI SDK providers and custom providers.
+ */
+
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { createToolPlex } from "./toolplex.js";
+import type { AIProvider, ProviderCredentials } from "../types/index.js";
+import type { LoggerAdapter } from "../adapters/types.js";
+
+export { toolplexUsageMap } from "./toolplex.js";
+
+export interface GetProviderOptions {
+  logger?: LoggerAdapter;
+  clientVersion?: string;
+}
+
+/**
+ * Get provider instance by ID
+ *
+ * @param providerId - Provider identifier (e.g., 'toolplex', 'openai', 'anthropic')
+ * @param credentials - API keys and credentials
+ * @param options - Optional logger and client version
+ * @returns Provider instance
+ */
+export function getProvider(
+  providerId: string,
+  credentials: ProviderCredentials,
+  options?: GetProviderOptions,
+): AIProvider {
+  switch (providerId.toLowerCase()) {
+    case "toolplex": {
+      if (!credentials.toolplexApiKey) {
+        throw new Error("ToolPlex API key is required");
+      }
+      const toolplexProvider = createToolPlex({
+        apiKey: credentials.toolplexApiKey,
+        baseURL: "https://api.toolplex.ai",
+        clientVersion: options?.clientVersion,
+        logger: options?.logger,
+      });
+      return {
+        id: "toolplex",
+        chat: (modelId: string) => toolplexProvider(modelId),
+      };
+    }
+
+    case "openai": {
+      if (!credentials.openaiKey) {
+        throw new Error("OpenAI API key is required");
+      }
+      const openaiProvider = createOpenAI({ apiKey: credentials.openaiKey });
+      return {
+        id: "openai",
+        chat: (modelId: string) => openaiProvider(modelId),
+      };
+    }
+
+    case "anthropic": {
+      if (!credentials.anthropicKey) {
+        throw new Error("Anthropic API key is required");
+      }
+      const anthropicProvider = createAnthropic({
+        apiKey: credentials.anthropicKey,
+      });
+      return {
+        id: "anthropic",
+        chat: (modelId: string) => anthropicProvider(modelId),
+      };
+    }
+
+    case "google": {
+      if (!credentials.googleKey) {
+        throw new Error("Google API key is required");
+      }
+      const googleProvider = createGoogleGenerativeAI({
+        apiKey: credentials.googleKey,
+      });
+      return {
+        id: "google",
+        chat: (modelId: string) => googleProvider(modelId),
+      };
+    }
+
+    case "openrouter": {
+      if (!credentials.openrouterKey) {
+        throw new Error("OpenRouter API key is required");
+      }
+      const openrouterProvider = createOpenRouter({
+        apiKey: credentials.openrouterKey,
+      });
+      return {
+        id: "openrouter",
+        chat: (modelId: string) => openrouterProvider(modelId),
+      };
+    }
+
+    case "deepseek": {
+      if (!credentials.deepseekKey) {
+        throw new Error("DeepSeek API key is required");
+      }
+      // DeepSeek uses OpenAI-compatible API
+      const deepseekProvider = createOpenAI({
+        apiKey: credentials.deepseekKey,
+        baseURL: "https://api.deepseek.com/v1",
+      });
+      return {
+        id: "deepseek",
+        chat: (modelId: string) => deepseekProvider(modelId),
+      };
+    }
+
+    case "moonshot": {
+      if (!credentials.moonshotKey) {
+        throw new Error("Moonshot API key is required");
+      }
+      // Moonshot uses OpenAI-compatible API
+      const moonshotProvider = createOpenAI({
+        apiKey: credentials.moonshotKey,
+        baseURL: "https://api.moonshot.cn/v1",
+      });
+      return {
+        id: "moonshot",
+        chat: (modelId: string) => moonshotProvider(modelId),
+      };
+    }
+
+    default:
+      throw new Error(`Unknown provider: ${providerId}`);
+  }
+}
+
+/**
+ * Get model instance for streaming
+ *
+ * @param modelId - Full model identifier (e.g., 'anthropic/claude-sonnet-4')
+ * @param credentials - API keys and credentials
+ * @param options - Optional logger and client version
+ * @returns Language model instance ready for streamText()
+ */
+export function getModel(
+  modelId: string,
+  credentials: ProviderCredentials,
+  options?: GetProviderOptions,
+) {
+  // Parse model ID format: "provider/model-name"
+  const parts = modelId.split("/");
+  const providerId = parts[0];
+  const actualModelId = parts.slice(1).join("/");
+
+  const provider = getProvider(providerId, credentials, options);
+  return provider.chat(actualModelId);
+}
+
+/**
+ * Check if a provider is available (has required credentials)
+ *
+ * @param providerId - Provider identifier
+ * @param credentials - API keys and credentials
+ * @returns True if provider can be instantiated
+ */
+export function isProviderAvailable(
+  providerId: string,
+  credentials: ProviderCredentials,
+): boolean {
+  try {
+    getProvider(providerId, credentials);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/providers/toolplex.ts

@@ -0,0 +1,217 @@
+/**
+ * @toolplex/ai-engine - ToolPlex Provider
+ *
+ * Custom ToolPlex Provider for Vercel AI SDK.
+ * Wraps the ToolPlex AI API backend (api.toolplex.ai) which proxies OpenRouter
+ * and returns OpenRouter-format SSE streaming responses.
+ *
+ * The backend handles:
+ * - Authentication via ToolPlex API keys (x-api-key header)
+ * - Usage tracking and enforcement
+ * - OpenRouter model access
+ * - Tool call handling
+ */
+
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { LoggerAdapter } from "../adapters/types.js";
+
+export interface ToolPlexConfig {
+  apiKey: string;
+  baseURL?: string;
+  clientVersion?: string;
+  logger?: LoggerAdapter;
+}
+
+/**
+ * Global map to store usage data from DONE events
+ * Key: sessionId, Value: Usage data from backend
+ * This is cleared after being read by the engine
+ */
+export const toolplexUsageMap = new Map<
+  string,
+  {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cost?: number;
+  }
+>();
+
+/**
+ * ToolPlex model factory function type
+ */
+export type ToolPlexModelFactory = (modelId: string) => any;
+
+/**
+ * Create a ToolPlex provider instance
+ *
+ * Uses the specialized OpenRouter SDK provider with custom configuration to work with
+ * the ToolPlex backend API which proxies OpenRouter and returns OpenRouter's SSE format.
+ */
+export function createToolPlex(config: ToolPlexConfig): ToolPlexModelFactory {
+  const baseURL = config.baseURL || "https://api.toolplex.ai";
+  const logger = config.logger;
+
+  // Build headers
+  const headers: Record<string, string> = {
+    "x-api-key": config.apiKey,
+  };
+
+  if (config.clientVersion) {
+    headers["X-Client-Version"] = config.clientVersion;
+  }
+
+  // Create OpenRouter provider with custom configuration for ToolPlex backend
+  const provider = createOpenRouter({
+    apiKey: config.apiKey,
+    baseURL: `${baseURL}/ai`,
+    headers,
+    // Custom fetch to transform requests and intercept DONE events for usage data
+    fetch: async (url, init) => {
+      // Add provider field and session_id to request body
+      if (init?.body && typeof init.body === "string") {
+        try {
+          const body = JSON.parse(init.body);
+
+          // Extract session ID from headers if present
+          let sessionId: string | null = null;
+          if (init?.headers) {
+            if (init.headers instanceof Headers) {
+              sessionId = init.headers.get("x-session-id");
+            } else if (Array.isArray(init.headers)) {
+              const sessionHeader = init.headers.find(
+                ([key]) => key.toLowerCase() === "x-session-id",
+              );
+              sessionId = sessionHeader ? sessionHeader[1] : null;
+            } else {
+              sessionId =
+                (init.headers as Record<string, string>)["x-session-id"] ||
+                null;
+            }
+          }
+
+          logger?.debug("ToolPlex provider: Transforming request", {
+            hasSessionId: !!sessionId,
+            sessionId: sessionId ? sessionId.substring(0, 8) + "..." : null,
+            bodyKeys: Object.keys(body),
+          });
+
+          const toolplexBody = {
+            ...body,
+            provider: "openrouter",
+            ...(sessionId && { session_id: sessionId }),
+          };
+
+          init = {
+            ...init,
+            body: JSON.stringify(toolplexBody),
+          };
+        } catch (error) {
+          logger?.error("Failed to transform ToolPlex request", { error });
+        }
+      }
+
+      const response = await fetch(url, init);
+
+      // Intercept SSE stream to capture usage from DONE event
+      if (
+        response.body &&
+        response.headers.get("content-type")?.includes("text/event-stream")
+      ) {
+        const originalBody = response.body;
+        const reader = originalBody.getReader();
+        const decoder = new TextDecoder();
+
+        // Create a new readable stream that intercepts SSE events
+        const transformedStream = new ReadableStream({
+          async start(controller) {
+            let buffer = "";
+
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+
+                if (done) {
+                  controller.close();
+                  break;
+                }
+
+                // Decode chunk and add to buffer
+                buffer += decoder.decode(value, { stream: true });
+
+                // Process complete SSE events (separated by \n\n)
+                const events = buffer.split("\n\n");
+                buffer = events.pop() || ""; // Keep incomplete event in buffer
+
+                // Filter out DONE events and track usage
+                const filteredEvents: string[] = [];
+
+                for (const event of events) {
+                  if (event.trim()) {
+                    // Parse SSE event (format: "data: {...}")
+                    const match = event.match(/^data: (.+)$/m);
+                    if (match) {
+                      try {
+                        const data = JSON.parse(match[1]);
+
+                        // Check for DONE event with usage data
+                        if (data.done === true && data.usage) {
+                          const sessionId = (init?.headers as any)?.[
+                            "x-session-id"
+                          ];
+
+                          if (sessionId) {
+                            toolplexUsageMap.set(sessionId, {
+                              prompt_tokens: data.usage.prompt_tokens || 0,
+                              completion_tokens:
+                                data.usage.completion_tokens || 0,
+                              total_tokens: data.usage.total_tokens || 0,
+                              cost: data.usage.cost,
+                            });
+                          }
+
+                          // Skip this event to prevent AI SDK from seeing invalid chunk format
+                          continue;
+                        }
+                      } catch {
+                        // Not JSON or different format - keep the event
+                      }
+                    }
+                  }
+
+                  // Keep this event
+                  filteredEvents.push(event);
+                }
+
+                // Reconstruct the filtered stream
+                if (filteredEvents.length > 0) {
+                  const filteredBuffer = filteredEvents.join("\n\n") + "\n\n";
+                  controller.enqueue(Buffer.from(filteredBuffer, "utf8"));
+                }
+              }
+            } catch (error) {
+              logger?.error("Error intercepting ToolPlex SSE stream", {
+                error,
+              });
+              controller.error(error);
+            }
+          },
+        });
+
+        // Return a new response with the transformed stream
+        return new Response(transformedStream, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        });
+      }
+
+      return response;
+    },
+  });
+
+  // Return a function that creates model instances
+  return function (modelId: string) {
+    return provider.chat(modelId);
+  };
+}