@elizaos/ui 2.0.0-alpha.52 → 2.0.0-alpha.521

package/packages/typescript/src/features/knowledge/config.d.ts

@@ -0,0 +1,5 @@
+import type { IAgentRuntime } from "../../types";
+import { type ModelConfig, type ProviderRateLimits } from "./types.ts";
+export declare function validateModelConfig(runtime?: IAgentRuntime): ModelConfig;
+export declare function getProviderRateLimits(runtime?: IAgentRuntime): Promise<ProviderRateLimits>;
+//# sourceMappingURL=config.d.ts.map

package/packages/typescript/src/features/knowledge/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/features/knowledge/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACN,KAAK,WAAW,EAEhB,KAAK,kBAAkB,EACvB,MAAM,YAAY,CAAC;AAiBpB,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW,CA4FxE;AAwDD,wBAAsB,qBAAqB,CAC1C,OAAO,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA8B7B"}

package/packages/typescript/src/features/knowledge/config.js

@@ -0,0 +1,147 @@
+import z from "zod";
+import { ModelConfigSchema, } from "./types.js";
+const parseBooleanEnv = (value) => {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value === "string")
+        return value.toLowerCase() === "true";
+    return false;
+};
+const normalizeEnvValue = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+export function validateModelConfig(runtime) {
+    try {
+        const getSetting = (key, defaultValue) => {
+            if (runtime) {
+                const runtimeValue = runtime.getSetting(key);
+                const normalizedRuntimeValue = typeof runtimeValue === "string"
+                    ? normalizeEnvValue(runtimeValue)
+                    : undefined;
+                return (normalizedRuntimeValue ??
+                    normalizeEnvValue(process.env[key]) ??
+                    defaultValue);
+            }
+            return normalizeEnvValue(process.env[key]) || defaultValue;
+        };
+        const ctxKnowledgeEnabled = parseBooleanEnv(getSetting("CTX_KNOWLEDGE_ENABLED", "false"));
+        const embeddingProvider = getSetting("EMBEDDING_PROVIDER");
+        const localEmbeddingModel = getSetting("LOCAL_EMBEDDING_MODEL");
+        const localEmbeddingDimensions = getSetting("LOCAL_EMBEDDING_DIMENSIONS");
+        const inferredLocalEmbeddings = !embeddingProvider &&
+            Boolean(localEmbeddingModel || localEmbeddingDimensions);
+        const resolvedEmbeddingProvider = embeddingProvider || (inferredLocalEmbeddings ? "local" : undefined);
+        const assumePluginOpenAI = !resolvedEmbeddingProvider;
+        const textEmbeddingModel = getSetting("TEXT_EMBEDDING_MODEL") ||
+            (resolvedEmbeddingProvider === "local"
+                ? localEmbeddingModel
+                : getSetting("OPENAI_EMBEDDING_MODEL")) ||
+            (resolvedEmbeddingProvider === "local"
+                ? "local-embedding"
+                : "text-embedding-3-small");
+        const embeddingDimension = getSetting("EMBEDDING_DIMENSION") ||
+            (resolvedEmbeddingProvider === "local"
+                ? localEmbeddingDimensions
+                : getSetting("OPENAI_EMBEDDING_DIMENSIONS")) ||
+            (resolvedEmbeddingProvider === "local" ? "384" : "1536");
+        const openaiApiKey = getSetting("OPENAI_API_KEY");
+        const config = ModelConfigSchema.parse({
+            EMBEDDING_PROVIDER: resolvedEmbeddingProvider,
+            TEXT_PROVIDER: getSetting("TEXT_PROVIDER"),
+            OPENAI_API_KEY: openaiApiKey,
+            ANTHROPIC_API_KEY: getSetting("ANTHROPIC_API_KEY"),
+            OPENROUTER_API_KEY: getSetting("OPENROUTER_API_KEY"),
+            GOOGLE_API_KEY: getSetting("GOOGLE_API_KEY"),
+            OPENAI_BASE_URL: getSetting("OPENAI_BASE_URL"),
+            ANTHROPIC_BASE_URL: getSetting("ANTHROPIC_BASE_URL"),
+            OPENROUTER_BASE_URL: getSetting("OPENROUTER_BASE_URL"),
+            GOOGLE_BASE_URL: getSetting("GOOGLE_BASE_URL"),
+            TEXT_EMBEDDING_MODEL: textEmbeddingModel,
+            TEXT_MODEL: getSetting("TEXT_MODEL"),
+            MAX_INPUT_TOKENS: getSetting("MAX_INPUT_TOKENS", "4000"),
+            MAX_OUTPUT_TOKENS: getSetting("MAX_OUTPUT_TOKENS", "4096"),
+            EMBEDDING_DIMENSION: embeddingDimension,
+            LOAD_DOCS_ON_STARTUP: parseBooleanEnv(getSetting("LOAD_DOCS_ON_STARTUP")),
+            CTX_KNOWLEDGE_ENABLED: ctxKnowledgeEnabled,
+            RATE_LIMIT_ENABLED: parseBooleanEnv(getSetting("RATE_LIMIT_ENABLED", "true")),
+            MAX_CONCURRENT_REQUESTS: getSetting("MAX_CONCURRENT_REQUESTS", "100"),
+            REQUESTS_PER_MINUTE: getSetting("REQUESTS_PER_MINUTE", "500"),
+            TOKENS_PER_MINUTE: getSetting("TOKENS_PER_MINUTE", "1000000"),
+            BATCH_DELAY_MS: getSetting("BATCH_DELAY_MS", "100"),
+        });
+        validateConfigRequirements(config, assumePluginOpenAI);
+        return config;
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const issues = error.issues
+                .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+                .join(", ");
+            throw new Error(`Model configuration validation failed: ${issues}`);
+        }
+        throw error;
+    }
+}
+function validateConfigRequirements(config, assumePluginOpenAI) {
+    const embeddingProvider = config.EMBEDDING_PROVIDER;
+    if (embeddingProvider === "local") {
+        return;
+    }
+    if (embeddingProvider === "openai" && !config.OPENAI_API_KEY) {
+        throw new Error('OPENAI_API_KEY is required when EMBEDDING_PROVIDER is set to "openai"');
+    }
+    if (embeddingProvider === "google" && !config.GOOGLE_API_KEY) {
+        throw new Error('GOOGLE_API_KEY is required when EMBEDDING_PROVIDER is set to "google"');
+    }
+    if (assumePluginOpenAI &&
+        config.OPENAI_API_KEY &&
+        !config.TEXT_EMBEDDING_MODEL) {
+        throw new Error("OPENAI_EMBEDDING_MODEL is required when using plugin-openai configuration");
+    }
+    if (config.CTX_KNOWLEDGE_ENABLED) {
+        if (config.TEXT_PROVIDER === "openai" && !config.OPENAI_API_KEY) {
+            throw new Error('OPENAI_API_KEY is required when TEXT_PROVIDER is set to "openai"');
+        }
+        if (config.TEXT_PROVIDER === "anthropic" && !config.ANTHROPIC_API_KEY) {
+            throw new Error('ANTHROPIC_API_KEY is required when TEXT_PROVIDER is set to "anthropic"');
+        }
+        if (config.TEXT_PROVIDER === "openrouter" && !config.OPENROUTER_API_KEY) {
+            throw new Error('OPENROUTER_API_KEY is required when TEXT_PROVIDER is set to "openrouter"');
+        }
+        if (config.TEXT_PROVIDER === "google" && !config.GOOGLE_API_KEY) {
+            throw new Error('GOOGLE_API_KEY is required when TEXT_PROVIDER is set to "google"');
+        }
+    }
+}
+export async function getProviderRateLimits(runtime) {
+    const config = validateModelConfig(runtime);
+    const rateLimitEnabled = config.RATE_LIMIT_ENABLED;
+    const maxConcurrentRequests = config.MAX_CONCURRENT_REQUESTS;
+    const requestsPerMinute = config.REQUESTS_PER_MINUTE;
+    const tokensPerMinute = config.TOKENS_PER_MINUTE;
+    const batchDelayMs = config.BATCH_DELAY_MS;
+    const primaryProvider = config.TEXT_PROVIDER || config.EMBEDDING_PROVIDER;
+    if (!rateLimitEnabled) {
+        return {
+            maxConcurrentRequests,
+            requestsPerMinute: Number.MAX_SAFE_INTEGER,
+            tokensPerMinute: Number.MAX_SAFE_INTEGER,
+            provider: primaryProvider || "unlimited",
+            rateLimitEnabled: false,
+            batchDelayMs,
+        };
+    }
+    return {
+        maxConcurrentRequests,
+        requestsPerMinute,
+        tokensPerMinute,
+        provider: primaryProvider || "unlimited",
+        rateLimitEnabled: true,
+        batchDelayMs,
+    };
+}

