chat-agent-toolkit 1.2.367 → 1.2.368

package/src/mastra/model-routing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Mastra Model Routing
+ *
+ * Multi-provider model routing with strategy selection:
+ * cost-optimized, latency-optimized, capability-based, or round-robin.
+ */
+import { Agent } from "@mastra/core/agent";
+export type RoutingStrategy = "cost" | "latency" | "capability" | "round-robin";
+export interface ModelRouterConfig {
+    providers: Array<{
+        id: string;
+        model: any;
+        costPer1kTokens?: number;
+        avgLatencyMs?: number;
+        capabilities?: string[];
+        priority?: number;
+    }>;
+    strategy: RoutingStrategy;
+    fallbackProviderId?: string;
+}
+/**
+ * Model router that selects providers based on configurable strategies.
+ *
+ * @example
+ * ```ts
+ * import { createModelRouter } from "chat-agent-toolkit/mastra";
+ * import { openai } from "@ai-sdk/openai";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ *
+ * const router = createModelRouter({
+ *   providers: [
+ *     { id: "openai", model: openai("gpt-4o"), costPer1kTokens: 0.005 },
+ *     { id: "anthropic", model: anthropic("claude-sonnet-4-20250514"), costPer1kTokens: 0.003 },
+ *     { id: "fast", model: openai("gpt-4o-mini"), costPer1kTokens: 0.0002, avgLatencyMs: 200 },
+ *   ],
+ *   strategy: "cost",
+ * });
+ *
+ * const model = router.select(); // cheapest provider
+ * const model2 = router.select({ capabilities: ["vision"] }); // capability match
+ * ```
+ */
+export declare function createModelRouter(config: ModelRouterConfig): {
+    select(options?: {
+        capabilities?: string[];
+        maxCost?: number;
+        maxLatency?: number;
+    }): any;
+    createAgent(agentConfig: {
+        id: string;
+        name: string;
+        instructions: string;
+        tools?: Record<string, any>;
+    }, routingOptions?: {
+        capabilities?: string[];
+        maxCost?: number;
+        maxLatency?: number;
+    }): Agent;
+};
+/**
+ * Load a Mastra-compatible model from a provider string.
+ * Convenience wrapper around Vercel AI SDK provider imports.
+ *
+ * @example
+ * ```ts
+ * const model = await loadMastraModel("openai", "gpt-4o");
+ * const model2 = await loadMastraModel("anthropic", "claude-sonnet-4-20250514");
+ * const model3 = await loadMastraModel("groq", "llama-3.3-70b-versatile");
+ * ```
+ */
+export declare function loadMastraModel(provider: "openai" | "anthropic" | "groq" | "google", modelId: string): Promise<any>;

package/src/mastra/rag.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Mastra RAG (Retrieval-Augmented Generation)
+ *
+ * Document processing, chunking, embedding, and vector-store retrieval.
+ * Uses Vercel AI SDK embeddings with pluggable vector backends.
+ */
+export interface RAGConfig {
+    embeddingModel: any;
+    chunkSize?: number;
+    chunkOverlap?: number;
+    topK?: number;
+}
+export interface RAGDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, any>;
+}
+export interface RAGChunk {
+    id: string;
+    documentId: string;
+    text: string;
+    embedding: number[];
+    metadata?: Record<string, any>;
+}
+export interface RAGRetrievalResult {
+    chunk: RAGChunk;
+    score: number;
+}
+/**
+ * In-memory RAG pipeline with document chunking, embedding, and retrieval.
+ * For production, swap the vector store with Pinecone, Qdrant, or pgvector.
+ *
+ * @example
+ * ```ts
+ * import { MastraRAG } from "chat-agent-toolkit/mastra";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const rag = new MastraRAG({
+ *   embeddingModel: openai.embedding("text-embedding-3-small"),
+ *   chunkSize: 512,
+ *   topK: 5,
+ * });
+ *
+ * await rag.ingest([
+ *   { id: "doc1", content: "Long document text..." },
+ * ]);
+ *
+ * const results = await rag.retrieve("What is the main topic?");
+ * ```
+ */
+export declare class MastraRAG {
+    private config;
+    private chunks;
+    constructor(config: RAGConfig);
+    /**
+     * Split text into overlapping chunks of configured size.
+     */
+    private splitIntoChunks;
+    /**
+     * Ingest documents: chunk, embed, and store.
+     */
+    ingest(documents: RAGDocument[]): Promise<number>;
+    /**
+     * Retrieve relevant chunks for a query using cosine similarity.
+     */
+    retrieve(query: string): Promise<RAGRetrievalResult[]>;
+    /**
+     * Retrieve and format context string for LLM consumption.
+     */
+    getContext(query: string): Promise<string>;
+    /**
+     * Get total chunk count in the store.
+     */
+    get size(): number;
+    /**
+     * Clear all stored chunks.
+     */
+    clear(): void;
+}
+/**
+ * Factory for creating a configured RAG pipeline.
+ */
+export declare function createRAGPipeline(config: RAGConfig): MastraRAG;

