@elizaos/plugin-knowledge 1.0.0-beta.71 → 1.0.0-beta.72

package/dist/{docs-loader-3LDO3WCY.js → docs-loader-G3WS433E.js}

@@ -1,5 +1,5 @@
 // src/docs-loader.ts
-import { logger } from "@elizaos/core";
+import { logger, createUniqueUuid } from "@elizaos/core";
 import * as fs from "fs";
 import * as path from "path";
 function getKnowledgePath() {
@@ -62,7 +62,7 @@ async function loadDocsFromPath(service, agentId, worldId) {
       ].includes(contentType);
       const content = isBinary ? fileBuffer.toString("base64") : fileBuffer.toString("utf-8");
       const knowledgeOptions = {
-        clientDocumentId: `${agentId}-docs-${Date.now()}-${fileName}`,
+        clientDocumentId: createUniqueUuid(agentId + fileName + Date.now(), fileName),
         contentType,
         originalFilename: fileName,
         worldId: worldId || agentId,
@@ -126,4 +126,4 @@ export {
   getKnowledgePath,
   loadDocsFromPath
 };
-//# sourceMappingURL=docs-loader-3LDO3WCY.js.map
+//# sourceMappingURL=docs-loader-G3WS433E.js.map

package/dist/docs-loader-G3WS433E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docs-loader.ts"],"sourcesContent":["import { logger, UUID, createUniqueUuid } from \"@elizaos/core\";\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport { KnowledgeService } from \"./service.ts\";\nimport { AddKnowledgeOptions } from \"./types.ts\";\n\n/**\n * Get the knowledge path from environment or default to ./docs\n */\nexport function getKnowledgePath(): string {\n  const envPath = process.env.KNOWLEDGE_PATH;\n\n  if (envPath) {\n    // Resolve relative paths from current working directory\n    const resolvedPath = path.resolve(envPath);\n\n    if (!fs.existsSync(resolvedPath)) {\n      logger.warn(\n        `Knowledge path from environment variable does not exist: ${resolvedPath}`\n      );\n      logger.warn(\n        \"Please create the directory or update KNOWLEDGE_PATH environment variable\"\n      );\n    }\n\n    return resolvedPath;\n  }\n\n  // Default to docs folder in current working directory\n  const defaultPath = path.join(process.cwd(), \"docs\");\n\n  if (!fs.existsSync(defaultPath)) {\n    logger.info(`Default docs folder does not exist at: ${defaultPath}`);\n    logger.info(\"To use the knowledge plugin, either:\");\n    logger.info('1. Create a \"docs\" folder in your project root');\n    logger.info(\n      \"2. Set KNOWLEDGE_PATH environment variable to your documents folder\"\n    );\n  }\n\n  return defaultPath;\n}\n\n/**\n * Load documents from the knowledge path\n */\nexport async function loadDocsFromPath(\n  service: KnowledgeService,\n  agentId: UUID,\n  worldId?: UUID\n): Promise<{ total: number; successful: number; failed: number }> {\n  const docsPath = getKnowledgePath();\n\n  if (!fs.existsSync(docsPath)) {\n    logger.warn(`Knowledge path does not exist: ${docsPath}`);\n    return { total: 0, successful: 0, failed: 0 };\n  }\n\n  logger.info(`Loading documents from: ${docsPath}`);\n\n  // Get all files recursively\n  const files = getAllFiles(docsPath);\n\n  if (files.length === 0) {\n    logger.info(\"No files found in knowledge path\");\n    return { total: 0, successful: 0, failed: 0 };\n  }\n\n  logger.info(`Found ${files.length} files to process`);\n\n  let successful = 0;\n  let failed = 0;\n\n  for (const filePath of files) {\n    try {\n      const fileName = path.basename(filePath);\n      const fileExt = path.extname(filePath).toLowerCase();\n\n      // Skip hidden files and directories\n      if (fileName.startsWith(\".\")) {\n        continue;\n      }\n\n      // Determine content type\n      const contentType = getContentType(fileExt);\n\n      // Skip unsupported file types\n      if (!contentType) {\n        logger.debug(`Skipping unsupported file type: ${filePath}`);\n        continue;\n      }\n\n      // Read file\n      const fileBuffer = fs.readFileSync(filePath);\n\n      // For binary files, convert to base64\n      const isBinary = [\n        \"application/pdf\",\n        \"application/msword\",\n        \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      ].includes(contentType);\n\n      const content = isBinary\n        ? fileBuffer.toString(\"base64\")\n        : fileBuffer.toString(\"utf-8\");\n\n      // Create knowledge options\n      const knowledgeOptions: AddKnowledgeOptions = {\n        clientDocumentId: createUniqueUuid(agentId + fileName + Date.now(), fileName),\n        contentType,\n        originalFilename: fileName,\n        worldId: worldId || agentId,\n        content,\n      };\n\n      // Process the document\n      logger.debug(`Processing document: ${fileName}`);\n      const result = await service.addKnowledge(knowledgeOptions);\n\n      logger.info(\n        `Successfully processed ${fileName}: ${result.fragmentCount} fragments created`\n      );\n      successful++;\n    } catch (error) {\n      logger.error(`Failed to process file ${filePath}:`, error);\n      failed++;\n    }\n  }\n\n  logger.info(\n    `Document loading complete: ${successful} successful, ${failed} failed out of ${files.length} total`\n  );\n\n  return {\n    total: files.length,\n    successful,\n    failed,\n  };\n}\n\n/**\n * Recursively get all files in a directory\n */\nfunction getAllFiles(dirPath: string, files: string[] = []): string[] {\n  try {\n    const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n\n    for (const entry of entries) {\n      const fullPath = path.join(dirPath, entry.name);\n\n      if (entry.isDirectory()) {\n        // Skip node_modules and other common directories\n        if (\n          ![\"node_modules\", \".git\", \".vscode\", \"dist\", \"build\"].includes(\n            entry.name\n          )\n        ) {\n          getAllFiles(fullPath, files);\n        }\n      } else if (entry.isFile()) {\n        files.push(fullPath);\n      }\n    }\n  } catch (error) {\n    logger.error(`Error reading directory ${dirPath}:`, error);\n  }\n\n  return files;\n}\n\n/**\n * Get content type based on file extension\n */\nfunction getContentType(extension: string): string | null {\n  const contentTypes: Record<string, string> = {\n    \".txt\": \"text/plain\",\n    \".md\": \"text/plain\",\n    \".tson\": \"text/plain\",\n    \".xml\": \"text/plain\",\n    \".csv\": \"text/plain\",\n    \".html\": \"text/html\",\n    \".pdf\": \"application/pdf\",\n    \".doc\": \"application/msword\",\n    \".docx\":\n      \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n  };\n\n  return contentTypes[extension] || null;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,4 +1,130 @@
-import { Plugin } from '@elizaos/core';
+import { UUID, Plugin } from '@elizaos/core';
+import z from 'zod';
+
+declare const ModelConfigSchema: z.ZodObject<{
+    EMBEDDING_PROVIDER: z.ZodEnum<["openai", "google"]>;
+    TEXT_PROVIDER: z.ZodOptional<z.ZodEnum<["openai", "anthropic", "openrouter", "google"]>>;
+    OPENAI_API_KEY: z.ZodOptional<z.ZodString>;
+    ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
+    OPENROUTER_API_KEY: z.ZodOptional<z.ZodString>;
+    GOOGLE_API_KEY: z.ZodOptional<z.ZodString>;
+    OPENAI_BASE_URL: z.ZodOptional<z.ZodString>;
+    ANTHROPIC_BASE_URL: z.ZodOptional<z.ZodString>;
+    OPENROUTER_BASE_URL: z.ZodOptional<z.ZodString>;
+    GOOGLE_BASE_URL: z.ZodOptional<z.ZodString>;
+    TEXT_EMBEDDING_MODEL: z.ZodString;
+    TEXT_MODEL: z.ZodOptional<z.ZodString>;
+    MAX_INPUT_TOKENS: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, number, string | number>;
+    MAX_OUTPUT_TOKENS: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
+    EMBEDDING_DIMENSION: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
+    CTX_KNOWLEDGE_ENABLED: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    MAX_INPUT_TOKENS: number;
+    MAX_OUTPUT_TOKENS: number;
+    CTX_KNOWLEDGE_ENABLED: boolean;
+    EMBEDDING_PROVIDER: "openai" | "google";
+    TEXT_EMBEDDING_MODEL: string;
+    EMBEDDING_DIMENSION: number;
+    TEXT_PROVIDER?: "openai" | "google" | "anthropic" | "openrouter" | undefined;
+    OPENAI_API_KEY?: string | undefined;
+    ANTHROPIC_API_KEY?: string | undefined;
+    OPENROUTER_API_KEY?: string | undefined;
+    GOOGLE_API_KEY?: string | undefined;
+    OPENAI_BASE_URL?: string | undefined;
+    ANTHROPIC_BASE_URL?: string | undefined;
+    OPENROUTER_BASE_URL?: string | undefined;
+    GOOGLE_BASE_URL?: string | undefined;
+    TEXT_MODEL?: string | undefined;
+}, {
+    MAX_INPUT_TOKENS: string | number;
+    EMBEDDING_PROVIDER: "openai" | "google";
+    TEXT_EMBEDDING_MODEL: string;
+    MAX_OUTPUT_TOKENS?: string | number | undefined;
+    CTX_KNOWLEDGE_ENABLED?: boolean | undefined;
+    TEXT_PROVIDER?: "openai" | "google" | "anthropic" | "openrouter" | undefined;
+    OPENAI_API_KEY?: string | undefined;
+    ANTHROPIC_API_KEY?: string | undefined;
+    OPENROUTER_API_KEY?: string | undefined;
+    GOOGLE_API_KEY?: string | undefined;
+    OPENAI_BASE_URL?: string | undefined;
+    ANTHROPIC_BASE_URL?: string | undefined;
+    OPENROUTER_BASE_URL?: string | undefined;
+    GOOGLE_BASE_URL?: string | undefined;
+    TEXT_MODEL?: string | undefined;
+    EMBEDDING_DIMENSION?: string | number | undefined;
+}>;
+type ModelConfig = z.infer<typeof ModelConfigSchema>;
+/**
+ * Interface for provider rate limits
+ */
+interface ProviderRateLimits {
+    maxConcurrentRequests: number;
+    requestsPerMinute: number;
+    tokensPerMinute?: number;
+    provider: string;
+}
+/**
+ * Options for text generation overrides
+ */
+interface TextGenerationOptions {
+    provider?: "anthropic" | "openai" | "openrouter" | "google";
+    modelName?: string;
+    maxTokens?: number;
+    /**
+     * Document to cache for contextual retrieval.
+     * When provided (along with an Anthropic model via OpenRouter), this enables prompt caching.
+     * The document is cached with the provider and subsequent requests will reuse the cached document,
+     * significantly reducing costs for multiple operations on the same document.
+     * Most effective with contextual retrieval for Knowledge applications.
+     */
+    cacheDocument?: string;
+    /**
+     * Options for controlling the cache behavior.
+     * Currently supports { type: 'ephemeral' } which sets up a temporary cache.
+     * Cache expires after approximately 5 minutes with Anthropic models.
+     * This can reduce costs by up to 90% for reads after the initial cache write.
+     */
+    cacheOptions?: {
+        type: "ephemeral";
+    };
+    /**
+     * Whether to automatically detect and enable caching for contextual retrieval.
+     * Default is true for OpenRouter+Anthropic models with document-chunk prompts.
+     * Set to false to disable automatic caching detection.
+     */
+    autoCacheContextualRetrieval?: boolean;
+}
+/**
+ * Options for adding knowledge to the system
+ */
+interface AddKnowledgeOptions {
+    /** Client-provided document ID */
+    clientDocumentId: UUID;
+    /** MIME type of the file */
+    contentType: string;
+    /** Original filename */
+    originalFilename: string;
+    /** World ID for storage */
+    worldId: UUID;
+    /**
+     * Content of the document. Should be:
+     * - Base64 encoded string for binary files (PDFs, DOCXs, etc)
+     * - Plain text for text files
+     */
+    content: string;
+    /** Optional room ID for storage scoping */
+    roomId?: UUID;
+    /** Optional entity ID for storage scoping */
+    entityId?: UUID;
+}
+declare module "@elizaos/core" {
+    interface ServiceTypeRegistry {
+        KNOWLEDGE: "knowledge";
+    }
+}
+declare const KnowledgeServiceType: {
+    KNOWLEDGE: "knowledge";
+};
 
 /**
  * Knowledge Plugin - Main Entry Point
@@ -11,4 +137,4 @@ import { Plugin } from '@elizaos/core';
  */
 declare const knowledgePlugin: Plugin;
 
-export { knowledgePlugin as default, knowledgePlugin };
+export { type AddKnowledgeOptions, KnowledgeServiceType, type ModelConfig, ModelConfigSchema, type ProviderRateLimits, type TextGenerationOptions, knowledgePlugin as default, knowledgePlugin };

package/dist/index.js

@@ -2763,7 +2763,7 @@ var KnowledgeTestSuite = class {
 var tests_default = new KnowledgeTestSuite();
 
 // src/actions.ts
-import { logger as logger5 } from "@elizaos/core";
+import { logger as logger5, createUniqueUuid as createUniqueUuid2 } from "@elizaos/core";
 import * as fs2 from "fs";
 import * as path2 from "path";
 var processKnowledgeAction = {
@@ -2873,7 +2873,7 @@ var processKnowledgeAction = {
         else if ([".txt", ".md", ".tson", ".xml", ".csv"].includes(fileExt))
           contentType = "text/plain";
         const knowledgeOptions = {
-          clientDocumentId: `${runtime.agentId}-${Date.now()}-${fileName}`,
+          clientDocumentId: createUniqueUuid2(runtime.agentId + fileName + Date.now(), fileName),
           contentType,
           originalFilename: fileName,
           worldId: runtime.agentId,
@@ -2900,7 +2900,7 @@ var processKnowledgeAction = {
           return;
         }
         const knowledgeOptions = {
-          clientDocumentId: `${runtime.agentId}-${Date.now()}-text`,
+          clientDocumentId: createUniqueUuid2(runtime.agentId + "text" + Date.now(), "user-knowledge"),
           contentType: "text/plain",
           originalFilename: "user-knowledge.txt",
           worldId: runtime.agentId,
@@ -3089,7 +3089,7 @@ var knowledgePlugin = {
             try {
               const service = runtime.getService(KnowledgeService.serviceType);
               if (service instanceof KnowledgeService) {
-                const { loadDocsFromPath } = await import("./docs-loader-3LDO3WCY.js");
+                const { loadDocsFromPath } = await import("./docs-loader-G3WS433E.js");
                 const result = await loadDocsFromPath(service, runtime.agentId);
                 if (result.successful > 0) {
                   logger6.info(
@@ -3116,6 +3116,8 @@ var knowledgePlugin = {
 };
 var index_default = knowledgePlugin;
 export {
+  KnowledgeServiceType,
+  ModelConfigSchema,
   index_default as default,
   knowledgePlugin
 };