chat-agent-toolkit 1.2.1

package/src/memory/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Memory System Types and Constants
+ *
+ * Defines interfaces and configuration for the memory management system
+ */
+
+/**
+ * Memory types for categorization
+ */
+export const MEMORY_TYPES = {
+  FACT: "fact",
+  CONVERSATION: "conversation",
+  PREFERENCE: "preference",
+  PERSONAL: "personal",
+  WORK: "work",
+  MANUAL: "manual",
+} as const;
+
+export type MemoryType = (typeof MEMORY_TYPES)[keyof typeof MEMORY_TYPES];
+
+/**
+ * Configuration constants for memory management
+ */
+export const MEMORY_CONFIG = {
+  DEFAULT_MAX_MEMORIES: 100,
+  DEFAULT_SUMMARY_THRESHOLD: 10,
+  DEFAULT_CACHE_EXPIRY: 5 * 60 * 1000, // 5 minutes
+  DEFAULT_BATCH_SIZE: 5,
+  DEFAULT_RELEVANCE_THRESHOLD: 0.3,
+  DEFAULT_IMPORTANCE_RANGE: { min: 0, max: 10 },
+  DEFAULT_RATE_LIMIT: { requests: 10, windowMs: 60000 },
+  DEFAULT_TIMEOUT: 30000, // 30 seconds
+  VECTOR_SEARCH_ENABLED: true,
+  AUTO_SUMMARIZATION_ENABLED: true,
+} as const;
+
+/**
+ * Memory record structure
+ */
+export interface MemoryRecord {
+  id: string;
+  user_id: string;
+  memory_type: MemoryType;
+  content: string;
+  importance: number;
+  access_count: number;
+  metadata?: Record<string, any>;
+  created_at: Date;
+  updated_at: Date;
+  relevance_score?: number;
+}
+
+/**
+ * Message structure for conversation tracking
+ */
+export interface Message {
+  role: "user" | "assistant";
+  content: string;
+  timestamp: number;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Memory search options
+ */
+export interface MemorySearchOptions {
+  minImportance?: number;
+  memoryType?: MemoryType;
+  includeMetadata?: boolean;
+}
+
+/**
+ * Memory update payload
+ */
+export interface MemoryUpdate {
+  importance?: number;
+  access_count?: number | { increment: number };
+  updated_at?: Date;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Memory context options
+ */
+export interface MemoryContextOptions {
+  maxMemories?: number;
+  minImportance?: number;
+}
+
+/**
+ * Performance metrics
+ */
+export interface MemoryMetrics {
+  cacheHits: number;
+  cacheMisses: number;
+  vectorSearches: number;
+  summarizations: number;
+  errors: number;
+  cacheSize: number;
+  recentMessagesCount: number;
+  isProcessing: boolean;
+}
+
+/**
+ * Memory initialization options
+ */
+export interface MemoryOptions {
+  maxMemories?: number;
+  summaryThreshold?: number;
+  cacheExpiry?: number;
+  batchSize?: number;
+  relevanceThreshold?: number;
+  enableVectorSearch?: boolean;
+  enableAutoSummarization?: boolean;
+}
+
+/**
+ * Extracted fact structure
+ */
+export interface ExtractedFact {
+  content: string;
+  importance?: number;
+  category?: MemoryType;
+  metadata?: Record<string, any>;
+}

package/src/models/providers.ts

@@ -0,0 +1,5 @@
+/**
+ * @module agent-toolkit/models/providers
+ * @description Re-export provider UI configuration
+ */
+export { getModelProvidersUIConfigSection } from "../config/provider-ui-config";

package/src/models/registry.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview Re-export ModelRegistry from config directory
+ */
+export { default } from "../config/model-registry";

package/src/models/types.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview Re-export model types from config directory
+ */
+export type { Model, ConfigModelProvider } from "../config/config-types";

package/src/search.ts

@@ -0,0 +1,5 @@
+/**
+ * @module agent-toolkit/search
+ * @description Re-export search tools and handlers
+ */
+export * from "./tools/search/index";

package/src/tools/composio-mastra.ts

@@ -0,0 +1,305 @@
+/**
+ * @fileoverview Composio + Mastra Integration
+ *
+ * Connects Composio's MCP endpoint to Mastra agents.
+ * Composio provides the tools, Mastra provides the agent framework.
+ *
+ * Architecture:
+ * 1. Create Composio Tool Router session → Get MCP URL + headers
+ * 2. Configure Mastra MCPClient with URL + headers
+ * 3. Get tools with mcp.listTools() or mcp.listToolsets()
+ * 4. Create Mastra Agent with tools
+ * 5. Execute agent.generate() with multi-step tool calling
+ *
+ * @see https://composio.dev/toolkits/composio/framework/mastra-ai
+ */
+
+import { Composio } from '@composio/core';
+import { Agent } from '@mastra/core/agent';
+import { MCPClient } from '@mastra/mcp';
+import type { Tool } from '@mastra/core';
+
+/**
+ * Configuration for Composio + Mastra integration
+ */
+export interface ComposioMastraConfig {
+  /** Composio API key */
+  composioApiKey: string;
+  /** User ID for scoping the session */
+  userId: string;
+  /** Toolkits to enable */
+  toolkits: string[];
+  /** Agent configuration */
+  agent: {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any; // Mastra model instance (e.g., openai('gpt-4o'))
+    maxSteps?: number;
+  };
+  /** Whether to require approval before tool execution */
+  requireToolApproval?: boolean;
+}
+
+/**
+ * Composio + Mastra session manager
+ * Handles MCP connection lifecycle and agent creation
+ */
+export class ComposioMastraSession {
+  private composio: Composio;
+  private mcpClient: MCPClient | null = null;
+  private agent: Agent | null = null;
+  private sessionEndpoint: { url: string; headers: Record<string, string> } | null =
+    null;
+
+  constructor(private config: ComposioMastraConfig) {
+    this.composio = new Composio({
+      apiKey: config.composioApiKey,
+    });
+  }
+
+  /**
+   * Create Composio Tool Router session
+   * Returns MCP endpoint URL + auth headers
+   */
+  private async createSession() {
+    if (this.sessionEndpoint) {
+      return this.sessionEndpoint;
+    }
+
+    // Create Composio session with specified toolkits
+    const session = await this.composio.toolsets.create({
+      userId: this.config.userId,
+      toolkits: this.config.toolkits,
+    });
+
+    this.sessionEndpoint = {
+      url: session.mcp.url,
+      headers: {
+        'x-api-key': this.config.composioApiKey,
+        ...session.mcp.headers,
+      },
+    };
+
+    return this.sessionEndpoint;
+  }
+
+  /**
+   * Get or create Mastra MCP client
+   * Connects to Composio's MCP endpoint via HTTP
+   */
+  async getMCPClient(): Promise<MCPClient> {
+    if (this.mcpClient) {
+      return this.mcpClient;
+    }
+
+    const endpoint = await this.createSession();
+
+    // Create Mastra MCP client
+    this.mcpClient = new MCPClient({
+      id: `composio-${this.config.userId}`,
+      servers: {
+        composio: {
+          url: new URL(endpoint.url),
+          requestInit: {
+            headers: endpoint.headers,
+          },
+        },
+      },
+    });
+
+    return this.mcpClient;
+  }
+
+  /**
+   * Get tools from Composio MCP
+   * Use for static agent setup (same tools for all requests)
+   */
+  async getTools(): Promise<Record<string, Tool>> {
+    const mcp = await this.getMCPClient();
+    return await mcp.listTools();
+  }
+
+  /**
+   * Get toolsets from Composio MCP
+   * Use for dynamic per-request tool configuration
+   */
+  async getToolsets() {
+    const mcp = await this.getMCPClient();
+    return await mcp.listToolsets();
+  }
+
+  /**
+   * Create or get Mastra agent with Composio tools
+   * Agent is cached and reused across generate() calls
+   */
+  async getAgent(): Promise<Agent> {
+    if (this.agent) {
+      return this.agent;
+    }
+
+    const tools = await this.getTools();
+
+    this.agent = new Agent({
+      id: this.config.agent.id,
+      name: this.config.agent.name,
+      instructions: this.config.agent.instructions,
+      model: this.config.agent.model,
+      tools,
+    });
+
+    return this.agent;
+  }
+
+  /**
+   * Execute agent with a prompt
+   * Handles multi-step tool calling automatically
+   *
+   * @param prompt - User prompt
+   * @param options - Generation options
+   * @returns Agent response with text and tool calls
+   */
+  async generate(
+    prompt: string,
+    options?: {
+      maxSteps?: number;
+      context?: Record<string, any>;
+    }
+  ) {
+    const agent = await this.getAgent();
+
+    return await agent.generate(prompt, {
+      maxSteps: options?.maxSteps || this.config.agent.maxSteps || 5,
+      ...(options?.context && { context: options.context }),
+    });
+  }
+
+  /**
+   * Clean up MCP connection and agent
+   * Call when done with the session
+   */
+  async cleanup() {
+    if (this.mcpClient) {
+      await this.mcpClient.disconnect();
+      this.mcpClient = null;
+    }
+    this.agent = null;
+    this.sessionEndpoint = null;
+  }
+}
+
+/**
+ * Quick helper to create a Composio + Mastra agent
+ * For one-off usage without session management
+ *
+ * @example
+ * ```ts
+ * const result = await createComposioMastraAgent({
+ *   composioApiKey: process.env.COMPOSIO_API_KEY!,
+ *   userId: 'user-123',
+ *   toolkits: ['GMAIL', 'SLACK'],
+ *   agent: {
+ *     id: 'email-agent',
+ *     name: 'Email Assistant',
+ *     instructions: 'Help with email tasks',
+ *     model: openai('gpt-4o'),
+ *   },
+ * }).generate('Check my unread emails');
+ * ```
+ */
+export async function createComposioMastraAgent(config: ComposioMastraConfig) {
+  const session = new ComposioMastraSession(config);
+  await session.getAgent(); // Initialize
+  return session;
+}
+
+/**
+ * Create Mastra agent with dynamic per-request toolsets
+ * Better for multi-user scenarios where tools vary per request
+ *
+ * @example
+ * ```ts
+ * const agent = await createDynamicComposioAgent({
+ *   composioApiKey: process.env.COMPOSIO_API_KEY!,
+ *   agent: {
+ *     id: 'dynamic-agent',
+ *     name: 'Dynamic Assistant',
+ *     instructions: 'Use available tools',
+ *     model: openai('gpt-4o'),
+ *   },
+ * });
+ *
+ * // Each request can have different userId/toolkits
+ * const result = await agent.generate({
+ *   userId: 'user-123',
+ *   toolkits: ['GMAIL'],
+ *   prompt: 'Check emails',
+ * });
+ * ```
+ */
+export async function createDynamicComposioAgent(config: {
+  composioApiKey: string;
+  agent: {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any;
+    maxSteps?: number;
+  };
+}) {
+  const composio = new Composio({
+    apiKey: config.composioApiKey,
+  });
+
+  return {
+    async generate(params: {
+      userId: string;
+      toolkits: string[];
+      prompt: string;
+      maxSteps?: number;
+    }) {
+      // Create session for this user/toolkits
+      const session = await composio.toolsets.create({
+        userId: params.userId,
+        toolkits: params.toolkits,
+      });
+
+      // Connect MCP client
+      const mcp = new MCPClient({
+        id: `composio-${params.userId}`,
+        servers: {
+          composio: {
+            url: new URL(session.mcp.url),
+            requestInit: {
+              headers: {
+                'x-api-key': config.composioApiKey,
+                ...session.mcp.headers,
+              },
+            },
+          },
+        },
+      });
+
+      try {
+        // Get toolsets for this request
+        const toolsets = await mcp.listToolsets();
+
+        // Create agent with dynamic toolsets
+        const agent = new Agent({
+          id: config.agent.id,
+          name: config.agent.name,
+          instructions: config.agent.instructions,
+          model: config.agent.model,
+          toolsets,
+        });
+
+        // Execute
+        return await agent.generate(params.prompt, {
+          maxSteps: params.maxSteps || config.agent.maxSteps || 5,
+        });
+      } finally {
+        await mcp.disconnect();
+      }
+    },
+  };
+}

package/src/tools/composio-mcp.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Composio MCP Integration for AI SDK v5
+ *
+ * Composio provides dynamic MCP endpoints through sessions/Tool Router.
+ * This module creates MCP clients connected to Composio's HTTP endpoints,
+ * fetches available tools, and passes them to AI SDK models.
+ *
+ * Architecture:
+ * 1. Create Composio session → Get MCP URL + headers
+ * 2. Connect with createMCPClient (HTTP transport)
+ * 3. Fetch tools with client.tools()
+ * 4. Pass to streamText/generateText
+ *
+ * @see https://composio.dev/toolkits/ai_ml_api/framework/ai-sdk
+ * @see https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools
+ */
+
+import { Composio } from '@composio/core';
+import { createMCPClient } from '@ai-sdk/mcp';
+import type { MCPClient } from '@ai-sdk/mcp';
+
+/**
+ * Configuration for Composio MCP session
+ */
+export interface ComposioMCPConfig {
+  /** Composio API key */
+  apiKey: string;
+  /** User ID to scope the session */
+  userId: string;
+  /** Toolkits to enable (e.g., ['GMAIL', 'NOTION', 'SLACK']) */
+  toolkits: string[];
+  /** Optional: Additional MCP headers (e.g., x-api-key if org requires it) */
+  additionalHeaders?: Record<string, string>;
+}
+
+/**
+ * Composio MCP session wrapper
+ * Manages the lifecycle of MCP client connections to Composio
+ */
+export class ComposioMCPSession {
+  private composio: Composio;
+  private client: MCPClient | null = null;
+  private mcpEndpoint: { url: string; headers: Record<string, string> } | null = null;
+
+  constructor(private config: ComposioMCPConfig) {
+    this.composio = new Composio({
+      apiKey: config.apiKey,
+    });
+  }
+
+  /**
+   * Create Composio Tool Router session and get MCP endpoint
+   * This returns the HTTP URL and auth headers for the MCP server
+   */
+  private async getOrCreateEndpoint() {
+    if (this.mcpEndpoint) {
+      return this.mcpEndpoint;
+    }
+
+    // Create dynamic Composio session with specified toolkits
+    const session = await this.composio.toolkits.authorize({
+      userId: this.config.userId,
+      toolkits: this.config.toolkits,
+    });
+
+    // Extract MCP endpoint info
+    this.mcpEndpoint = {
+      url: session.mcp.url,
+      headers: {
+        ...session.mcp.headers,
+        ...this.config.additionalHeaders,
+      },
+    };
+
+    return this.mcpEndpoint;
+  }
+
+  /**
+   * Get or create the MCP client connection
+   * Uses HTTP transport as recommended by Composio
+   */
+  async getClient(): Promise<MCPClient> {
+    if (this.client) {
+      return this.client;
+    }
+
+    const endpoint = await this.getOrCreateEndpoint();
+
+    // Connect to Composio MCP endpoint via HTTP
+    this.client = await createMCPClient({
+      transport: {
+        type: 'http',
+        url: endpoint.url,
+        headers: endpoint.headers,
+        redirect: 'error',
+      },
+    });
+
+    return this.client;
+  }
+
+  /**
+   * Get all available tools from Composio MCP
+   * These tools can be passed directly to streamText/generateText
+   *
+   * @returns Tools object compatible with AI SDK
+   */
+  async getTools() {
+    const client = await this.getClient();
+    return await client.tools();
+  }
+
+  /**
+   * Close the MCP connection
+   * Should be called after request completion or in finally block
+   */
+  async close() {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+  }
+
+  /**
+   * Get list of available toolkits from Composio
+   * Useful for discovering what integrations are available
+   */
+  static async listAvailableToolkits(apiKey: string): Promise<string[]> {
+    const composio = new Composio({ apiKey });
+    const toolkits = await composio.toolkits.list();
+    return toolkits.map((t) => t.name);
+  }
+
+  /**
+   * Check if a user has authenticated a specific toolkit
+   * Returns true if the user can access the toolkit's tools
+   */
+  async isToolkitAuthenticated(toolkit: string): Promise<boolean> {
+    try {
+      const integrations = await this.composio.integrations.list({
+        appName: toolkit,
+      });
+      return integrations.length > 0;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Helper function to create a one-shot Composio MCP session
+ * For quick tool usage without managing session lifecycle
+ *
+ * @example
+ * ```ts
+ * const tools = await getComposioTools({
+ *   apiKey: process.env.COMPOSIO_API_KEY!,
+ *   userId: 'user-123',
+ *   toolkits: ['GMAIL', 'SLACK'],
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Check my unread emails',
+ *   tools,
+ * });
+ * ```
+ */
+export async function getComposioTools(config: ComposioMCPConfig) {
+  const session = new ComposioMCPSession(config);
+  try {
+    return await session.getTools();
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Create a reusable Composio MCP session
+ * Better for multiple requests with the same toolkits
+ *
+ * @example
+ * ```ts
+ * const session = await createComposioSession({
+ *   apiKey: process.env.COMPOSIO_API_KEY!,
+ *   userId: 'user-123',
+ *   toolkits: ['GMAIL', 'NOTION'],
+ * });
+ *
+ * try {
+ *   const tools = await session.getTools();
+ *   const result = await streamText({ model, messages, tools });
+ * } finally {
+ *   await session.close();
+ * }
+ * ```
+ */
+export async function createComposioSession(
+  config: ComposioMCPConfig
+): Promise<ComposioMCPSession> {
+  const session = new ComposioMCPSession(config);
+  // Pre-initialize the connection
+  await session.getClient();
+  return session;
+}

package/src/tools/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Agent Tools Module
+ *
+ * Exports tool definitions for QwkSearch API integration including web search,
+ * content extraction, and AI response generation. Tools are automatically
+ * attached to agents when declared in prompt templates.
+ *
+ * @module tools
+ * @author ai-research-agent contributors
+ */
+
+export { AGENT_TOOLS } from "./qwksearch-api-tools";
+export * from "./search";