package/src/mastra/telemetry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Mastra Telemetry & Instance Factory
+ *
+ * Creates configured Mastra instances with OpenTelemetry-compatible
+ * tracing, logging, and agent registration.
+ */
+import { Mastra } from "@mastra/core";
+export interface TelemetryConfig {
+    serviceName: string;
+    enabled?: boolean;
+    sampling?: number;
+    exporterUrl?: string;
+}
+export interface MastraInstanceConfig {
+    agents?: Record<string, any>;
+    workflows?: Record<string, any>;
+    telemetry?: TelemetryConfig;
+    storage?: any;
+}
+/**
+ * Create a fully configured Mastra instance with agents, workflows,
+ * and telemetry. Central entry point for Mastra framework setup.
+ *
+ * @example
+ * ```ts
+ * import { createMastraInstance } from "chat-agent-toolkit/mastra";
+ *
+ * const mastra = createMastraInstance({
+ *   agents: { assistant, researcher },
+ *   workflows: { researchWorkflow },
+ *   telemetry: {
+ *     serviceName: "my-app",
+ *     enabled: true,
+ *   },
+ * });
+ *
+ * const agent = mastra.getAgent("assistant");
+ * const result = await agent.generate("Hello");
+ * ```
+ */
+export declare function createMastraInstance(config: MastraInstanceConfig): Mastra;