package/packages/typescript/src/features/knowledge/ctx-embeddings.d.ts

@@ -0,0 +1,53 @@
+export declare const DEFAULT_CHUNK_TOKEN_SIZE = 500;
+export declare const DEFAULT_CHUNK_OVERLAP_TOKENS = 100;
+export declare const DEFAULT_CHARS_PER_TOKEN = 3.5;
+export declare const CONTEXT_TARGETS: {
+    DEFAULT: {
+        MIN_TOKENS: number;
+        MAX_TOKENS: number;
+    };
+    PDF: {
+        MIN_TOKENS: number;
+        MAX_TOKENS: number;
+    };
+    MATH_PDF: {
+        MIN_TOKENS: number;
+        MAX_TOKENS: number;
+    };
+    CODE: {
+        MIN_TOKENS: number;
+        MAX_TOKENS: number;
+    };
+    TECHNICAL: {
+        MIN_TOKENS: number;
+        MAX_TOKENS: number;
+    };
+};
+export declare const SYSTEM_PROMPT = "You are a precision text augmentation tool. Your task is to expand a given text chunk with its direct context from a larger document. You must: 1) Keep the original chunk intact; 2) Add critical context from surrounding text; 3) Never summarize or rephrase the original chunk; 4) Create contextually rich output for improved semantic retrieval.";
+export declare const SYSTEM_PROMPTS: {
+    DEFAULT: string;
+    CODE: string;
+    PDF: string;
+    MATH_PDF: string;
+    TECHNICAL: string;
+};
+export declare const CONTEXTUAL_CHUNK_ENRICHMENT_PROMPT_TEMPLATE = "\n<document>\n{doc_content}\n</document>\n\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. Follow these guidelines:\n\n1. Identify the document's main topic and key information relevant to understanding this chunk\n2. Include 2-3 sentences before the chunk that provide essential context\n3. Include 2-3 sentences after the chunk that complete thoughts or provide resolution\n4. For technical documents, include any definitions or explanations of terms used in the chunk\n5. For narrative content, include character or setting information needed to understand the chunk\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. Do not use phrases like \"this chunk discusses\" - directly present the context\n8. The total length should be between {min_tokens} and {max_tokens} tokens\n9. Format the response as a single coherent paragraph\n\nProvide ONLY the enriched chunk text in your response:";
+export declare const CACHED_CHUNK_PROMPT_TEMPLATE = "\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. Follow these guidelines:\n\n1. Identify the document's main topic and key information relevant to understanding this chunk\n2. Include 2-3 sentences before the chunk that provide essential context\n3. Include 2-3 sentences after the chunk that complete thoughts or provide resolution\n4. For technical documents, include any definitions or explanations of terms used in the chunk\n5. For narrative content, include character or setting information needed to understand the chunk\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. Do not use phrases like \"this chunk discusses\" - directly present the context\n8. The total length should be between {min_tokens} and {max_tokens} tokens\n9. Format the response as a single coherent paragraph\n\nProvide ONLY the enriched chunk text in your response:";
+export declare const CACHED_CODE_CHUNK_PROMPT_TEMPLATE = "\nHere is the chunk of code we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this code chunk by adding critical surrounding context. Follow these guidelines:\n\n1. Preserve ALL code syntax, indentation, and comments exactly as they appear\n2. Include any import statements, function definitions, or class declarations that this code depends on\n3. Add necessary type definitions or interfaces that are referenced in this chunk\n4. Include any crucial comments from elsewhere in the document that explain this code\n5. If there are key variable declarations or initializations earlier in the document, include those\n6. Keep the original chunk COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Do NOT include implementation details for functions that are only called but not defined in this chunk\n\nProvide ONLY the enriched code chunk in your response:";
+export declare const CACHED_MATH_PDF_PROMPT_TEMPLATE = "\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. This document contains mathematical content that requires special handling. Follow these guidelines:\n\n1. Preserve ALL mathematical notation exactly as it appears in the chunk\n2. Include any defining equations, variables, or parameters mentioned earlier in the document that relate to this chunk\n3. Add section/subsection names or figure references if they help situate the chunk\n4. If variables or symbols are defined elsewhere in the document, include these definitions\n5. If mathematical expressions appear corrupted, try to infer their meaning from context\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Format the response as a coherent mathematical explanation\n\nProvide ONLY the enriched chunk text in your response:";
+export declare const CACHED_TECHNICAL_PROMPT_TEMPLATE = "\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. This appears to be technical documentation that requires special handling. Follow these guidelines:\n\n1. Preserve ALL technical terminology, product names, and version numbers exactly as they appear\n2. Include any prerequisite information or requirements mentioned earlier in the document\n3. Add section/subsection headings or navigation path to situate this chunk within the document structure\n4. Include any definitions of technical terms, acronyms, or jargon used in this chunk\n5. If this chunk references specific configurations, include relevant parameter explanations\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Format the response maintaining any hierarchical structure present in the original\n\nProvide ONLY the enriched chunk text in your response:";
+export declare const MATH_PDF_PROMPT_TEMPLATE = "\n<document>\n{doc_content}\n</document>\n\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. This document contains mathematical content that requires special handling. Follow these guidelines:\n\n1. Preserve ALL mathematical notation exactly as it appears in the chunk\n2. Include any defining equations, variables, or parameters mentioned earlier in the document that relate to this chunk\n3. Add section/subsection names or figure references if they help situate the chunk\n4. If variables or symbols are defined elsewhere in the document, include these definitions\n5. If mathematical expressions appear corrupted, try to infer their meaning from context\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Format the response as a coherent mathematical explanation\n\nProvide ONLY the enriched chunk text in your response:";
+export declare const CODE_PROMPT_TEMPLATE = "\n<document>\n{doc_content}\n</document>\n\nHere is the chunk of code we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this code chunk by adding critical surrounding context. Follow these guidelines:\n\n1. Preserve ALL code syntax, indentation, and comments exactly as they appear\n2. Include any import statements, function definitions, or class declarations that this code depends on\n3. Add necessary type definitions or interfaces that are referenced in this chunk\n4. Include any crucial comments from elsewhere in the document that explain this code\n5. If there are key variable declarations or initializations earlier in the document, include those\n6. Keep the original chunk COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Do NOT include implementation details for functions that are only called but not defined in this chunk\n\nProvide ONLY the enriched code chunk in your response:";
+export declare const TECHNICAL_PROMPT_TEMPLATE = "\n<document>\n{doc_content}\n</document>\n\nHere is the chunk we want to situate within the whole document:\n<chunk>\n{chunk_content}\n</chunk>\n\nCreate an enriched version of this chunk by adding critical surrounding context. This appears to be technical documentation that requires special handling. Follow these guidelines:\n\n1. Preserve ALL technical terminology, product names, and version numbers exactly as they appear\n2. Include any prerequisite information or requirements mentioned earlier in the document\n3. Add section/subsection headings or navigation path to situate this chunk within the document structure\n4. Include any definitions of technical terms, acronyms, or jargon used in this chunk\n5. If this chunk references specific configurations, include relevant parameter explanations\n6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response\n7. The total length should be between {min_tokens} and {max_tokens} tokens\n8. Format the response maintaining any hierarchical structure present in the original\n\nProvide ONLY the enriched chunk text in your response:";
+export declare function getContextualizationPrompt(docContent: string, chunkContent: string, minTokens?: number, maxTokens?: number, promptTemplate?: string): string;
+export declare function getCachingContextualizationPrompt(chunkContent: string, contentType?: string, minTokens?: number, maxTokens?: number): {
+    prompt: string;
+    systemPrompt: string;
+};
+export declare function getPromptForMimeType(mimeType: string, docContent: string, chunkContent: string): string;
+export declare function getCachingPromptForMimeType(mimeType: string, chunkContent: string): {
+    prompt: string;
+    systemPrompt: string;
+};
+export declare function getChunkWithContext(chunkContent: string, generatedContext: string): string;
+//# sourceMappingURL=ctx-embeddings.d.ts.map

