chat-agent-toolkit 1.2.49 → 1.2.50

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './memory';
 export * from './tools';
 export { AGENT_TOOLS } from './tools';
 export * from './utils';
+export * from './mastra';
 export { configManager, ModelRegistry, getEnv, getModelProvidersUIConfigSection } from './config';
 export type { Config, ConfigModelProvider, MCPServerConfig, UIConfigSections, Model, ModelWithProvider } from './config';
 export { cropProvider, cropProviderAsBlob, cropProviderAsDataURL, getProviderImage, getProviderNames } from './utils/provider-image-cropper';

package/dist/mastra/agents.d.ts

@@ -0,0 +1,72 @@
+import { Agent } from '@mastra/core/agent';
+import { z } from 'zod';
+export interface MastraAgentConfig {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any;
+    tools?: Record<string, any>;
+    maxSteps?: number;
+    memory?: {
+        enabled: boolean;
+        threadId?: string;
+        userId?: string;
+    };
+}
+/**
+ * Create a Mastra agent with full configuration.
+ * Supports tool-calling, multi-step reasoning, and memory.
+ *
+ * @example
+ * ```ts
+ * import { createMastraAgent } from "chat-agent-toolkit/mastra";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const agent = createMastraAgent({
+ *   id: "research-assistant",
+ *   name: "Research Assistant",
+ *   instructions: "Help users research topics thoroughly.",
+ *   model: openai("gpt-4o"),
+ *   tools: { webSearch, extractPage },
+ * });
+ *
+ * const result = await agent.generate("What is RAG?");
+ * ```
+ */
+export declare function createMastraAgent(config: MastraAgentConfig): Agent;
+/**
+ * Create a Mastra agent with inline tool definitions using Zod schemas.
+ * Convenience wrapper for quick prototyping.
+ *
+ * @example
+ * ```ts
+ * const agent = createToolAgent({
+ *   id: "calculator",
+ *   name: "Calculator",
+ *   instructions: "Perform math operations.",
+ *   model: openai("gpt-4o"),
+ *   toolDefs: [{
+ *     id: "add",
+ *     description: "Add two numbers",
+ *     inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *     outputSchema: z.object({ result: z.number() }),
+ *     execute: async ({ context }) => ({ result: context.a + context.b }),
+ *   }],
+ * });
+ * ```
+ */
+export declare function createToolAgent(config: {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any;
+    toolDefs: Array<{
+        id: string;
+        description: string;
+        inputSchema: z.ZodType;
+        outputSchema: z.ZodType;
+        execute: (params: {
+            context: any;
+        }) => Promise<any>;
+    }>;
+}): Agent;

package/dist/mastra/evals.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Mastra Evals
+ *
+ * Scorer-based evaluation functions for LLM outputs.
+ * Assess factuality, relevance, coherence, and safety.
+ */
+export interface EvalResult {
+    score: number;
+    reason: string;
+}
+export interface EvalSuiteResult {
+    overall: number;
+    results: Record<string, EvalResult>;
+}
+/**
+ * Evaluate factuality/groundedness of a response.
+ * Checks whether the output references sources or evidence.
+ *
+ * @example
+ * ```ts
+ * const result = await factualityEval(
+ *   "The earth orbits the sun (source: NASA).",
+ *   "What does the earth orbit?"
+ * );
+ * // { score: 0.9, reason: "Response includes source attribution." }
+ * ```
+ */
+export declare function factualityEval(output: string, _query?: string, sources?: string[]): Promise<EvalResult>;
+/**
+ * Evaluate relevance of a response to the query.
+ * Uses keyword overlap and length heuristics.
+ */
+export declare function relevanceEval(output: string, query: string): Promise<EvalResult>;
+/**
+ * Evaluate coherence and structure of a response.
+ * Checks sentence structure, paragraph flow, and logical markers.
+ */
+export declare function coherenceEval(output: string): Promise<EvalResult>;
+/**
+ * Evaluate output for toxic or harmful content.
+ * Basic keyword/pattern-based detection.
+ */
+export declare function toxicityEval(output: string): Promise<EvalResult>;
+/**
+ * Run a full evaluation suite against a response.
+ *
+ * @example
+ * ```ts
+ * const results = await runEvalSuite({
+ *   output: agentResponse,
+ *   query: "What is photosynthesis?",
+ *   sources: ["Biology textbook chapter 3"],
+ * });
+ *
+ * console.log(results.overall); // 0.78
+ * console.log(results.results.factuality.score); // 0.85
+ * ```
+ */
+export declare function runEvalSuite(params: {
+    output: string;
+    query?: string;
+    sources?: string[];
+}): Promise<EvalSuiteResult>;

package/dist/mastra/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Mastra Integration Module
+ *
+ * Full-featured Mastra AI framework integration providing agents, workflows,
+ * RAG, evals, telemetry, and model routing. Built on @mastra/core with
+ * Vercel AI SDK compatibility.
+ *
+ * @module mastra
+ */
+export { createMastraAgent, createToolAgent, type MastraAgentConfig } from './agents';
+export { createWorkflowStep, createResearchWorkflow, createRAGWorkflow, type WorkflowStepConfig, } from './workflows';
+export { MastraRAG, createRAGPipeline, type RAGConfig, type RAGDocument, type RAGChunk, type RAGRetrievalResult, } from './rag';
+export { factualityEval, relevanceEval, coherenceEval, toxicityEval, runEvalSuite, type EvalResult, type EvalSuiteResult, } from './evals';
+export { createMastraInstance, type MastraInstanceConfig, type TelemetryConfig, } from './telemetry';
+export { createModelRouter, loadMastraModel, type ModelRouterConfig, type RoutingStrategy, } from './model-routing';

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

@@ -0,0 +1,65 @@
+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/dist/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/dist/mastra/telemetry.d.ts

@@ -0,0 +1,35 @@
+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/dist/mastra/workflows.d.ts

@@ -0,0 +1,79 @@
+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>;