@mastra/core 0.1.27-unstable.1 → 0.2.0-alpha.83

package/README.md

@@ -1,8 +1,178 @@
 # @mastra/core
 
-This is a guide to developing the core package.
+The core foundation of the Mastra framework, providing essential components and interfaces for building AI-powered applications.
 
-### Install Dependencies for Core Package
+## Installation
 
-1. Navigate to the core directory:`cd packages/core`
-2. Install the dependencies:`pnpm install`
+```bash
+npm install @mastra/core
+```
+
+## Overview
+
+`@mastra/core` is the foundational package of the Mastra framework, providing:
+
+- Core abstractions and interfaces
+- AI agent management and execution
+- Integration with multiple AI providers
+- Workflow orchestration
+- Memory and vector store management
+- Telemetry and logging infrastructure
+- Text-to-speech capabilities
+
+For comprehensive documentation, visit our [official documentation](https://mastra.ai/docs).
+
+## Core Components
+
+### Agents (`/agent`)
+
+Agents are autonomous AI entities that can understand instructions, use tools, and complete tasks. They encapsulate LLM interactions and can maintain conversation history, use provided tools, and follow specific behavioral guidelines through instructions.
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+
+const agent = new Agent({
+  name: 'my-agent',
+  instructions: 'Your task-specific instructions',
+  model: {
+    provider: 'openai',
+    model: 'gpt-4',
+  },
+  tools: {}, // Optional tools
+});
+```
+
+[More agent documentation →](https://mastra.ai/docs/reference/agents/overview)
+
+### Embeddings (`/embeddings`)
+
+The embeddings module provides a unified interface for converting text into vector representations across multiple AI providers. These vectors are essential for semantic search, similarity comparisons, and other NLP tasks.
+
+```typescript
+import { embed, EmbeddingOptions } from '@mastra/core';
+
+const embeddings = await embed('text to embed', {
+  provider: 'OPEN_AI',
+  model: 'text-embedding-ada-002',
+});
+```
+
+Supported providers right now are OpenAI, Cohere, Amazon Bedrock, Google AI, Mistral, and Voyage.
+
+[More embeddings documentation →](https://mastra.ai/docs/reference/embeddings/overview)
+
+### Evaluations (`/eval`)
+
+The evaluation system enables quantitative assessment of AI outputs. Create custom metrics to measure specific aspects of AI performance, from response quality to task completion accuracy.
+
+```typescript
+import { Metric, evaluate } from '@mastra/core';
+
+class CustomMetric extends Metric {
+  async measure(input: string, output: string): Promise<MetricResult> {
+    // Your evaluation logic
+    return { score: 0.95 };
+  }
+}
+```
+
+[More evaluations documentation →](https://mastra.ai/docs/reference/eval/overview)
+
+### Memory (`/memory`)
+
+Memory management provides persistent storage and retrieval of AI interactions. It supports different storage backends and enables context-aware conversations and long-term learning.
+
+```typescript
+import { MastraMemory } from '@mastra/core';
+
+const memory = new MastraMemory({
+  // Memory configuration
+});
+```
+
+[More memory documentation →](https://mastra.ai/docs/reference/memory/overview)
+
+### Vector Stores (`/vector`)
+
+Vector stores provide the infrastructure for storing and querying vector embeddings. They support semantic search, similarity matching, and efficient vector operations across different backend implementations.
+
+```typescript
+import { MastraVector } from '@mastra/core';
+
+class CustomVectorStore extends MastraVector {
+  // Vector store implementation
+}
+```
+
+[More vector stores documentation →](https://mastra.ai/docs/reference/vector/overview)
+
+### Workflows (`/workflows`)
+
+Workflows orchestrate complex AI tasks by combining multiple actions into a coherent sequence. They handle state management, error recovery, and can include conditional logic and parallel execution.
+
+```typescript
+import { Workflow } from '@mastra/core';
+
+const workflow = new Workflow({
+  name: 'my-workflow',
+  steps: [
+    // Workflow steps
+  ],
+});
+```
+
+[More workflows documentation →](https://mastra.ai/docs/reference/workflows/overview)
+
+### Tools (`/tools`)
+
+Tools are functions that agents can use to interact with external systems or perform specific tasks. Each tool has a clear description and schema, making it easy for AI to understand and use them effectively.
+
+```typescript
+import { ToolAction } from '@mastra/core';
+
+const tool = new ToolAction({
+  name: 'tool-name',
+  description: 'Tool description',
+  execute: async context => {
+    // Tool implementation
+  },
+});
+```
+
+[More tools documentation →](https://mastra.ai/docs/reference/tools/overview)
+
+### Logger (`/logger`)
+
+The logging system provides structured, leveled logging with multiple transport options. It supports debug information, performance monitoring, and error tracking across your AI applications.
+
+```typescript
+import { createLogger, LogLevel } from '@mastra/core';
+
+const logger = createLogger({
+  name: 'MyApp',
+  level: LogLevel.INFO,
+});
+```
+
+[More logging documentation →](https://mastra.ai/docs/reference/observability/logging)
+
+### Telemetry (`/telemetry`)
+
+Telemetry provides OpenTelemetry integration for comprehensive monitoring of your AI systems. Track latency, success rates, and system health with distributed tracing and metrics collection.
+
+```typescript
+import { Telemetry } from '@mastra/core';
+
+const telemetry = Telemetry.init({
+  serviceName: 'my-service',
+});
+```
+
+[More Telemetry documentation →](https://mastra.ai/docs/reference/observability/telemetry)
+
+## Additional Resources
+
+- [Getting Started Guide](https://mastra.ai/docs/getting-started/installation)
+- [API Reference](https://mastra.ai/docs/reference)
+- [Examples](https://mastra.ai/docs/examples)
+- [Deployment Guide](https://mastra.ai/docs/deployment/overview)

package/dist/action/index.d.ts

@@ -0,0 +1,18 @@
+import 'zod';
+export { I as IAction, aR as IExecutionContext, d as MastraPrimitives } from '../index-CA9EWqaj.js';
+import '../engine-EwEG-4Iv.js';
+import '../index-B9i6dmc0.js';
+import '../telemetry/index.js';
+import '../tts/index.js';
+import '../vector/index.js';
+import 'ai';
+import 'json-schema';
+import '../base.js';
+import '@opentelemetry/api';
+import 'pino';
+import 'stream';
+import '@opentelemetry/sdk-node';
+import '@opentelemetry/sdk-trace-base';
+import '../metric-D2V4CR8D.js';
+import 'sift';
+import '../types-M16hSruO.js';

package/dist/action/index.js

@@ -0,0 +1 @@
+

package/dist/agent/index.d.ts

@@ -1,60 +1,18 @@
-import { UserContent } from 'ai';
-import { Integration } from '../integration';
-import { Logger } from '../logger';
-import { AllTools, ToolApi } from '../tools/types';
-import { LLM } from '../llm';
-import { ModelConfig, StructuredOutput } from '../llm/types';
-export declare class Agent<TTools, TIntegrations extends Integration[] | undefined = undefined, TKeys extends keyof AllTools<TTools, TIntegrations> = keyof AllTools<TTools, TIntegrations>> {
-    name: string;
-    readonly llm: LLM<TTools, TIntegrations, TKeys>;
-    readonly instructions: string;
-    readonly model: ModelConfig;
-    readonly enabledTools: Partial<Record<TKeys, boolean>>;
-    logger: Logger;
-    constructor(config: {
-        name: string;
-        instructions: string;
-        model: ModelConfig;
-        enabledTools?: Partial<Record<TKeys, boolean>>;
-    });
-    /**
-     * Set the concrete tools for the agent
-     * @param tools
-     */
-    __setTools(tools: Record<TKeys, ToolApi>): void;
-    /**
-     * Set the logger for the agent
-     * @param logger
-     */
-    __setLogger(logger: Logger): void;
-    text({ messages, onStepFinish, maxSteps, }: {
-        messages: UserContent[];
-        onStepFinish?: (step: string) => void;
-        maxSteps?: number;
-    }): Promise<import("ai").GenerateTextResult<{}>>;
-    textObject({ messages, structuredOutput, onStepFinish, maxSteps, }: {
-        messages: UserContent[];
-        structuredOutput: StructuredOutput;
-        onStepFinish?: (step: string) => void;
-        maxSteps?: number;
-    }): Promise<import("ai").GenerateObjectResult<{
-        [x: string]: any;
-    }>>;
-    stream({ messages, onStepFinish, onFinish, maxSteps, }: {
-        messages: UserContent[];
-        onStepFinish?: (step: string) => void;
-        onFinish?: (result: string) => Promise<void> | void;
-        maxSteps?: number;
-    }): Promise<import("ai").StreamTextResult<{}>>;
-    streamObject({ messages, structuredOutput, onStepFinish, onFinish, maxSteps, }: {
-        messages: UserContent[];
-        structuredOutput: StructuredOutput;
-        onStepFinish?: (step: string) => void;
-        onFinish?: (result: string) => Promise<void> | void;
-        maxSteps?: number;
-    }): Promise<import("ai").StreamObjectResult<{
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }, never>>;
-}
+import 'ai';
+import 'json-schema';
+import 'zod';
+export { A as Agent } from '../index-CA9EWqaj.js';
+import '../base.js';
+import '../metric-D2V4CR8D.js';
+import '../telemetry/index.js';
+import '@opentelemetry/api';
+import '@opentelemetry/sdk-node';
+import '@opentelemetry/sdk-trace-base';
+import '../index-B9i6dmc0.js';
+import 'pino';
+import 'stream';
+import 'sift';
+import '../types-M16hSruO.js';
+import '../vector/index.js';
+import '../engine-EwEG-4Iv.js';
+import '../tts/index.js';

package/dist/agent/index.js

@@ -0,0 +1,9 @@
+export { Agent } from '../chunk-RPBNMIV7.js';
+import '../chunk-OZZS5Y3C.js';
+import '../chunk-K7KUCZT2.js';
+import '../chunk-6ZVFVYLE.js';
+import '../chunk-LUULSM4U.js';
+import '../chunk-27EL4TRB.js';
+import '../chunk-NLQVQJOD.js';
+import '../chunk-HBTQNIAX.js';
+import '../chunk-AJJZUHB4.js';

package/dist/base.d.ts

@@ -0,0 +1,46 @@
+import * as _opentelemetry_api from '@opentelemetry/api';
+import { R as RegisteredLogger, L as Logger, a as LogLevel } from './index-B9i6dmc0.js';
+import { Telemetry } from './telemetry/index.js';
+import 'pino';
+import 'stream';
+import '@opentelemetry/sdk-node';
+import '@opentelemetry/sdk-trace-base';
+
+declare class MastraBase {
+    component: RegisteredLogger;
+    logger: Logger;
+    name?: string;
+    telemetry?: Telemetry;
+    constructor({ component, name }: {
+        component?: RegisteredLogger;
+        name?: string;
+    });
+    /**
+     * Set the logger for the agent
+     * @param logger
+     */
+    __setLogger(logger: Logger): void;
+    /**
+     * Internal logging helper that formats and sends logs to the configured logger
+     * @param level - Severity level of the log
+     * @param message - Main log message
+     * @param opts - Optional object for the log
+     */
+    log(level: LogLevel, message: string, opts?: Record<string, any>): void;
+    /**
+     * Set the telemetry for the
+     * @param telemetry
+     */
+    __setTelemetry(telemetry: Telemetry): void;
+    /**
+     * Get the telemetry on the vector
+     * @returns telemetry
+     */
+    __getTelemetry(): Telemetry | undefined;
+    get experimental_telemetry(): {
+        tracer: _opentelemetry_api.Tracer;
+        isEnabled: boolean;
+    } | undefined;
+}
+
+export { MastraBase };

package/dist/base.js

@@ -0,0 +1,3 @@
+export { MastraBase } from './chunk-27EL4TRB.js';
+import './chunk-NLQVQJOD.js';
+import './chunk-AJJZUHB4.js';

package/dist/chunk-27EL4TRB.js

@@ -0,0 +1,70 @@
+import { RegisteredLogger, createLogger } from './chunk-NLQVQJOD.js';
+import { __name, __publicField } from './chunk-AJJZUHB4.js';
+
+// src/base.ts
+var _MastraBase = class _MastraBase {
+  constructor({ component, name }) {
+    __publicField(this, "component", RegisteredLogger.LLM);
+    __publicField(this, "logger");
+    __publicField(this, "name");
+    __publicField(this, "telemetry");
+    this.component = component || RegisteredLogger.LLM;
+    this.name = name;
+    this.logger = createLogger({
+      name: `${this.component} - ${this.name}`
+    });
+  }
+  /**
+  * Set the logger for the agent
+  * @param logger
+  */
+  __setLogger(logger) {
+    this.logger = logger;
+    this.logger.debug(`Logger updated for ${this.component}:${this.name}`);
+  }
+  /**
+  * Internal logging helper that formats and sends logs to the configured logger
+  * @param level - Severity level of the log
+  * @param message - Main log message
+  * @param opts - Optional object for the log
+  */
+  log(level, message, opts) {
+    if (!this.logger) return;
+    const logMessage = {
+      type: this.component,
+      message,
+      destinationPath: this.name ? `${this.component}/${this.name}` : this.component,
+      ...opts || {}
+    };
+    const logMethod = level.toLowerCase();
+    this.logger[logMethod]?.(logMessage);
+  }
+  /**
+  * Set the telemetry for the
+  * @param telemetry
+  */
+  __setTelemetry(telemetry) {
+    this.telemetry = telemetry;
+    this.logger.debug(`Telemetry updated for ${this.component} ${this.telemetry.tracer}`);
+  }
+  /**
+  * Get the telemetry on the vector
+  * @returns telemetry
+  */
+  __getTelemetry() {
+    return this.telemetry;
+  }
+  /* 
+  get experimental_telemetry config
+  */
+  get experimental_telemetry() {
+    return this.telemetry ? {
+      tracer: this.telemetry.tracer,
+      isEnabled: !!this.telemetry.tracer
+    } : undefined;
+  }
+};
+__name(_MastraBase, "MastraBase");
+var MastraBase = _MastraBase;
+
+export { MastraBase };

package/dist/chunk-42DYOLDV.js

@@ -0,0 +1,96 @@
+import { createTool } from './chunk-VOUPGVRD.js';
+import { __name, __publicField } from './chunk-AJJZUHB4.js';
+import { z } from 'zod';
+
+// src/integration/integration.ts
+var _Integration = class _Integration {
+  constructor() {
+    __publicField(this, "name", "Integration");
+    __publicField(this, "workflows");
+    this.workflows = {};
+  }
+  /**
+  * Workflows
+  */
+  registerWorkflow(name, fn) {
+    if (this.workflows[name]) {
+      throw new Error(`Sync function "${name}" already registered`);
+    }
+    this.workflows[name] = fn;
+  }
+  getWorkflows({ serialized }) {
+    if (serialized) {
+      return Object.entries(this.workflows).reduce((acc, [k, v]) => {
+        return {
+          ...acc,
+          [k]: {
+            name: v.name
+          }
+        };
+      }, {});
+    }
+    return this.workflows;
+  }
+  /**
+  * TOOLS
+  */
+  getStaticTools(_params) {
+    throw new Error("Method not implemented.");
+  }
+  async getTools(_params) {
+    throw new Error("Method not implemented.");
+  }
+  async getApiClient() {
+    throw new Error("Method not implemented");
+  }
+};
+__name(_Integration, "Integration");
+var Integration = _Integration;
+var _OpenAPIToolset = class _OpenAPIToolset {
+  constructor() {
+    __publicField(this, "authType", "API_KEY");
+  }
+  get toolSchemas() {
+    return {};
+  }
+  get toolDocumentations() {
+    return {};
+  }
+  get baseClient() {
+    return {};
+  }
+  async getApiClient() {
+    throw new Error("API not implemented");
+  }
+  _generateIntegrationTools() {
+    const { client, ...clientMethods } = this.baseClient;
+    const schemas = this.toolSchemas;
+    const documentations = this.toolDocumentations;
+    const tools = Object.keys(clientMethods).reduce((acc, key) => {
+      const comment = documentations[key]?.comment;
+      const fallbackComment = `Execute ${key}`;
+      const tool = createTool({
+        id: key,
+        inputSchema: schemas[key] || z.object({}),
+        description: comment || fallbackComment,
+        // documentation: doc || fallbackComment,
+        execute: /* @__PURE__ */ __name(async ({ context }) => {
+          const client2 = await this.getApiClient();
+          const value = client2[key];
+          return value({
+            ...context
+          });
+        }, "execute")
+      });
+      return {
+        ...acc,
+        [key]: tool
+      };
+    }, {});
+    return tools;
+  }
+};
+__name(_OpenAPIToolset, "OpenAPIToolset");
+var OpenAPIToolset = _OpenAPIToolset;
+
+export { Integration, OpenAPIToolset };

package/dist/chunk-5R6DBXQM.js

@@ -0,0 +1,57 @@
+import { MastraBase } from './chunk-27EL4TRB.js';
+import { __name, __publicField } from './chunk-AJJZUHB4.js';
+import dotenv from 'dotenv';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+var _MastraDeployer = class _MastraDeployer extends MastraBase {
+  constructor({ scope, env, projectName }) {
+    super({
+      component: "DEPLOYER",
+      name: "MasterDeployer"
+    });
+    __publicField(this, "scope");
+    __publicField(this, "projectName");
+    __publicField(this, "env");
+    this.scope = scope;
+    this.env = env;
+    this.projectName = projectName;
+  }
+  loadEnvVars() {
+    this.logger.debug("Loading environment variables into context.");
+    this.getEnvFiles().forEach((file) => {
+      const content = readFileSync(file, "utf-8");
+      const config = dotenv.parse(content);
+      this.env = {
+        ...this.env,
+        ...config
+      };
+    });
+  }
+  getEnvFiles() {
+    this.logger.debug("Reading environment variables from .env or .env.production files.");
+    const envFiles = [
+      ".env",
+      ".env.production"
+    ].map((file) => join(process.cwd(), file)).filter((file) => existsSync(file));
+    return envFiles;
+  }
+  parseEnvFile(filePath) {
+    this.logger.debug(`Parsing environment variables file: ${filePath}`);
+    const content = readFileSync(filePath, "utf-8");
+    return content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).filter((line) => line.includes("="));
+  }
+  writeFiles({ dir }) {
+    this.logger.debug(`Writing files to ${dir}`);
+  }
+  writeIndex({ dir }) {
+    this.logger.debug(`Writing index file to ${dir}`);
+  }
+  async deploy({ dir, siteId }) {
+    this.logger.debug(`Deploying with command ${this.scope}...${siteId || ""} to ${dir} ${this.projectName || "mastra-starter"}`);
+  }
+};
+__name(_MastraDeployer, "MastraDeployer");
+var MastraDeployer = _MastraDeployer;
+
+export { MastraDeployer };

package/dist/chunk-6ZVFVYLE.js

@@ -0,0 +1,101 @@
+import { __name } from './chunk-AJJZUHB4.js';
+import { trace, context, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+function hasActiveTelemetry() {
+  try {
+    return !!trace.getTracer("default-tracer");
+  } catch {
+    return false;
+  }
+}
+__name(hasActiveTelemetry, "hasActiveTelemetry");
+function withSpan(options) {
+  return function(_target, propertyKey, descriptor) {
+    if (!descriptor || typeof descriptor === "number") return;
+    const originalMethod = descriptor.value;
+    const methodName = String(propertyKey);
+    descriptor.value = function(...args) {
+      if (options?.skipIfNoTelemetry && !hasActiveTelemetry()) {
+        return originalMethod.apply(this, args);
+      }
+      const tracer = trace.getTracer("default-tracer");
+      let spanName;
+      let spanKind;
+      if (typeof options === "string") {
+        spanName = options;
+      } else if (options) {
+        spanName = options.spanName || methodName;
+        spanKind = options.spanKind;
+      } else {
+        spanName = methodName;
+      }
+      const span = tracer.startSpan(spanName, {
+        kind: spanKind
+      });
+      const ctx = trace.setSpan(context.active(), span);
+      args.forEach((arg, index) => {
+        try {
+          span.setAttribute(`${spanName}.argument.${index}`, JSON.stringify(arg));
+        } catch (e) {
+          span.setAttribute(`${spanName}.argument.${index}`, "[Not Serializable]");
+        }
+      });
+      let result;
+      try {
+        result = context.with(ctx, () => originalMethod.apply(this, args));
+        if (result instanceof Promise) {
+          return result.then((resolvedValue) => {
+            try {
+              span.setAttribute(`${spanName}.result`, JSON.stringify(resolvedValue));
+            } catch (e) {
+              span.setAttribute(`${spanName}.result`, "[Not Serializable]");
+            }
+            return resolvedValue;
+          }).finally(() => span.end());
+        }
+        try {
+          span.setAttribute(`${spanName}.result`, JSON.stringify(result));
+        } catch (e) {
+          span.setAttribute(`${spanName}.result`, "[Not Serializable]");
+        }
+        return result;
+      } catch (error) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error instanceof Error ? error.message : "Unknown error"
+        });
+        if (error instanceof Error) {
+          span.recordException(error);
+        }
+        throw error;
+      } finally {
+        if (!(result instanceof Promise)) {
+          span.end();
+        }
+      }
+    };
+    return descriptor;
+  };
+}
+__name(withSpan, "withSpan");
+function InstrumentClass(options) {
+  return function(target) {
+    const methods = Object.getOwnPropertyNames(target.prototype);
+    methods.forEach((method) => {
+      if (options?.excludeMethods?.includes(method) || method === "constructor") return;
+      if (options?.methodFilter && !options.methodFilter(method)) return;
+      const descriptor = Object.getOwnPropertyDescriptor(target.prototype, method);
+      if (descriptor && typeof descriptor.value === "function") {
+        Object.defineProperty(target.prototype, method, withSpan({
+          spanName: options?.prefix ? `${options.prefix}.${method}` : method,
+          skipIfNoTelemetry: true,
+          spanKind: options?.spanKind || SpanKind.INTERNAL
+        })(target, method, descriptor));
+      }
+    });
+    return target;
+  };
+}
+__name(InstrumentClass, "InstrumentClass");
+
+export { InstrumentClass, hasActiveTelemetry, withSpan };

package/dist/chunk-AJJZUHB4.js

@@ -0,0 +1,14 @@
+var __defProp = Object.defineProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+export { __name, __privateAdd, __privateGet, __privateMethod, __privateSet, __publicField };