package/packages/typescript/src/features/knowledge/ctx-embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctx-embeddings.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/features/knowledge/ctx-embeddings.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAqB3B,CAAC;AAEF,eAAO,MAAM,aAAa,6VACiU,CAAC;AAE5V,eAAO,MAAM,cAAc;;;;;;CAa1B,CAAC;AAEF,eAAO,MAAM,2CAA2C,0iCAsBD,CAAC;AAExD,eAAO,MAAM,4BAA4B,ggCAkBc,CAAC;AAExD,eAAO,MAAM,iCAAiC,2+BAiBS,CAAC;AAExD,eAAO,MAAM,+BAA+B,2gCAiBW,CAAC;AAExD,eAAO,MAAM,gCAAgC,gjCAiBU,CAAC;AAExD,eAAO,MAAM,wBAAwB,qjCAqBkB,CAAC;AAExD,eAAO,MAAM,oBAAoB,qhCAqBsB,CAAC;AAExD,eAAO,MAAM,yBAAyB,0lCAqBiB,CAAC;AAExD,wBAAgB,0BAA0B,CACzC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAqC,EAC9C,SAAS,SAAqC,EAC9C,cAAc,SAA8C,GAC1D,MAAM,CAiBR;AAED,wBAAgB,iCAAiC,CAChD,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,SAAS,SAAqC,EAC9C,SAAS,SAAqC,GAC5C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAsD1C;AAED,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GAClB,MAAM,CA0CR;AAED,wBAAgB,2BAA2B,CAC1C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAoC1C;AAiGD,wBAAgB,mBAAmB,CAClC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACtB,MAAM,CAKR"}

