@juspay/neurolink 9.5.2 → 9.6.0

package/dist/lib/types/fileReferenceTypes.d.ts

@@ -0,0 +1,222 @@
+/**
+ * File Reference Architecture Types (canonical location)
+ *
+ * Types for the lazy on-demand file processing system.
+ * Files are registered as lightweight references with metadata and previews.
+ * Full content is processed on-demand when the LLM requests it via tools.
+ */
+import type { FileSource, FileType } from "./fileTypes.js";
+/**
+ * Size tier determines the processing strategy for a file.
+ *
+ * - tiny:     Inline in prompt (current behavior)
+ * - small:    Full load, truncate to budget
+ * - medium:   Outline + on-demand sections
+ * - large:    Stream + chunked summarization
+ * - huge:     Reference only + tool-based access
+ * - oversized: Reject with informative message
+ */
+export type SizeTier = "tiny" | "small" | "medium" | "large" | "huge" | "oversized";
+/**
+ * Processing status of a file reference
+ */
+export type FileReferenceStatus = "registered" | "previewed" | "processing" | "processed" | "error";
+/**
+ * A section in a file outline (used for code, PDFs, spreadsheets)
+ */
+export type OutlineSection = {
+    /** Section heading/name (e.g., function name, class name, sheet name) */
+    name: string;
+    /** Type of section (function, class, import, sheet, page, heading) */
+    kind: string;
+    /** Starting line number (1-indexed) */
+    startLine: number;
+    /** Ending line number (1-indexed) */
+    endLine: number;
+    /** Nesting depth (0 = top-level) */
+    depth: number;
+    /** Child sections (e.g., methods within a class) */
+    children?: OutlineSection[];
+};
+/**
+ * A lightweight reference to a file registered for on-demand processing.
+ *
+ * Registration is fast (~1ms): only stat + magic bytes + first 1KB preview.
+ * Full processing is deferred until the LLM requests it via tools.
+ */
+export type FileReference = {
+    /** Unique identifier (UUID v4) */
+    id: string;
+    /** How the file was provided */
+    source: FileSource;
+    /** Original file path or URL */
+    originalPath?: string;
+    /** Display name */
+    filename: string;
+    /** Original file size in bytes */
+    sizeBytes: number;
+    /** Detected file type from magic bytes / extension */
+    detectedType: FileType;
+    /** Detected MIME type */
+    mimeType: string;
+    /** Size tier determining processing strategy */
+    sizeTier: SizeTier;
+    /** Estimated tokens after processing (type-aware) */
+    estimatedTokens: number;
+    /** First ~500 tokens of content (lightweight preview) */
+    preview: string;
+    /** Current processing status */
+    status: FileReferenceStatus;
+    /** LLM-generated summary (populated lazily via summarize_file tool) */
+    summary?: string;
+    /** Structural outline for code/docs (populated lazily) */
+    outlineSections?: OutlineSection[];
+    /** Path in temp directory where buffer is persisted */
+    tempPath?: string;
+    /** Provider file API ID (for Anthropic Files API, Gemini File API, etc.) */
+    providerId?: string;
+    /** Full processed content (cached after first full processing) */
+    processedContent?: string;
+    /** Extracted images (e.g., video keyframes, PPTX slide images) */
+    extractedImages?: Buffer[];
+    /** Timestamp when the file was registered */
+    registeredAt: number;
+    /** Timestamp when the file was last accessed (for LRU eviction) */
+    lastAccessedAt: number;
+    /** Total line count (for text files, populated on first read) */
+    totalLines?: number;
+    /** File extension (e.g., 'py', 'xlsx', 'mp4') */
+    extension?: string;
+};
+/**
+ * Options for registering a file
+ */
+export type FileRegistrationOptions = {
+    /** Override filename detection */
+    filename?: string;
+    /** Override file type detection */
+    fileType?: FileType;
+    /** Maximum preview length in characters */
+    maxPreviewChars?: number;
+    /** Skip persisting buffer to temp directory */
+    skipTempPersist?: boolean;
+};
+/**
+ * Result of reading a file section
+ */
+export type FileReadResult = {
+    /** The content that was read */
+    content: string;
+    /** Starting line number (1-indexed) */
+    startLine: number;
+    /** Ending line number (1-indexed) */
+    endLine: number;
+    /** Total lines in the file */
+    totalLines: number;
+    /** Whether the content was truncated to fit token budget */
+    truncated: boolean;
+    /** Number of tokens in the returned content */
+    estimatedTokens: number;
+};
+/**
+ * Result of searching within a file
+ */
+export type FileSearchResult = {
+    /** Matching lines with context */
+    matches: FileSearchMatch[];
+    /** Total number of matches found */
+    totalMatches: number;
+    /** Whether results were truncated */
+    truncated: boolean;
+};
+/**
+ * A single search match within a file
+ */
+export type FileSearchMatch = {
+    /** Line number (1-indexed) */
+    lineNumber: number;
+    /** The matching line content */
+    line: string;
+    /** Context lines before the match */
+    contextBefore: string[];
+    /** Context lines after the match */
+    contextAfter: string[];
+};
+/**
+ * Options for the streaming reader
+ */
+export type StreamingReaderOptions = {
+    /** Maximum tokens to read (stops when budget exhausted) */
+    tokenBudget?: number;
+    /** Starting line number (1-indexed, default 1) */
+    startLine?: number;
+    /** Ending line number (1-indexed, default EOF) */
+    endLine?: number;
+    /** Encoding (default 'utf-8') */
+    encoding?: BufferEncoding;
+    /** Provider name for token estimation multiplier */
+    provider?: string;
+};
+/**
+ * Parameters for targeted content extraction via extract_file_content tool.
+ * Different file types use different subsets of these parameters.
+ */
+export type FileExtractionParams = {
+    /** File ID (UUID) or filename */
+    file_id: string;
+    /** Start timestamp in seconds (video) */
+    start_time?: number;
+    /** End timestamp in seconds (video) */
+    end_time?: number;
+    /** Number of frames to extract in range (video, default: 5) */
+    frame_count?: number;
+    /** Specific page/slide numbers (1-indexed) */
+    pages?: number[];
+    /** Page range (1-indexed, inclusive) */
+    page_range?: {
+        start: number;
+        end: number;
+    };
+    /** Sheet name or 0-based index */
+    sheet?: string | number;
+    /** Row range (1-indexed) */
+    row_range?: {
+        start: number;
+        end: number;
+    };
+    /** Specific columns (e.g., ["A", "B", "D"]) */
+    columns?: string[];
+    /** File path within the archive */
+    entry_path?: string;
+    /** Output format hint */
+    format?: "text" | "detailed" | "summary";
+};
+/**
+ * Result of targeted content extraction.
+ * May contain text, images, or both depending on the extraction type.
+ */
+export type FileExtractionResult = {
+    /** Whether the extraction succeeded */
+    success: boolean;
+    /** Extracted text content */
+    text?: string;
+    /** Extracted images as JPEG buffers (e.g., video frames, slide renders) */
+    images?: Buffer[];
+    /** Metadata about the extraction */
+    metadata?: Record<string, unknown>;
+    /** Error message if extraction failed */
+    error?: string;
+};
+/**
+ * Options for the file reference registry
+ */
+export type FileRegistryOptions = {
+    /** Directory for persisting file buffers (default: os.tmpdir()/neurolink-files/) */
+    tempDir?: string;
+    /** Maximum number of file references to keep (LRU eviction, default: 100) */
+    maxFiles?: number;
+    /** Maximum total bytes to persist to temp (default: 1GB) */
+    maxTempBytes?: number;
+    /** Default preview length in characters (default: 2000) */
+    defaultPreviewChars?: number;
+};

