@moss-tools/mastra 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, InferEdge Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,117 @@
+# @moss-tools/mastra
+
+Moss semantic search tools for [Mastra](https://mastra.ai) agents.
+
+Wraps Moss into `createTool()` primitives that drop straight into any Mastra agent. Sub-10ms lookups, no external embedder, no vector database to run.
+
+## Installation
+
+```bash
+npm install @moss-tools/mastra @moss-dev/moss @mastra/core zod
+```
+
+## Prerequisites
+
+- Moss project ID and project key — get them from the [Moss Portal](https://portal.usemoss.dev)
+- Node.js 18+
+
+## Quickstart
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { MossClient } from '@moss-dev/moss';
+import { mossSearchTool } from '@moss-tools/mastra';
+
+const client = new MossClient(
+  process.env.MOSS_PROJECT_ID!,
+  process.env.MOSS_PROJECT_KEY!
+);
+
+// Load the index once at startup for sub-10ms queries
+await client.loadIndex('my-index');
+
+const agent = new Agent({
+  id: 'support-agent',
+  name: 'Knowledge Support Copilot',
+  instructions: 'Use moss_search to find relevant information before answering.',
+  model: 'openai/gpt-4.1-mini',
+  tools: {
+    search: mossSearchTool({ client, indexName: 'my-index' }),
+  },
+});
+
+const response = await agent.generate('What is your refund policy?');
+console.log(response.text);
+```
+
+## Available tools
+
+### `mossSearchTool`
+
+Searches a Moss index and returns ranked documents.
+
+```typescript
+import { mossSearchTool } from '@moss-tools/mastra';
+
+// Pre-bound to an index — LLM only needs to supply { query }
+const searchBound = mossSearchTool({ client, indexName: 'my-index' });
+
+// Dynamic — LLM supplies { indexName, query }
+const searchDynamic = mossSearchTool({ client });
+```
+
+**Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `client` | (required) | `MossClient` instance |
+| `indexName` | — | Pre-bind to an index; when omitted the LLM must provide it |
+| `topK` | `5` | Number of results to return |
+| `alpha` | `0.8` | Search blend: 1.0 = semantic only, 0.0 = keyword only |
+| `id` | `"moss_search"` | Mastra tool ID |
+| `description` | *(auto)* | Tool description shown to the LLM |
+
+### `mossAddDocsTool`
+
+Adds or upserts documents into a Moss index. Useful for agents that learn and store information during a conversation.
+
+```typescript
+import { mossAddDocsTool } from '@moss-tools/mastra';
+
+const addDocs = mossAddDocsTool({ client, indexName: 'my-index' });
+```
+
+**Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `client` | (required) | `MossClient` instance |
+| `indexName` | — | Pre-bind to an index |
+| `id` | `"moss_add_docs"` | Mastra tool ID |
+| `description` | *(auto)* | Tool description shown to the LLM |
+
+## Agent with both tools
+
+```typescript
+const agent = new Agent({
+  id: 'learning-agent',
+  instructions:
+    'You are a support assistant. Search the knowledge base with moss_search. ' +
+    'If you learn something new that should be remembered, store it with moss_add_docs.',
+  model: 'openai/gpt-4.1-mini',
+  tools: {
+    search: mossSearchTool({ client, indexName: 'support-kb' }),
+    addDocs: mossAddDocsTool({ client, indexName: 'support-kb' }),
+  },
+});
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).
+
+## Support
+
+- [Moss Docs](https://docs.moss.dev)
+- [Moss Discord](https://discord.gg/eMXExuafBR)
+- [Mastra Docs](https://mastra.ai/docs)

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import * as _mastra_core_tools from '@mastra/core/tools';
+import { MossClient } from '@moss-dev/moss';
+
+interface MossSearchToolOptions {
+    /** Moss client instance. */
+    client: MossClient;
+    /** Pre-bind to a specific index. When omitted the LLM must supply `indexName`. */
+    indexName?: string;
+    /** Number of results to return (default: 5). */
+    topK?: number;
+    /** Hybrid search blend — 1.0 = semantic only, 0.0 = keyword only (default: 0.8). */
+    alpha?: number;
+    /** Override the Mastra tool `id`. */
+    id?: string;
+    /** Override the tool description shown to the LLM. */
+    description?: string;
+}
+interface MossAddDocsToolOptions {
+    /** Moss client instance. */
+    client: MossClient;
+    /** Pre-bind to a specific index. When omitted the LLM must supply `indexName`. */
+    indexName?: string;
+    /** Override the Mastra tool `id`. */
+    id?: string;
+    /** Override the tool description shown to the LLM. */
+    description?: string;
+}
+/**
+ * Creates a Mastra tool that searches a Moss index.
+ *
+ * @example
+ * ```ts
+ * import { Agent } from '@mastra/core/agent';
+ * import { MossClient } from '@moss-dev/moss';
+ * import { mossSearchTool } from '@moss-tools/mastra';
+ *
+ * const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!);
+ * await client.loadIndex('my-index');
+ *
+ * const agent = new Agent({
+ *   id: 'support-agent',
+ *   instructions: 'Use moss_search to answer questions from the knowledge base.',
+ *   model: 'openai/gpt-4.1-mini',
+ *   tools: { search: mossSearchTool({ client, indexName: 'my-index' }) },
+ * });
+ * ```
+ */
+declare function mossSearchTool(options: MossSearchToolOptions): _mastra_core_tools.Tool<{
+    query: string;
+}, unknown, unknown, unknown, _mastra_core_tools.ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
+/**
+ * Creates a Mastra tool that adds or upserts documents into a Moss index.
+ * Useful for agents that learn and store new information during a conversation.
+ */
+declare function mossAddDocsTool(options: MossAddDocsToolOptions): _mastra_core_tools.Tool<{
+    docs: {
+        id: string;
+        text: string;
+        metadata?: Record<string, string> | undefined;
+    }[];
+}, unknown, unknown, unknown, _mastra_core_tools.ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
+
+export { type MossAddDocsToolOptions, type MossSearchToolOptions, mossAddDocsTool, mossSearchTool };

package/dist/index.js

@@ -0,0 +1,63 @@
+// src/tools.ts
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+var docSchema = z.object({
+  id: z.string().describe("Unique document identifier."),
+  text: z.string().describe("Text content to embed and store."),
+  metadata: z.record(z.string()).optional().describe("Optional key-value metadata.")
+});
+function mossSearchTool(options) {
+  const {
+    client,
+    indexName: boundIndex,
+    topK = 5,
+    alpha = 0.8,
+    id = "moss_search",
+    description
+  } = options;
+  const baseFields = {
+    query: z.string().describe("The semantic search query.")
+  };
+  const inputSchema = boundIndex != null ? z.object(baseFields) : z.object({
+    indexName: z.string().describe("Name of the Moss index to search."),
+    ...baseFields
+  });
+  return createTool({
+    id,
+    description: description ?? "Search the knowledge base using Moss semantic search. Returns the most relevant documents for a given query.",
+    inputSchema,
+    execute: async (input) => {
+      const index = boundIndex ?? input.indexName;
+      const result = await client.query(index, input.query, { topK, alpha });
+      return result.docs.map((doc) => ({
+        text: doc.text,
+        score: doc.score,
+        ...doc.metadata ? { metadata: doc.metadata } : {}
+      }));
+    }
+  });
+}
+function mossAddDocsTool(options) {
+  const { client, indexName: boundIndex, id = "moss_add_docs", description } = options;
+  const baseFields = {
+    docs: z.array(docSchema).min(1).max(50).describe("Documents to add or update in the index (1-50).")
+  };
+  const inputSchema = boundIndex != null ? z.object(baseFields) : z.object({
+    indexName: z.string().describe("Name of the Moss index to add documents to."),
+    ...baseFields
+  });
+  return createTool({
+    id,
+    description: description ?? "Add or update documents in a Moss knowledge base index. Use this to store new information for future retrieval.",
+    inputSchema,
+    execute: async (input) => {
+      const index = boundIndex ?? input.indexName;
+      const result = await client.addDocs(index, input.docs, { upsert: true });
+      return { jobId: result.jobId, docCount: result.docCount };
+    }
+  });
+}
+export {
+  mossAddDocsTool,
+  mossSearchTool
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@moss-tools/mastra",
+  "version": "0.1.0",
+  "description": "Moss semantic search tools for Mastra agents",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mastra",
+    "moss",
+    "semantic-search",
+    "rag",
+    "ai-agent",
+    "inferedge"
+  ],
+  "author": "InferEdge Inc.",
+  "license": "BSD-2-Clause",
+  "peerDependencies": {
+    "@mastra/core": ">=1.0.0",
+    "@moss-dev/moss": "^1.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@mastra/core": "1.26.0",
+    "@moss-dev/moss": "1.0.0",
+    "@types/node": "22.13.14",
+    "tsup": "8.4.0",
+    "typescript": "5.8.2",
+    "vitest": "3.1.1",
+    "zod": "3.25.76"
+  }
+}