package/packages/typescript/src/features/knowledge/ctx-embeddings.js

@@ -0,0 +1,412 @@
+export const DEFAULT_CHUNK_TOKEN_SIZE = 500;
+export const DEFAULT_CHUNK_OVERLAP_TOKENS = 100;
+export const DEFAULT_CHARS_PER_TOKEN = 3.5;
+export const CONTEXT_TARGETS = {
+    DEFAULT: {
+        MIN_TOKENS: 60,
+        MAX_TOKENS: 120,
+    },
+    PDF: {
+        MIN_TOKENS: 80,
+        MAX_TOKENS: 150,
+    },
+    MATH_PDF: {
+        MIN_TOKENS: 100,
+        MAX_TOKENS: 180,
+    },
+    CODE: {
+        MIN_TOKENS: 100,
+        MAX_TOKENS: 200,
+    },
+    TECHNICAL: {
+        MIN_TOKENS: 80,
+        MAX_TOKENS: 160,
+    },
+};
+export const SYSTEM_PROMPT = "You are a precision text augmentation tool. Your task is to expand a given text chunk with its direct context from a larger document. You must: 1) Keep the original chunk intact; 2) Add critical context from surrounding text; 3) Never summarize or rephrase the original chunk; 4) Create contextually rich output for improved semantic retrieval.";
+export const SYSTEM_PROMPTS = {
+    DEFAULT: "You are a precision text augmentation tool. Your task is to expand a given text chunk with its direct context from a larger document. You must: 1) Keep the original chunk intact; 2) Add critical context from surrounding text; 3) Never summarize or rephrase the original chunk; 4) Create contextually rich output for improved semantic retrieval.",
+    CODE: "You are a precision code augmentation tool. Your task is to expand a given code chunk with necessary context from the larger codebase. You must: 1) Keep the original code chunk intact with exact syntax and indentation; 2) Add relevant imports, function signatures, or class definitions; 3) Include critical surrounding code context; 4) Create contextually rich output that maintains correct syntax.",
+    PDF: "You are a precision document augmentation tool. Your task is to expand a given PDF text chunk with its direct context from the larger document. You must: 1) Keep the original chunk intact; 2) Add section headings, references, or figure captions; 3) Include text that immediately precedes and follows the chunk; 4) Create contextually rich output that maintains the document's original structure.",
+    MATH_PDF: "You are a precision mathematical content augmentation tool. Your task is to expand a given mathematical text chunk with essential context. You must: 1) Keep original mathematical notations and expressions exactly as they appear; 2) Add relevant definitions, theorems, or equations from elsewhere in the document; 3) Preserve all LaTeX or mathematical formatting; 4) Create contextually rich output for improved mathematical comprehension.",
+    TECHNICAL: "You are a precision technical documentation augmentation tool. Your task is to expand a technical document chunk with critical context. You must: 1) Keep the original chunk intact including all technical terminology; 2) Add relevant configuration examples, parameter definitions, or API references; 3) Include any prerequisite information; 4) Create contextually rich output that maintains technical accuracy.",
+};
+export const CONTEXTUAL_CHUNK_ENRICHMENT_PROMPT_TEMPLATE = `
+<document>
+{doc_content}
+</document>
+
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. Follow these guidelines:
+
+1. Identify the document's main topic and key information relevant to understanding this chunk
+2. Include 2-3 sentences before the chunk that provide essential context
+3. Include 2-3 sentences after the chunk that complete thoughts or provide resolution
+4. For technical documents, include any definitions or explanations of terms used in the chunk
+5. For narrative content, include character or setting information needed to understand the chunk
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. Do not use phrases like "this chunk discusses" - directly present the context
+8. The total length should be between {min_tokens} and {max_tokens} tokens
+9. Format the response as a single coherent paragraph
+
+Provide ONLY the enriched chunk text in your response:`;
+export const CACHED_CHUNK_PROMPT_TEMPLATE = `
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. Follow these guidelines:
+
+1. Identify the document's main topic and key information relevant to understanding this chunk
+2. Include 2-3 sentences before the chunk that provide essential context
+3. Include 2-3 sentences after the chunk that complete thoughts or provide resolution
+4. For technical documents, include any definitions or explanations of terms used in the chunk
+5. For narrative content, include character or setting information needed to understand the chunk
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. Do not use phrases like "this chunk discusses" - directly present the context
+8. The total length should be between {min_tokens} and {max_tokens} tokens
+9. Format the response as a single coherent paragraph
+
+Provide ONLY the enriched chunk text in your response:`;
+export const CACHED_CODE_CHUNK_PROMPT_TEMPLATE = `
+Here is the chunk of code we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this code chunk by adding critical surrounding context. Follow these guidelines:
+
+1. Preserve ALL code syntax, indentation, and comments exactly as they appear
+2. Include any import statements, function definitions, or class declarations that this code depends on
+3. Add necessary type definitions or interfaces that are referenced in this chunk
+4. Include any crucial comments from elsewhere in the document that explain this code
+5. If there are key variable declarations or initializations earlier in the document, include those
+6. Keep the original chunk COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Do NOT include implementation details for functions that are only called but not defined in this chunk
+
+Provide ONLY the enriched code chunk in your response:`;
+export const CACHED_MATH_PDF_PROMPT_TEMPLATE = `
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. This document contains mathematical content that requires special handling. Follow these guidelines:
+
+1. Preserve ALL mathematical notation exactly as it appears in the chunk
+2. Include any defining equations, variables, or parameters mentioned earlier in the document that relate to this chunk
+3. Add section/subsection names or figure references if they help situate the chunk
+4. If variables or symbols are defined elsewhere in the document, include these definitions
+5. If mathematical expressions appear corrupted, try to infer their meaning from context
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Format the response as a coherent mathematical explanation
+
+Provide ONLY the enriched chunk text in your response:`;
+export const CACHED_TECHNICAL_PROMPT_TEMPLATE = `
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. This appears to be technical documentation that requires special handling. Follow these guidelines:
+
+1. Preserve ALL technical terminology, product names, and version numbers exactly as they appear
+2. Include any prerequisite information or requirements mentioned earlier in the document
+3. Add section/subsection headings or navigation path to situate this chunk within the document structure
+4. Include any definitions of technical terms, acronyms, or jargon used in this chunk
+5. If this chunk references specific configurations, include relevant parameter explanations
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Format the response maintaining any hierarchical structure present in the original
+
+Provide ONLY the enriched chunk text in your response:`;
+export const MATH_PDF_PROMPT_TEMPLATE = `
+<document>
+{doc_content}
+</document>
+
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. This document contains mathematical content that requires special handling. Follow these guidelines:
+
+1. Preserve ALL mathematical notation exactly as it appears in the chunk
+2. Include any defining equations, variables, or parameters mentioned earlier in the document that relate to this chunk
+3. Add section/subsection names or figure references if they help situate the chunk
+4. If variables or symbols are defined elsewhere in the document, include these definitions
+5. If mathematical expressions appear corrupted, try to infer their meaning from context
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Format the response as a coherent mathematical explanation
+
+Provide ONLY the enriched chunk text in your response:`;
+export const CODE_PROMPT_TEMPLATE = `
+<document>
+{doc_content}
+</document>
+
+Here is the chunk of code we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this code chunk by adding critical surrounding context. Follow these guidelines:
+
+1. Preserve ALL code syntax, indentation, and comments exactly as they appear
+2. Include any import statements, function definitions, or class declarations that this code depends on
+3. Add necessary type definitions or interfaces that are referenced in this chunk
+4. Include any crucial comments from elsewhere in the document that explain this code
+5. If there are key variable declarations or initializations earlier in the document, include those
+6. Keep the original chunk COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Do NOT include implementation details for functions that are only called but not defined in this chunk
+
+Provide ONLY the enriched code chunk in your response:`;
+export const TECHNICAL_PROMPT_TEMPLATE = `
+<document>
+{doc_content}
+</document>
+
+Here is the chunk we want to situate within the whole document:
+<chunk>
+{chunk_content}
+</chunk>
+
+Create an enriched version of this chunk by adding critical surrounding context. This appears to be technical documentation that requires special handling. Follow these guidelines:
+
+1. Preserve ALL technical terminology, product names, and version numbers exactly as they appear
+2. Include any prerequisite information or requirements mentioned earlier in the document
+3. Add section/subsection headings or navigation path to situate this chunk within the document structure
+4. Include any definitions of technical terms, acronyms, or jargon used in this chunk
+5. If this chunk references specific configurations, include relevant parameter explanations
+6. Keep the original chunk text COMPLETELY INTACT and UNCHANGED in your response
+7. The total length should be between {min_tokens} and {max_tokens} tokens
+8. Format the response maintaining any hierarchical structure present in the original
+
+Provide ONLY the enriched chunk text in your response:`;
+export function getContextualizationPrompt(docContent, chunkContent, minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS, maxTokens = CONTEXT_TARGETS.DEFAULT.MAX_TOKENS, promptTemplate = CONTEXTUAL_CHUNK_ENRICHMENT_PROMPT_TEMPLATE) {
+    if (!docContent || !chunkContent) {
+        return "Error: Document or chunk content missing.";
+    }
+    const chunkTokens = Math.ceil(chunkContent.length / DEFAULT_CHARS_PER_TOKEN);
+    if (chunkTokens > maxTokens * 0.7) {
+        maxTokens = Math.ceil(chunkTokens * 1.3);
+        minTokens = chunkTokens;
+    }
+    return promptTemplate
+        .replace("{doc_content}", docContent)
+        .replace("{chunk_content}", chunkContent)
+        .replace("{min_tokens}", minTokens.toString())
+        .replace("{max_tokens}", maxTokens.toString());
+}
+export function getCachingContextualizationPrompt(chunkContent, contentType, minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS, maxTokens = CONTEXT_TARGETS.DEFAULT.MAX_TOKENS) {
+    if (!chunkContent) {
+        return {
+            prompt: "Error: Chunk content missing.",
+            systemPrompt: SYSTEM_PROMPTS.DEFAULT,
+        };
+    }
+    const chunkTokens = Math.ceil(chunkContent.length / DEFAULT_CHARS_PER_TOKEN);
+    if (chunkTokens > maxTokens * 0.7) {
+        maxTokens = Math.ceil(chunkTokens * 1.3);
+        minTokens = chunkTokens;
+    }
+    let promptTemplate = CACHED_CHUNK_PROMPT_TEMPLATE;
+    let systemPrompt = SYSTEM_PROMPTS.DEFAULT;
+    if (contentType) {
+        if (contentType.includes("javascript") ||
+            contentType.includes("typescript") ||
+            contentType.includes("python") ||
+            contentType.includes("java") ||
+            contentType.includes("c++") ||
+            contentType.includes("code")) {
+            promptTemplate = CACHED_CODE_CHUNK_PROMPT_TEMPLATE;
+            systemPrompt = SYSTEM_PROMPTS.CODE;
+        }
+        else if (contentType.includes("pdf")) {
+            if (containsMathematicalContent(chunkContent)) {
+                promptTemplate = CACHED_MATH_PDF_PROMPT_TEMPLATE;
+                systemPrompt = SYSTEM_PROMPTS.MATH_PDF;
+            }
+            else {
+                systemPrompt = SYSTEM_PROMPTS.PDF;
+            }
+        }
+        else if (contentType.includes("markdown") ||
+            contentType.includes("text/html") ||
+            isTechnicalDocumentation(chunkContent)) {
+            promptTemplate = CACHED_TECHNICAL_PROMPT_TEMPLATE;
+            systemPrompt = SYSTEM_PROMPTS.TECHNICAL;
+        }
+    }
+    const formattedPrompt = promptTemplate
+        .replace("{chunk_content}", chunkContent)
+        .replace("{min_tokens}", minTokens.toString())
+        .replace("{max_tokens}", maxTokens.toString());
+    return {
+        prompt: formattedPrompt,
+        systemPrompt,
+    };
+}
+export function getPromptForMimeType(mimeType, docContent, chunkContent) {
+    let minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS;
+    let maxTokens = CONTEXT_TARGETS.DEFAULT.MAX_TOKENS;
+    let promptTemplate = CONTEXTUAL_CHUNK_ENRICHMENT_PROMPT_TEMPLATE;
+    if (mimeType.includes("pdf")) {
+        if (containsMathematicalContent(docContent)) {
+            minTokens = CONTEXT_TARGETS.MATH_PDF.MIN_TOKENS;
+            maxTokens = CONTEXT_TARGETS.MATH_PDF.MAX_TOKENS;
+            promptTemplate = MATH_PDF_PROMPT_TEMPLATE;
+        }
+        else {
+            minTokens = CONTEXT_TARGETS.PDF.MIN_TOKENS;
+            maxTokens = CONTEXT_TARGETS.PDF.MAX_TOKENS;
+        }
+    }
+    else if (mimeType.includes("javascript") ||
+        mimeType.includes("typescript") ||
+        mimeType.includes("python") ||
+        mimeType.includes("java") ||
+        mimeType.includes("c++") ||
+        mimeType.includes("code")) {
+        minTokens = CONTEXT_TARGETS.CODE.MIN_TOKENS;
+        maxTokens = CONTEXT_TARGETS.CODE.MAX_TOKENS;
+        promptTemplate = CODE_PROMPT_TEMPLATE;
+    }
+    else if (isTechnicalDocumentation(docContent) ||
+        mimeType.includes("markdown") ||
+        mimeType.includes("text/html")) {
+        minTokens = CONTEXT_TARGETS.TECHNICAL.MIN_TOKENS;
+        maxTokens = CONTEXT_TARGETS.TECHNICAL.MAX_TOKENS;
+        promptTemplate = TECHNICAL_PROMPT_TEMPLATE;
+    }
+    return getContextualizationPrompt(docContent, chunkContent, minTokens, maxTokens, promptTemplate);
+}
+export function getCachingPromptForMimeType(mimeType, chunkContent) {
+    let minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS;
+    let maxTokens = CONTEXT_TARGETS.DEFAULT.MAX_TOKENS;
+    if (mimeType.includes("pdf")) {
+        if (containsMathematicalContent(chunkContent)) {
+            minTokens = CONTEXT_TARGETS.MATH_PDF.MIN_TOKENS;
+            maxTokens = CONTEXT_TARGETS.MATH_PDF.MAX_TOKENS;
+        }
+        else {
+            minTokens = CONTEXT_TARGETS.PDF.MIN_TOKENS;
+            maxTokens = CONTEXT_TARGETS.PDF.MAX_TOKENS;
+        }
+    }
+    else if (mimeType.includes("javascript") ||
+        mimeType.includes("typescript") ||
+        mimeType.includes("python") ||
+        mimeType.includes("java") ||
+        mimeType.includes("c++") ||
+        mimeType.includes("code")) {
+        minTokens = CONTEXT_TARGETS.CODE.MIN_TOKENS;
+        maxTokens = CONTEXT_TARGETS.CODE.MAX_TOKENS;
+    }
+    else if (isTechnicalDocumentation(chunkContent) ||
+        mimeType.includes("markdown") ||
+        mimeType.includes("text/html")) {
+        minTokens = CONTEXT_TARGETS.TECHNICAL.MIN_TOKENS;
+        maxTokens = CONTEXT_TARGETS.TECHNICAL.MAX_TOKENS;
+    }
+    return getCachingContextualizationPrompt(chunkContent, mimeType, minTokens, maxTokens);
+}
+function containsMathematicalContent(content) {
+    const latexMathPatterns = [
+        /\$\$.+?\$\$/s,
+        /\$.+?\$/g,
+        /\\begin\{equation\}/,
+        /\\begin\{align\}/,
+        /\\sum_/,
+        /\\int/,
+        /\\frac\{/,
+        /\\sqrt\{/,
+        /\\alpha|\\beta|\\gamma|\\delta|\\theta|\\lambda|\\sigma/,
+        /\\nabla|\\partial/,
+    ];
+    const generalMathPatterns = [
+        /[≠≤≥±∞∫∂∑∏√∈∉⊆⊇⊂⊃∪∩]/,
+        /\b[a-zA-Z]\^[0-9]/,
+        /\(\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*\)/,
+        /\b[xyz]\s*=\s*-?\d+(\.\d+)?/,
+        /\[\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*\]/,
+        /\b\d+\s*×\s*\d+/,
+    ];
+    for (const pattern of latexMathPatterns) {
+        if (pattern.test(content)) {
+            return true;
+        }
+    }
+    // Test for general math patterns
+    for (const pattern of generalMathPatterns) {
+        if (pattern.test(content)) {
+            return true;
+        }
+    }
+    // Keyword analysis
+    const mathKeywords = [
+        "theorem",
+        "lemma",
+        "proof",
+        "equation",
+        "function",
+        "derivative",
+        "integral",
+        "matrix",
+        "vector",
+        "algorithm",
+        "constraint",
+        "coefficient",
+    ];
+    const contentLower = content.toLowerCase();
+    const mathKeywordCount = mathKeywords.filter((keyword) => contentLower.includes(keyword)).length;
+    return mathKeywordCount >= 2;
+}
+function isTechnicalDocumentation(content) {
+    const technicalPatterns = [
+        /\b(version|v)\s*\d+\.\d+(\.\d+)?/i,
+        /\b(api|sdk|cli)\b/i,
+        /\b(http|https|ftp):\/\//i,
+        /\b(GET|POST|PUT|DELETE)\b/,
+        /<\/?[a-z][\s\S]*>/i,
+        /\bREADME\b|\bCHANGELOG\b/i,
+        /\b(config|configuration)\b/i,
+        /\b(parameter|param|argument|arg)\b/i,
+    ];
+    const docHeadings = [
+        /\b(Introduction|Overview|Getting Started|Installation|Usage|API Reference|Troubleshooting)\b/i,
+    ];
+    for (const pattern of [...technicalPatterns, ...docHeadings]) {
+        if (pattern.test(content)) {
+            return true;
+        }
+    }
+    const listPatterns = [
+        /\d+\.\s.+\n\d+\.\s.+/,
+        /•\s.+\n•\s.+/,
+        /\*\s.+\n\*\s.+/,
+        /-\s.+\n-\s.+/,
+    ];
+    for (const pattern of listPatterns) {
+        if (pattern.test(content)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function getChunkWithContext(chunkContent, generatedContext) {
+    if (!generatedContext || generatedContext.trim() === "") {
+        return chunkContent;
+    }
+    return generatedContext.trim();
+}