@juspay/neurolink 8.16.0 → 8.18.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.18.0](https://github.com/juspay/neurolink/compare/v8.17.0...v8.18.0) (2025-12-16)
+
+### Features
+
+- **(utils):** standardize logging levels in CSVProcessor ([1c348b2](https://github.com/juspay/neurolink/commit/1c348b28d1212cd8ec33eb0100acddaa5a3df2bd))
+
+## [8.17.0](https://github.com/juspay/neurolink/compare/v8.16.0...v8.17.0) (2025-12-16)
+
+### Features
+
+- **(tts):** Add TTS type integration to GenerateOptions, GenerateResult, and StreamChunk ([e290330](https://github.com/juspay/neurolink/commit/e290330e8fe22a4cd0427185cbddbb8856fbd5ca))
+
 ## [8.16.0](https://github.com/juspay/neurolink/compare/v8.15.0...v8.16.0) (2025-12-16)
 
 ### Features

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

@@ -7,6 +7,7 @@ import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
+import type { TTSOptions, TTSResult } from "./ttsTypes.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -52,6 +53,39 @@ export type GenerateOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration
+     *
+     * Enable audio generation from the text response. The generated audio will be
+     * returned in the result's `audio` field as a TTSResult object.
+     *
+     * @example Basic TTS
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     * console.log(result.audio?.buffer); // Audio Buffer
+     * ```
+     *
+     * @example Advanced TTS with options
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Speak slowly and clearly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     pitch: 2.0,
+     *     format: "mp3",
+     *     quality: "standard"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;
@@ -144,6 +178,35 @@ export type GenerateResult = {
     outputs?: {
         text: string;
     };
+    /**
+     * Text-to-Speech audio result
+     *
+     * Contains the generated audio buffer and metadata when TTS is enabled.
+     * Generated by TTSProcessor.synthesize() using the specified provider.
+     *
+     * @example Accessing TTS audio
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * if (result.audio) {
+     *   console.log(`Audio size: ${result.audio.size} bytes`);
+     *   console.log(`Format: ${result.audio.format}`);
+     *   if (result.audio.duration) {
+     *     console.log(`Duration: ${result.audio.duration}s`);
+     *   }
+     *   if (result.audio.voice) {
+     *     console.log(`Voice: ${result.audio.voice}`);
+     *   }
+     *   // Save or play the audio buffer
+     *   fs.writeFileSync('output.mp3', result.audio.buffer);
+     * }
+     * ```
+     */
+    audio?: TTSResult;
     provider?: string;
     model?: string;
     usage?: TokenUsage;

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

@@ -9,6 +9,7 @@ import type { EvaluationData } from "../index.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
 import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 import type { ChatMessage } from "./conversation.js";
+import type { TTSOptions, TTSChunk } from "./ttsTypes.js";
 /**
  * Progress tracking and metadata for streaming operations
  */
@@ -121,6 +122,60 @@ export type AudioChunk = {
     channels: number;
     encoding: PCMEncoding;
 };
+/**
+ * Stream chunk type using discriminated union for type safety
+ *
+ * Used in streaming responses to deliver either text or TTS audio chunks.
+ * The discriminated union ensures type safety - only one variant can exist at a time.
+ *
+ * @example Processing text chunks
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "text") {
+ *     console.log(chunk.content); // TypeScript knows 'content' exists
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing audio chunks
+ * ```typescript
+ * const audioBuffer: Buffer[] = [];
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "audio") {
+ *     audioBuffer.push(chunk.audioChunk.data); // TypeScript knows 'audioChunk' exists
+ *     if (chunk.audioChunk.isFinal) {
+ *       const fullAudio = Buffer.concat(audioBuffer);
+ *       fs.writeFileSync('output.mp3', fullAudio);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing both text and audio
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   switch (chunk.type) {
+ *     case "text":
+ *       process.stdout.write(chunk.content);
+ *       break;
+ *     case "audio":
+ *       playAudioChunk(chunk.audioChunk.data);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamChunk = {
+    /** Discriminator for text chunks */
+    type: "text";
+    /** Text content chunk */
+    content: string;
+} | {
+    /** Discriminator for audio chunks */
+    type: "audio";
+    /** TTS audio chunk data */
+    audioChunk: TTSChunk;
+};
 export type StreamOptions = {
     input: {
         text: string;
@@ -168,6 +223,46 @@ export type StreamOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration for streaming
+     *
+     * Enable audio generation from the streamed text response. Audio chunks will be
+     * delivered through the stream alongside text chunks as TTSChunk objects.
+     *
+     * @example Basic streaming TTS
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * for await (const chunk of result.stream) {
+     *   if (chunk.type === "text") {
+     *     process.stdout.write(chunk.content);
+     *   } else if (chunk.type === "audio") {
+     *     // Handle audio chunk
+     *     playAudioChunk(chunk.audioChunk.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example Advanced streaming TTS with audio buffer
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Speak slowly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     format: "mp3",
+     *     quality: "hd"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;

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

@@ -114,3 +114,27 @@ export declare function isTTSResult(value: unknown): value is TTSResult;
  * Type guard to check if TTSOptions are valid
  */
 export declare function isValidTTSOptions(options: unknown): options is TTSOptions;
+/**
+ * TTS audio chunk for streaming Text-to-Speech output
+ *
+ * Represents a chunk of audio data generated during streaming TTS.
+ * Used in StreamChunk type to deliver audio alongside text content.
+ */
+export type TTSChunk = {
+    /** Audio data chunk as Buffer */
+    data: Buffer;
+    /** Audio format of this chunk */
+    format: AudioFormat;
+    /** Chunk sequence number (0-indexed) */
+    index: number;
+    /** Whether this is the final audio chunk */
+    isFinal: boolean;
+    /** Cumulative audio size in bytes so far */
+    cumulativeSize?: number;
+    /** Estimated total duration in seconds (if available) */
+    estimatedDuration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};

package/dist/lib/utils/csvProcessor.js

@@ -64,12 +64,21 @@ export class CSVProcessor {
     static async process(content, options) {
         const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", } = options || {};
         const maxRows = Math.max(1, Math.min(10000, rawMaxRows));
+        logger.debug("[CSVProcessor] Starting CSV processing", {
+            contentSize: content.length,
+            formatStyle,
+            maxRows,
+            includeHeaders,
+        });
         const csvString = content.toString("utf-8");
         // For raw format, return original CSV with row limit (no parsing needed)
         // This preserves the exact original format which works best for LLMs
         if (formatStyle === "raw") {
             const lines = csvString.split("\n");
             const hasMetadataLine = isMetadataLine(lines);
+            if (hasMetadataLine) {
+                logger.debug("[CSVProcessor] Detected metadata line, skipping first line");
+            }
             // Skip metadata line if present, then take header + maxRows data rows
             const csvLines = hasMetadataLine
                 ? lines.slice(1) // Skip metadata line
@@ -78,11 +87,21 @@ export class CSVProcessor {
             const limitedCSV = limitedLines.join("\n");
             const rowCount = limitedLines.length - 1; // Subtract header
             const originalRowCount = csvLines.length - 1; // Subtract header from original
+            const wasTruncated = rowCount < originalRowCount;
+            if (wasTruncated) {
+                logger.warn(`[CSVProcessor] CSV data truncated: showing ${rowCount} of ${originalRowCount} rows (limit: ${maxRows})`);
+            }
             logger.debug(`[CSVProcessor] raw format: ${rowCount} rows (original: ${originalRowCount}) → ${limitedCSV.length} chars`, {
                 formatStyle: "raw",
                 originalSize: csvString.length,
                 limitedSize: limitedCSV.length,
             });
+            logger.info("[CSVProcessor] ✅ Processed CSV file", {
+                formatStyle: "raw",
+                rowCount,
+                columnCount: (limitedLines[0] || "").split(",").length,
+                truncated: wasTruncated,
+            });
             return {
                 type: "csv",
                 content: limitedCSV,
@@ -96,6 +115,10 @@ export class CSVProcessor {
             };
         }
         // Parse CSV for JSON and Markdown formats only
+        logger.debug("[CSVProcessor] Parsing CSV for structured format conversion", {
+            formatStyle,
+            maxRows,
+        });
         const rows = await this.parseCSVString(csvString, maxRows);
         // Extract metadata from parsed results
         const rowCount = rows.length;
@@ -104,9 +127,24 @@ export class CSVProcessor {
         const hasEmptyColumns = columnNames.some((col) => !col || col.trim() === "");
         const sampleRows = rows.slice(0, 3);
         const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders);
+        if (hasEmptyColumns) {
+            logger.warn("[CSVProcessor] CSV contains empty or blank column headers", {
+                columnNames,
+            });
+        }
+        if (rowCount === 0) {
+            logger.warn("[CSVProcessor] CSV file contains no data rows");
+        }
         // Format parsed data
+        logger.debug(`[CSVProcessor] Converting ${rowCount} rows to ${formatStyle} format`);
         const formatted = this.formatForLLM(rows, formatStyle, includeHeaders);
-        logger.info(`[CSVProcessor] ${formatStyle} format: ${rowCount} rows × ${columnCount} columns → ${formatted.length} chars`, { rowCount, columnCount, columns: columnNames, hasEmptyColumns });
+        logger.info("[CSVProcessor] ✅ Processed CSV file", {
+            formatStyle,
+            rowCount,
+            columnCount,
+            outputLength: formatted.length,
+            hasEmptyColumns,
+        });
         return {
             type: "csv",
             content: formatted,
@@ -136,6 +174,10 @@ export class CSVProcessor {
     static async parseCSVFile(filePath, maxRows = 1000) {
         const clampedMaxRows = Math.max(1, Math.min(10000, maxRows));
         const fs = await import("fs");
+        logger.debug("[CSVProcessor] Starting file parsing", {
+            filePath,
+            maxRows: clampedMaxRows,
+        });
         // Read first 2 lines to detect metadata
         const fileHandle = await fs.promises.open(filePath, "r");
         const firstLines = [];
@@ -156,6 +198,9 @@ export class CSVProcessor {
         await fileHandle.close();
         const hasMetadataLine = isMetadataLine(firstLines);
         const skipLines = hasMetadataLine ? 1 : 0;
+        if (hasMetadataLine) {
+            logger.debug("[CSVProcessor] Detected metadata line in file, will skip first line");
+        }
         return new Promise((resolve, reject) => {
             const rows = [];
             let count = 0;
@@ -182,6 +227,7 @@ export class CSVProcessor {
                 }
             })
                 .on("end", () => {
+                logger.debug(`[CSVProcessor] File parsing complete: ${rows.length} rows parsed`);
                 resolve(rows);
             })
                 .on("error", (error) => {
@@ -200,10 +246,17 @@ export class CSVProcessor {
      */
     static async parseCSVString(csvString, maxRows = 1000) {
         const clampedMaxRows = Math.max(1, Math.min(10000, maxRows));
+        logger.debug("[CSVProcessor] Starting string parsing", {
+            inputLength: csvString.length,
+            maxRows: clampedMaxRows,
+        });
         // Detect and skip metadata line
         const lines = csvString.split("\n");
         const hasMetadataLine = isMetadataLine(lines);
         const csvData = hasMetadataLine ? lines.slice(1).join("\n") : csvString;
+        if (hasMetadataLine) {
+            logger.debug("[CSVProcessor] Detected metadata line in string, skipping");
+        }
         return new Promise((resolve, reject) => {
             const rows = [];
             let count = 0;
@@ -225,6 +278,7 @@ export class CSVProcessor {
                 }
             })
                 .on("end", () => {
+                logger.debug(`[CSVProcessor] String parsing complete: ${rows.length} rows parsed`);
                 resolve(rows);
             })
                 .on("error", (error) => {

package/dist/types/generateTypes.d.ts

@@ -7,6 +7,7 @@ import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
+import type { TTSOptions, TTSResult } from "./ttsTypes.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -52,6 +53,39 @@ export type GenerateOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration
+     *
+     * Enable audio generation from the text response. The generated audio will be
+     * returned in the result's `audio` field as a TTSResult object.
+     *
+     * @example Basic TTS
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     * console.log(result.audio?.buffer); // Audio Buffer
+     * ```
+     *
+     * @example Advanced TTS with options
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Speak slowly and clearly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     pitch: 2.0,
+     *     format: "mp3",
+     *     quality: "standard"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;
@@ -144,6 +178,35 @@ export type GenerateResult = {
     outputs?: {
         text: string;
     };
+    /**
+     * Text-to-Speech audio result
+     *
+     * Contains the generated audio buffer and metadata when TTS is enabled.
+     * Generated by TTSProcessor.synthesize() using the specified provider.
+     *
+     * @example Accessing TTS audio
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Hello world" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * if (result.audio) {
+     *   console.log(`Audio size: ${result.audio.size} bytes`);
+     *   console.log(`Format: ${result.audio.format}`);
+     *   if (result.audio.duration) {
+     *     console.log(`Duration: ${result.audio.duration}s`);
+     *   }
+     *   if (result.audio.voice) {
+     *     console.log(`Voice: ${result.audio.voice}`);
+     *   }
+     *   // Save or play the audio buffer
+     *   fs.writeFileSync('output.mp3', result.audio.buffer);
+     * }
+     * ```
+     */
+    audio?: TTSResult;
     provider?: string;
     model?: string;
     usage?: TokenUsage;

package/dist/types/streamTypes.d.ts

@@ -9,6 +9,7 @@ import type { EvaluationData } from "../index.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
 import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 import type { ChatMessage } from "./conversation.js";
+import type { TTSOptions, TTSChunk } from "./ttsTypes.js";
 /**
  * Progress tracking and metadata for streaming operations
  */
@@ -121,6 +122,60 @@ export type AudioChunk = {
     channels: number;
     encoding: PCMEncoding;
 };
+/**
+ * Stream chunk type using discriminated union for type safety
+ *
+ * Used in streaming responses to deliver either text or TTS audio chunks.
+ * The discriminated union ensures type safety - only one variant can exist at a time.
+ *
+ * @example Processing text chunks
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "text") {
+ *     console.log(chunk.content); // TypeScript knows 'content' exists
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing audio chunks
+ * ```typescript
+ * const audioBuffer: Buffer[] = [];
+ * for await (const chunk of result.stream) {
+ *   if (chunk.type === "audio") {
+ *     audioBuffer.push(chunk.audioChunk.data); // TypeScript knows 'audioChunk' exists
+ *     if (chunk.audioChunk.isFinal) {
+ *       const fullAudio = Buffer.concat(audioBuffer);
+ *       fs.writeFileSync('output.mp3', fullAudio);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Processing both text and audio
+ * ```typescript
+ * for await (const chunk of result.stream) {
+ *   switch (chunk.type) {
+ *     case "text":
+ *       process.stdout.write(chunk.content);
+ *       break;
+ *     case "audio":
+ *       playAudioChunk(chunk.audioChunk.data);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamChunk = {
+    /** Discriminator for text chunks */
+    type: "text";
+    /** Text content chunk */
+    content: string;
+} | {
+    /** Discriminator for audio chunks */
+    type: "audio";
+    /** TTS audio chunk data */
+    audioChunk: TTSChunk;
+};
 export type StreamOptions = {
     input: {
         text: string;
@@ -168,6 +223,46 @@ export type StreamOptions = {
         format?: "jpeg" | "png";
         transcribeAudio?: boolean;
     };
+    /**
+     * Text-to-Speech (TTS) configuration for streaming
+     *
+     * Enable audio generation from the streamed text response. Audio chunks will be
+     * delivered through the stream alongside text chunks as TTSChunk objects.
+     *
+     * @example Basic streaming TTS
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story" },
+     *   provider: "google-ai",
+     *   tts: { enabled: true, voice: "en-US-Neural2-C" }
+     * });
+     *
+     * for await (const chunk of result.stream) {
+     *   if (chunk.type === "text") {
+     *     process.stdout.write(chunk.content);
+     *   } else if (chunk.type === "audio") {
+     *     // Handle audio chunk
+     *     playAudioChunk(chunk.audioChunk.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example Advanced streaming TTS with audio buffer
+     * ```typescript
+     * const result = await neurolink.stream({
+     *   input: { text: "Speak slowly" },
+     *   provider: "google-ai",
+     *   tts: {
+     *     enabled: true,
+     *     voice: "en-US-Neural2-D",
+     *     speed: 0.8,
+     *     format: "mp3",
+     *     quality: "hd"
+     *   }
+     * });
+     * ```
+     */
+    tts?: TTSOptions;
     provider?: AIProviderName | string;
     model?: string;
     region?: string;

package/dist/types/ttsTypes.d.ts

@@ -114,3 +114,27 @@ export declare function isTTSResult(value: unknown): value is TTSResult;
  * Type guard to check if TTSOptions are valid
  */
 export declare function isValidTTSOptions(options: unknown): options is TTSOptions;
+/**
+ * TTS audio chunk for streaming Text-to-Speech output
+ *
+ * Represents a chunk of audio data generated during streaming TTS.
+ * Used in StreamChunk type to deliver audio alongside text content.
+ */
+export type TTSChunk = {
+    /** Audio data chunk as Buffer */
+    data: Buffer;
+    /** Audio format of this chunk */
+    format: AudioFormat;
+    /** Chunk sequence number (0-indexed) */
+    index: number;
+    /** Whether this is the final audio chunk */
+    isFinal: boolean;
+    /** Cumulative audio size in bytes so far */
+    cumulativeSize?: number;
+    /** Estimated total duration in seconds (if available) */
+    estimatedDuration?: number;
+    /** Voice used for generation */
+    voice?: string;
+    /** Sample rate in Hz */
+    sampleRate?: number;
+};

package/dist/utils/csvProcessor.js

@@ -64,12 +64,21 @@ export class CSVProcessor {
     static async process(content, options) {
         const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", } = options || {};
         const maxRows = Math.max(1, Math.min(10000, rawMaxRows));
+        logger.debug("[CSVProcessor] Starting CSV processing", {
+            contentSize: content.length,
+            formatStyle,
+            maxRows,
+            includeHeaders,
+        });
         const csvString = content.toString("utf-8");
         // For raw format, return original CSV with row limit (no parsing needed)
         // This preserves the exact original format which works best for LLMs
         if (formatStyle === "raw") {
             const lines = csvString.split("\n");
             const hasMetadataLine = isMetadataLine(lines);
+            if (hasMetadataLine) {
+                logger.debug("[CSVProcessor] Detected metadata line, skipping first line");
+            }
             // Skip metadata line if present, then take header + maxRows data rows
             const csvLines = hasMetadataLine
                 ? lines.slice(1) // Skip metadata line
@@ -78,11 +87,21 @@ export class CSVProcessor {
             const limitedCSV = limitedLines.join("\n");
             const rowCount = limitedLines.length - 1; // Subtract header
             const originalRowCount = csvLines.length - 1; // Subtract header from original
+            const wasTruncated = rowCount < originalRowCount;
+            if (wasTruncated) {
+                logger.warn(`[CSVProcessor] CSV data truncated: showing ${rowCount} of ${originalRowCount} rows (limit: ${maxRows})`);
+            }
             logger.debug(`[CSVProcessor] raw format: ${rowCount} rows (original: ${originalRowCount}) → ${limitedCSV.length} chars`, {
                 formatStyle: "raw",
                 originalSize: csvString.length,
                 limitedSize: limitedCSV.length,
             });
+            logger.info("[CSVProcessor] ✅ Processed CSV file", {
+                formatStyle: "raw",
+                rowCount,
+                columnCount: (limitedLines[0] || "").split(",").length,
+                truncated: wasTruncated,
+            });
             return {
                 type: "csv",
                 content: limitedCSV,
@@ -96,6 +115,10 @@ export class CSVProcessor {
             };
         }
         // Parse CSV for JSON and Markdown formats only
+        logger.debug("[CSVProcessor] Parsing CSV for structured format conversion", {
+            formatStyle,
+            maxRows,
+        });
         const rows = await this.parseCSVString(csvString, maxRows);
         // Extract metadata from parsed results
         const rowCount = rows.length;
@@ -104,9 +127,24 @@ export class CSVProcessor {
         const hasEmptyColumns = columnNames.some((col) => !col || col.trim() === "");
         const sampleRows = rows.slice(0, 3);
         const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders);
+        if (hasEmptyColumns) {
+            logger.warn("[CSVProcessor] CSV contains empty or blank column headers", {
+                columnNames,
+            });
+        }
+        if (rowCount === 0) {
+            logger.warn("[CSVProcessor] CSV file contains no data rows");
+        }
         // Format parsed data
+        logger.debug(`[CSVProcessor] Converting ${rowCount} rows to ${formatStyle} format`);
         const formatted = this.formatForLLM(rows, formatStyle, includeHeaders);
-        logger.info(`[CSVProcessor] ${formatStyle} format: ${rowCount} rows × ${columnCount} columns → ${formatted.length} chars`, { rowCount, columnCount, columns: columnNames, hasEmptyColumns });
+        logger.info("[CSVProcessor] ✅ Processed CSV file", {
+            formatStyle,
+            rowCount,
+            columnCount,
+            outputLength: formatted.length,
+            hasEmptyColumns,
+        });
         return {
             type: "csv",
             content: formatted,
@@ -136,6 +174,10 @@ export class CSVProcessor {
     static async parseCSVFile(filePath, maxRows = 1000) {
         const clampedMaxRows = Math.max(1, Math.min(10000, maxRows));
         const fs = await import("fs");
+        logger.debug("[CSVProcessor] Starting file parsing", {
+            filePath,
+            maxRows: clampedMaxRows,
+        });
         // Read first 2 lines to detect metadata
         const fileHandle = await fs.promises.open(filePath, "r");
         const firstLines = [];
@@ -156,6 +198,9 @@ export class CSVProcessor {
         await fileHandle.close();
         const hasMetadataLine = isMetadataLine(firstLines);
         const skipLines = hasMetadataLine ? 1 : 0;
+        if (hasMetadataLine) {
+            logger.debug("[CSVProcessor] Detected metadata line in file, will skip first line");
+        }
         return new Promise((resolve, reject) => {
             const rows = [];
             let count = 0;
@@ -182,6 +227,7 @@ export class CSVProcessor {
                 }
             })
                 .on("end", () => {
+                logger.debug(`[CSVProcessor] File parsing complete: ${rows.length} rows parsed`);
                 resolve(rows);
             })
                 .on("error", (error) => {
@@ -200,10 +246,17 @@ export class CSVProcessor {
      */
     static async parseCSVString(csvString, maxRows = 1000) {
         const clampedMaxRows = Math.max(1, Math.min(10000, maxRows));
+        logger.debug("[CSVProcessor] Starting string parsing", {
+            inputLength: csvString.length,
+            maxRows: clampedMaxRows,
+        });
         // Detect and skip metadata line
         const lines = csvString.split("\n");
         const hasMetadataLine = isMetadataLine(lines);
         const csvData = hasMetadataLine ? lines.slice(1).join("\n") : csvString;
+        if (hasMetadataLine) {
+            logger.debug("[CSVProcessor] Detected metadata line in string, skipping");
+        }
         return new Promise((resolve, reject) => {
             const rows = [];
             let count = 0;
@@ -225,6 +278,7 @@ export class CSVProcessor {
                 }
             })
                 .on("end", () => {
+                logger.debug(`[CSVProcessor] String parsing complete: ${rows.length} rows parsed`);
                 resolve(rows);
             })
                 .on("error", (error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "8.16.0",
+  "version": "8.18.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 9 major providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",