package/src/mastra/workflows.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Mastra Workflow Builder
+ *
+ * Graph-based deterministic workflows with typed steps, chaining,
+ * branching, and parallel execution support.
+ */
+import { z } from "zod";
+export interface WorkflowStepConfig<TInput = any, TOutput = any> {
+    id: string;
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+    execute: (params: {
+        inputData: TInput;
+    }) => Promise<TOutput>;
+}
+/**
+ * Create a typed workflow step.
+ *
+ * @example
+ * ```ts
+ * const fetchStep = createWorkflowStep({
+ *   id: "fetch-sources",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   outputSchema: z.object({ sources: z.array(z.string()) }),
+ *   execute: async ({ inputData }) => {
+ *     const sources = await searchWeb(inputData.query);
+ *     return { sources };
+ *   },
+ * });
+ * ```
+ */
+export declare function createWorkflowStep<TInput, TOutput>(config: WorkflowStepConfig<TInput, TOutput>): import("@mastra/core/workflows").Step<string, unknown, TInput, TOutput, unknown, unknown, import("@mastra/core/workflows").DefaultEngineType, unknown>;
+/**
+ * Create a research workflow: fetch → analyze → summarize.
+ * Pre-built pipeline for common research tasks.
+ *
+ * @example
+ * ```ts
+ * const workflow = createResearchWorkflow({
+ *   fetchFn: async (topic) => fetchSources(topic),
+ *   analyzeFn: async (sources) => analyzeContent(sources),
+ *   summarizeFn: async (analysis) => generateSummary(analysis),
+ * });
+ *
+ * const run = await workflow.createRunAsync();
+ * const result = await run.start({ inputData: { topic: "quantum computing" } });
+ * ```
+ */
+export declare function createResearchWorkflow(handlers: {
+    fetchFn: (topic: string) => Promise<string[]>;
+    analyzeFn: (sources: string[]) => Promise<string>;
+    summarizeFn: (analysis: string) => Promise<string>;
+}): import("@mastra/core/workflows").Workflow<import("@mastra/core/workflows").DefaultEngineType, import("@mastra/core/workflows").Step<string, unknown, unknown, unknown, unknown, unknown, any, unknown>[], "research-workflow", unknown, {
+    topic: string;
+}, {
+    summary: string;
+}, {
+    summary: string;
+}, unknown>;
+/**
+ * Create a RAG workflow: chunk → embed → retrieve → generate.
+ * End-to-end retrieval-augmented generation pipeline.
+ *
+ * @example
+ * ```ts
+ * const workflow = createRAGWorkflow({
+ *   chunkFn: async (doc) => splitIntoChunks(doc),
+ *   embedFn: async (chunks) => embedChunks(chunks),
+ *   retrieveFn: async (query) => findRelevant(query),
+ *   generateFn: async (context, query) => llmGenerate(context, query),
+ * });
+ * ```
+ */
+export declare function createRAGWorkflow(handlers: {
+    chunkFn: (document: string) => Promise<string[]>;
+    embedFn: (chunks: string[]) => Promise<number[][]>;
+    retrieveFn: (query: string) => Promise<string[]>;
+    generateFn: (context: string[], query: string) => Promise<string>;
+}): import("@mastra/core/workflows").Workflow<import("@mastra/core/workflows").DefaultEngineType, import("@mastra/core/workflows").Step<string, unknown, unknown, unknown, unknown, unknown, any, unknown>[], "rag-workflow", unknown, {
+    query: string;
+}, {
+    answer: string;
+}, {
+    answer: string;
+}, unknown>;