package/dist/lib/types/fileReferenceTypes.js

@@ -0,0 +1,9 @@
+/**
+ * File Reference Architecture Types (canonical location)
+ *
+ * Types for the lazy on-demand file processing system.
+ * Files are registered as lightweight references with metadata and previews.
+ * Full content is processed on-demand when the LLM requests it via tools.
+ */
+export {};
+//# sourceMappingURL=fileReferenceTypes.js.map

package/dist/lib/types/fileTypes.d.ts

@@ -4,15 +4,34 @@
 /**
  * Supported file types for multimodal input
  */
-export type FileType = "csv" | "image" | "pdf" | "audio" | "text" | "svg" | "docx" | "pptx" | "xlsx" | "unknown";
+export type FileType = "csv" | "image" | "pdf" | "audio" | "video" | "archive" | "text" | "svg" | "docx" | "pptx" | "xlsx" | "unknown";
 /**
  * Office document types
  */
 export type OfficeDocumentType = "docx" | "pptx" | "xlsx";
 /**
- * File input can be Buffer or string (path/URL/data URI)
+ * File with metadata — allows callers to pass filename alongside a Buffer.
+ *
+ * This is the recommended way for applications (e.g. Slack bots) to pass
+ * files that were downloaded as Buffers but still have original filenames.
+ *
+ * @example
+ * ```typescript
+ * files: [
+ *   { buffer: pdfBuffer, filename: "quarterly-report.pdf" },
+ *   { buffer: videoBuffer, filename: "meeting-recording.mov", mimetype: "video/quicktime" }
+ * ]
+ * ```
+ */
+export type FileWithMetadata = {
+    buffer: Buffer;
+    filename: string;
+    mimetype?: string;
+};
+/**
+ * File input can be Buffer, string (path/URL/data URI), or an object with metadata.
  */