package/src/memory/agent-memory-manager.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Memory Agent
+ *
+ * Enhanced Memory Agent with:
+ * - Rate limiting
+ * - Multiple LLM provider support
+ * - Health monitoring
+ * - Conversation management
+ * - Memory analytics
+ */
+import type { IMemoryStorage } from "./storage/storage-interface";
+import type { MemoryType, MemorySearchOptions } from "./types";
+/**
+ * LLM provider interface
+ */
+interface LLMProvider {
+    invoke: (prompt: string) => Promise<{
+        content: string;
+        tokensUsed: number;
+    }>;
+}
+/**
+ * Chat options
+ */
+interface ChatOptions {
+    provider?: string;
+    apiKey?: string;
+    model?: string;
+    temperature?: number;
+    systemPrompt?: string;
+    includeHistory?: boolean;
+    maxMemories?: number;
+    minImportance?: number;
+}
+/**
+ * Chat response
+ */
+interface ChatResponse {
+    content?: string;
+    memoryContext?: string;
+    success: boolean;
+    tokensUsed?: number;
+    responseTime?: number;
+    sessionId?: string;
+    timestamp: string;
+    error?: string;
+}
+/**
+ * Rate limit configuration
+ */
+interface RateLimitConfig {
+    requests: number;
+    windowMs: number;
+}
+/**
+ * Agent options
+ */
+export interface MemoryAgentOptions {
+    memoryOptions?: any;
+    defaultProvider?: string;
+    defaultApiKey?: string;
+    defaultModel?: string;
+    rateLimit?: RateLimitConfig;
+    providers?: Record<string, (apiKey: string, model: string, temperature: number) => LLMProvider>;
+}
+export declare class MemoryAgent {
+    private memory;
+    private defaultProvider;
+    private defaultApiKey?;
+    private defaultModel?;
+    private rateLimiter;
+    private rateLimitConfig;
+    private providers;
+    private sessionId;
+    private conversationHistory;
+    private analytics;
+    private userId;
+    /**
+     * Initialize memory agent
+     */
+    constructor(userId: string, storage: IMemoryStorage, options?: MemoryAgentOptions);
+    /**
+     * Get default LLM providers
+     */
+    private getDefaultProviders;
+    /**
+     * Generate unique session ID
+     */
+    private generateSessionId;
+    /**
+     * Rate limiting check with sliding window
+     */
+    private checkRateLimit;
+    /**
+     * Main chat method with comprehensive error handling
+     */
+    chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Generate LLM response with timeout and error handling
+     */
+    private generateResponse;
+    /**
+     * Build enhanced prompt with context
+     */
+    private buildPrompt;
+    /**
+     * Update analytics
+     */
+    private updateAnalytics;
+    /**
+     * Remember a fact manually
+     */
+    remember(fact: string, importance?: number, category?: MemoryType, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Get memories with filtering
+     */
+    getMemories(query?: string, limit?: number, options?: MemorySearchOptions): Promise<any[]>;
+    /**
+     * Force store summary of current conversation
+     */
+    forceStoreSummary(): Promise<boolean>;
+    /**
+     * Health check for the agent
+     */
+    healthCheck(): Promise<any>;
+    /**
+     * Get analytics and performance metrics
+     */
+    getAnalytics(): any;
+    /**
+     * Reset session and clear conversation history
+     */
+    resetSession(): void;
+}
+export {};

package/src/memory/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Memory Management System
+ *
+ * Intelligent long-term memory for AI agents with persistent storage,
+ * vector-based relevance search, and automatic conversation summarization.
+ * Supports in-memory and Drizzle ORM-backed persistence.
+ *
+ * @module memory
+ * @author ai-research-agent contributors
+ */
+export { MemoryAgent } from "./agent-memory-manager";
+export type { MemoryAgentOptions } from "./agent-memory-manager";
+export { SimpleMemory } from "./storage/in-memory-storage";
+export { DrizzleMemoryStorage, createMemorySchema } from "./storage/drizzle-storage";
+export type { IMemoryStorage } from "./storage/storage-interface";
+export { MEMORY_CONFIG, MEMORY_TYPES, type MemoryType, type MemoryRecord, type Message, type MemorySearchOptions, type MemoryUpdate, type MemoryContextOptions, type MemoryMetrics, type MemoryOptions, type ExtractedFact, } from "./types";
+export { MastraMemoryManager, MastraD1MemoryStorage, MastraKVMemoryStorage, createMastraMemory, } from "./mastra-integration";
+export type { CloudflareEnv, MastraStorageBackend, MastraMemoryConfig, } from "./mastra-integration";

package/src/memory/mastra-integration.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Mastra Memory Integration for Cloudflare Workers
+ *
+ * Integrates Mastra's memory system with Cloudflare Workers environment.
+ * Provides persistent conversation memory using D1, KV, or Durable Objects.
+ *
+ * Features:
+ * - Multi-storage backend support (D1, KV, Durable Objects)
+ * - Thread-based conversation management
+ * - Resource scoping for multi-user scenarios
+ * - Cloudflare Workers optimized (edge-ready)
+ * - Compatible with existing MemoryAgent architecture
+ *
+ * @see https://docs.mastra.ai/core/memory
+ */
+import { Mastra } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import type { D1Database, KVNamespace } from '@cloudflare/workers-types';
+import type { IMemoryStorage } from './storage/storage-interface';
+import type { MemoryRecord, MemoryType, MemorySearchOptions, MemoryUpdate } from './types';
+/**
+ * Cloudflare Workers environment bindings
+ */
+export interface CloudflareEnv {
+    DB?: D1Database;
+    KV?: KVNamespace;
+    OPENAI_API_KEY?: string;
+    ANTHROPIC_API_KEY?: string;
+    GROQ_API_KEY?: string;
+}
+/**
+ * Storage backend types for Mastra memory
+ */
+export type MastraStorageBackend = 'memory' | 'd1' | 'kv';
+/**
+ * Configuration for Mastra memory integration
+ */
+export interface MastraMemoryConfig {
+    /** Storage backend (memory, d1, or kv) */
+    storage: MastraStorageBackend;
+    /** Cloudflare environment bindings */
+    env?: CloudflareEnv;
+    /** D1 table name (for d1 storage) */
+    tableName?: string;
+    /** KV key prefix (for kv storage) */
+    kvPrefix?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * D1-based storage adapter for Mastra Memory
+ * Implements IMemoryStorage using Cloudflare D1
+ */
+export declare class MastraD1MemoryStorage implements IMemoryStorage {
+    private db;
+    private tableName;
+    constructor(db: D1Database, tableName?: string);
+    /**
+     * Initialize D1 schema for Mastra memory
+     */
+    initSchema(): Promise<void>;
+    insertMemory(userId: string, memoryType: MemoryType, content: string, importance: number, metadata?: Record<string, any>): Promise<string>;
+    findMemories(userId: string, query?: string, limit?: number, options?: MemorySearchOptions): Promise<MemoryRecord[]>;
+    findSimilarMemories(userId: string, content: string, limit?: number): Promise<MemoryRecord[]>;
+    updateMemory(id: string, updates: MemoryUpdate): Promise<void>;
+    deleteMemory(id: string): Promise<void>;
+    getMemoryById(id: string): Promise<MemoryRecord | null>;
+    batchUpdateMemories(updates: Array<{
+        id: string;
+        updates: MemoryUpdate;
+    }>): Promise<void>;
+}
+/**
+ * KV-based storage adapter for Mastra Memory
+ * Uses Cloudflare KV for simple key-value storage
+ */
+export declare class MastraKVMemoryStorage implements IMemoryStorage {
+    private kv;
+    private prefix;
+    constructor(kv: KVNamespace, prefix?: string);
+    private getUserKey;
+    private getMemoryKey;
+    insertMemory(userId: string, memoryType: MemoryType, content: string, importance: number, metadata?: Record<string, any>): Promise<string>;
+    findMemories(userId: string, query?: string, limit?: number, options?: MemorySearchOptions): Promise<MemoryRecord[]>;
+    findSimilarMemories(userId: string, content: string, limit?: number): Promise<MemoryRecord[]>;
+    updateMemory(id: string, updates: MemoryUpdate): Promise<void>;
+    deleteMemory(id: string): Promise<void>;
+    getMemoryById(id: string): Promise<MemoryRecord | null>;
+    batchUpdateMemories(updates: Array<{
+        id: string;
+        updates: MemoryUpdate;
+    }>): Promise<void>;
+}
+/**
+ * Mastra Memory Manager for Cloudflare Workers
+ * Wraps Mastra's memory system with Cloudflare-compatible storage
+ */
+export declare class MastraMemoryManager {
+    private mastra;
+    private storage;
+    private config;
+    constructor(config: MastraMemoryConfig);
+    /**
+     * Initialize Mastra instance with memory
+     */
+    initialize(): Promise<Mastra>;
+    /**
+     * Get storage instance (for direct access)
+     */
+    getStorage(): IMemoryStorage;
+    /**
+     * Create an agent with memory
+     */
+    createAgent(config: {
+        id: string;
+        name: string;
+        instructions: string;
+        model: any;
+        tools?: Record<string, any>;
+        userId: string;
+        threadId?: string;
+        resourceId?: string;
+    }): Promise<Agent>;
+    /**
+     * Store a message in memory
+     */
+    storeMessage(userId: string, threadId: string, role: 'user' | 'assistant', content: string, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Recall conversation history
+     */
+    recallConversation(userId: string, threadId: string, limit?: number): Promise<Array<{
+        role: 'user' | 'assistant';
+        content: string;
+        timestamp: Date;
+    }>>;
+    /**
+     * Get relevant context for a query
+     */
+    getRelevantContext(userId: string, query: string, limit?: number): Promise<string>;
+}
+/**
+ * Quick helper to create Mastra memory manager for Cloudflare Workers
+ *
+ * @example
+ * ```ts
+ * const memoryManager = createMastraMemory({
+ *   storage: 'd1',
+ *   env: env, // Cloudflare env bindings
+ * });
+ *
+ * const agent = await memoryManager.createAgent({
+ *   id: 'assistant',
+ *   name: 'AI Assistant',
+ *   instructions: 'Help users with their questions',
+ *   model: openai('gpt-4o'),
+ *   userId: 'user-123',
+ *   threadId: 'conversation-1',
+ * });
+ * ```
+ */
+export declare function createMastraMemory(config: MastraMemoryConfig): MastraMemoryManager;

package/src/memory/storage/drizzle-storage.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Drizzle Storage Adapter
+ *
+ * Implementation of IMemoryStorage using Drizzle ORM
+ */
+import type { IMemoryStorage } from "./storage-interface";
+import type { MemoryRecord, MemoryType, MemorySearchOptions, MemoryUpdate } from "../types";
+/**
+ * The Drizzle table passed to {@link DrizzleMemoryStorage} must expose these
+ * columns (see {@link createMemorySchema} for the expected shape).
+ */
+export interface MemoryTable {
+    id: any;
+    user_id: any;
+    memory_type: any;
+    content: any;
+    importance: any;
+    access_count: any;
+    metadata: any;
+    created_at: any;
+    updated_at: any;
+}
+/**
+ * Drizzle-based storage adapter.
+ *
+ * Pass the Drizzle database instance and the memory table object defined in
+ * your schema (not a table-name string) so queries reference real columns:
+ *
+ * ```ts
+ * import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";
+ * const userMemories = sqliteTable("user_memories", { ... });
+ * const storage = new DrizzleMemoryStorage(db, userMemories);
+ * ```
+ */
+export declare class DrizzleMemoryStorage implements IMemoryStorage {
+    private db;
+    private table;
+    constructor(db: any, table: MemoryTable & Record<string, any>);
+    /**
+     * Insert a new memory record
+     */
+    insertMemory(userId: string, memoryType: MemoryType, content: string, importance: number, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Find memories by user ID and optional filters
+     */
+    findMemories(userId: string, query?: string, limit?: number, options?: MemorySearchOptions): Promise<MemoryRecord[]>;
+    /**
+     * Find similar memories based on content
+     */
+    findSimilarMemories(userId: string, content: string, limit?: number): Promise<MemoryRecord[]>;
+    /**
+     * Update a memory record
+     */
+    updateMemory(id: string, updates: MemoryUpdate): Promise<void>;
+    /**
+     * Delete a memory record
+     */
+    deleteMemory(id: string): Promise<void>;
+    /**
+     * Get memory by ID
+     */
+    getMemoryById(id: string): Promise<MemoryRecord | null>;
+    /**
+     * Batch update memories
+     */
+    batchUpdateMemories(updates: Array<{
+        id: string;
+        updates: MemoryUpdate;
+    }>): Promise<void>;
+}
+/**
+ * Database schema for memory system
+ * This is kept here for reference but should be managed by your migration system
+ */
+export declare function createMemorySchema(db: any): {
+    user_memories: {
+        id: string;
+        user_id: string;
+        memory_type: string;
+        content: string;
+        importance: string;
+        access_count: string;
+        metadata: string;
+        created_at: string;
+        updated_at: string;
+    };
+};