-export type FileInput = Buffer | string;
+export type FileInput = Buffer | string | FileWithMetadata;
 /**
  * File source type for tracking input origin
  */
@@ -38,6 +57,8 @@ export type FileProcessingResult = {
     type: FileType;
     content: string | Buffer;
     mimeType: string;
+    /** Additional images extracted from the file (e.g., video keyframes, audio cover art) */
+    images?: Array<Buffer | string>;
     metadata: {
         confidence: number;
         size?: number;
@@ -73,6 +94,8 @@ export type FileProcessingResult = {
         modifiedDate?: string;
         hasFormulas?: boolean;
         hasImages?: boolean;
+        frameCount?: number;
+        hasKeyframes?: boolean;
     };
 };
 /**

package/dist/lib/types/generateTypes.d.ts

@@ -39,7 +39,7 @@ export type GenerateOptions = {
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
         videoFiles?: Array<Buffer | string>;
-        files?: Array<Buffer | string>;
+        files?: Array<Buffer | string | import("./fileTypes.js").FileWithMetadata>;
         content?: Content[];
     };
     /**
@@ -293,6 +293,17 @@ export type GenerateOptions = {
      * ```
      */
     rag?: RAGConfig;
+    /**
+     * File reference registry for on-demand file processing.
+     *
+     * When set, files above the "tiny" size tier (>10KB) will be registered
+     * as lightweight references instead of being fully loaded into the prompt.
+     * The LLM can then access file content on-demand via file tools
+     * (list_attached_files, read_file_section, search_in_file).
+     *
+     * @internal Set by NeuroLink SDK — not typically used directly by consumers.
+     */
+    fileRegistry?: unknown;
 };
 /**
  * Generate function result type - Primary output format
@@ -588,6 +599,16 @@ export type TextGenerationOptions = {
         includeHeaders?: boolean;
     };
     enableSummarization?: boolean;
+    /**
+     * File reference registry for on-demand file processing (internal).
+     *
+     * When set, files above the "tiny" size tier (>10KB) will be registered
+     * as lightweight references instead of being fully loaded into the prompt.
+     * The LLM can then access file content on-demand via file tools.
+     *
+     * @internal Set by NeuroLink SDK — not typically used directly by consumers.
+     */
+    fileRegistry?: unknown;
     /**
      * ## Extended Thinking Options
      *

package/dist/lib/types/index.d.ts

@@ -33,9 +33,8 @@ export type { EnhancedStreamProvider, ProgressCallback, StreamingMetadata, Strea
 ToolCallResults, ToolCalls, ToolResult as StreamToolResult, } from "./streamTypes.js";
 export * from "./ttsTypes.js";
 export * from "./utilities.js";
-export * from "./middlewareTypes.js";
-export * from "./fileTypes.js";
-export * from "./content.js";
-export * from "./ttsTypes.js";
-export * from "./hitlTypes.js";
 export * from "./workflowTypes.js";
+export * from "./contextTypes.js";
+export * from "./fileReferenceTypes.js";
+export * from "./ragTypes.js";
+export * from "./conversationMemoryInterface.js";

package/dist/lib/types/index.js

@@ -38,16 +38,14 @@ export * from "./serviceTypes.js";
 export * from "./ttsTypes.js";
 // Utilities Types - Utility module types (selective export to avoid conflicts)
 export * from "./utilities.js";
-// Middleware Types - Middleware system types
-export * from "./middlewareTypes.js";
-// File detection and processing types
-export * from "./fileTypes.js";
-// Content types for multimodal support (includes multimodal re-exports for backward compatibility)
-export * from "./content.js";
-// TTS (Text-to-Speech) types
-export * from "./ttsTypes.js";
-// HITL (Human-in-the-Loop) types
-export * from "./hitlTypes.js";
 // Workflow types
 export * from "./workflowTypes.js";
+// Context compaction types
+export * from "./contextTypes.js";
+// File reference types
+export * from "./fileReferenceTypes.js";
+// RAG types
+export * from "./ragTypes.js";
+// Conversation memory manager type
+export * from "./conversationMemoryInterface.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/types/modelTypes.d.ts

@@ -160,6 +160,7 @@ export declare const ModelRegistrySchema: z.ZodObject<{
     defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
         capabilities: string[];
         id: string;
@@ -172,11 +173,11 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }, {
     version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
         capabilities: string[];
         id: string;
@@ -189,7 +190,6 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }>;