@juspay/neurolink 7.48.1 → 7.49.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [7.49.0](https://github.com/juspay/neurolink/compare/v7.48.1...v7.49.0) (2025-10-07)
+
+### Features
+
+- **(cli):** added support for resuming a conversation ([b860d29](https://github.com/juspay/neurolink/commit/b860d2995a2c3fe29a39c750f152d9f32abb612f))
+- **(middleware):** implement guardrails pre-call filtering with demo and proof ([b99a7f1](https://github.com/juspay/neurolink/commit/b99a7f15e5972eec4bd5652792f56f192239fd8d))
+- **(multimodal):** add comprehensive CSV file support with auto-detection and analysis tools ([374b375](https://github.com/juspay/neurolink/commit/374b3750a996a4e2e466bc1af1d54c9aec7f3b8c))
+
+### Bug Fixes
+
+- **(azure):** add SDK parameter support for lighthouse tool events compatibility ([a3bca3b](https://github.com/juspay/neurolink/commit/a3bca3b27b5505919a403896ee1dc1fb55a1983f))
+- **(formatting):** fixed linting issues with docs ([a7d1aff](https://github.com/juspay/neurolink/commit/a7d1affa6d8d00fd2b7491e1643e86654b242a40))
+
 ## [7.48.1](https://github.com/juspay/neurolink/compare/v7.48.0...v7.48.1) (2025-10-02)
 
 ## [7.48.0](https://github.com/juspay/neurolink/compare/v7.47.3...v7.48.0) (2025-09-30)

package/README.md

@@ -9,12 +9,29 @@
 
 Enterprise AI development platform with unified provider access, production-ready tooling, and an opinionated factory architecture. NeuroLink ships as both a TypeScript SDK and a professional CLI so teams can build, operate, and iterate on AI features quickly.
 
+## 🧠 What is NeuroLink?
+
+**NeuroLink is the universal AI integration platform that unifies 12 major AI providers and 100+ models under one consistent API.**
+
+Extracted from production systems at Juspay and battle-tested at enterprise scale, NeuroLink provides a production-ready solution for integrating AI into any application. Whether you're building with OpenAI, Anthropic, Google, AWS Bedrock, Azure, or any of our 12 supported providers, NeuroLink gives you a single, consistent interface that works everywhere.
+
+**Why NeuroLink?** Switch providers with a single parameter change, leverage 64+ built-in tools and MCP servers, deploy with confidence using enterprise features like Redis memory and multi-provider failover, and optimize costs automatically with intelligent routing. Use it via our professional CLI or TypeScript SDK—whichever fits your workflow.
+
+**Where we're headed:** We're building for the future of AI—edge-first execution and continuous streaming architectures that make AI practically free and universally available. **[Read our vision →](docs/about/vision.md)**
+
+**[Get Started in <5 Minutes →](docs/getting-started/quick-start.md)**
+
+---
+
 ## What's New (Q4 2025)
 
-- **Human-in-the-loop workflows** – Pause generation for user approval/input before tool execution or continuing. → [`docs/features/hitl.md`](docs/features/hitl.md)
-- **Guardrails middleware** – Block PII, profanity, and unsafe content with built-in content filtering. → [`docs/features/guardrails.md`](docs/features/guardrails.md)
-- **Context summarization** – Automatic conversation compression for long-running sessions with memory. → [`docs/features/context-summarization.md`](docs/features/context-summarization.md)
-- **Redis conversation export** – Export full session history as JSON for analytics and debugging. → [`docs/features/conversation-history.md`](docs/features/conversation-history.md)
+- **CSV File Support** – Attach CSV files to prompts for AI-powered data analysis with auto-detection. → [CSV Guide](docs/features/multimodal-chat.md#csv-file-support)
+- **LiteLLM Integration** – Access 100+ AI models from all major providers through unified interface. → [Setup Guide](docs/LITELLM-INTEGRATION.md)
+- **SageMaker Integration** – Deploy and use custom trained models on AWS infrastructure. → [Setup Guide](docs/SAGEMAKER-INTEGRATION.md)
+- **Human-in-the-loop workflows** – Pause generation for user approval/input before tool execution. → [HITL Guide](docs/features/hitl.md)
+- **Guardrails middleware** – Block PII, profanity, and unsafe content with built-in filtering. → [Guardrails Guide](docs/features/guardrails.md)
+- **Context summarization** – Automatic conversation compression for long-running sessions. → [Summarization Guide](docs/CONTEXT-SUMMARIZATION.md)
+- **Redis conversation export** – Export full session history as JSON for analytics and debugging. → [History Guide](docs/features/conversation-history.md)
 
 > **Q3 highlights** (multimodal chat, auto-evaluation, loop sessions, orchestration) are now in [Platform Capabilities](#platform-capabilities-at-a-glance) below.
 
@@ -28,7 +45,186 @@ pnpm dlx @juspay/neurolink setup
 npx @juspay/neurolink generate "Write a launch plan for multimodal chat"
 ```
 
-Need a persistent workspace? Launch loop mode:
+Need a persistent workspace? Launch loop mode with `npx @juspay/neurolink loop` - [Learn more →](docs/features/cli-loop-sessions.md)
+
+## 🌟 Complete Feature Set
+
+NeuroLink is a comprehensive AI development platform. Every feature below is production-ready and fully documented.
+
+### 🤖 AI Provider Integration
+
+**12 providers unified under one API** - Switch providers with a single parameter change.
+
+| Provider              | Models                         | Free Tier       | Tool Support | Status        | Documentation                                                           |
+| --------------------- | ------------------------------ | --------------- | ------------ | ------------- | ----------------------------------------------------------------------- |
+| **OpenAI**            | GPT-4o, GPT-4o-mini, o1        | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#openai)            |
+| **Anthropic**         | Claude 3.5/3.7 Sonnet, Opus    | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#anthropic)         |
+| **Google AI Studio**  | Gemini 2.5 Flash/Pro           | ✅ Free Tier    | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#google-ai)         |
+| **AWS Bedrock**       | Claude, Titan, Llama, Nova     | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#bedrock)           |
+| **Google Vertex**     | Gemini via GCP                 | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#vertex)            |
+| **Azure OpenAI**      | GPT-4, GPT-4o, o1              | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#azure)             |
+| **LiteLLM**           | 100+ models unified            | Varies          | ✅ Full      | ✅ Production | [Setup Guide](docs/LITELLM-INTEGRATION.md)                              |
+| **AWS SageMaker**     | Custom deployed models         | ❌              | ✅ Full      | ✅ Production | [Setup Guide](docs/SAGEMAKER-INTEGRATION.md)                            |
+| **Mistral AI**        | Mistral Large, Small           | ✅ Free Tier    | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#mistral)           |
+| **Hugging Face**      | 100,000+ models                | ✅ Free         | ⚠️ Partial   | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#huggingface)       |
+| **Ollama**            | Local models (Llama, Mistral)  | ✅ Free (Local) | ⚠️ Partial   | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#ollama)            |
+| **OpenAI Compatible** | Any OpenAI-compatible endpoint | Varies          | ✅ Full      | ✅ Production | [Setup Guide](docs/getting-started/provider-setup.md#openai-compatible) |
+
+**[📖 Provider Comparison Guide](docs/reference/provider-comparison.md)** - Detailed feature matrix and selection criteria
+
+---
+
+### 🔧 Built-in Tools & MCP Integration
+
+**6 Core Tools** (work across all providers, zero configuration):
+
+| Tool                 | Purpose                  | Auto-Available          | Documentation                                             |
+| -------------------- | ------------------------ | ----------------------- | --------------------------------------------------------- |
+| `getCurrentTime`     | Real-time clock access   | ✅                      | [Tool Reference](docs/sdk/custom-tools.md#getCurrentTime) |
+| `readFile`           | File system reading      | ✅                      | [Tool Reference](docs/sdk/custom-tools.md#readFile)       |
+| `writeFile`          | File system writing      | ✅                      | [Tool Reference](docs/sdk/custom-tools.md#writeFile)      |
+| `listDirectory`      | Directory listing        | ✅                      | [Tool Reference](docs/sdk/custom-tools.md#listDirectory)  |
+| `calculateMath`      | Mathematical operations  | ✅                      | [Tool Reference](docs/sdk/custom-tools.md#calculateMath)  |
+| `websearchGrounding` | Google Vertex web search | ⚠️ Requires credentials | [Tool Reference](docs/sdk/custom-tools.md#websearch)      |
+
+**58+ External MCP Servers** supported (GitHub, PostgreSQL, Google Drive, Slack, and more):
+
+```typescript
+// Add any MCP server dynamically
+await neurolink.addExternalMCPServer("github", {
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-github"],
+  transport: "stdio",
+  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+});
+
+// Tools automatically available to AI
+const result = await neurolink.generate({
+  input: { text: 'Create a GitHub issue titled "Bug in auth flow"' },
+});
+```
+
+**[📖 MCP Integration Guide](docs/advanced/mcp-integration.md)** - Setup external servers
+
+---
+
+### 💻 Developer Experience Features
+
+**SDK-First Design** with TypeScript, IntelliSense, and type safety:
+
+| Feature                     | Description                    | Documentation                                         |
+| --------------------------- | ------------------------------ | ----------------------------------------------------- |
+| **Auto Provider Selection** | Intelligent provider fallback  | [SDK Guide](docs/sdk/index.md#auto-selection)         |
+| **Streaming Responses**     | Real-time token streaming      | [Streaming Guide](docs/advanced/streaming.md)         |
+| **Conversation Memory**     | Automatic context management   | [Memory Guide](docs/sdk/index.md#memory)              |
+| **Full Type Safety**        | Complete TypeScript types      | [Type Reference](docs/sdk/api-reference.md)           |
+| **Error Handling**          | Graceful provider fallback     | [Error Guide](docs/reference/troubleshooting.md)      |
+| **Analytics & Evaluation**  | Usage tracking, quality scores | [Analytics Guide](docs/advanced/analytics.md)         |
+| **Middleware System**       | Request/response hooks         | [Middleware Guide](docs/CUSTOM-MIDDLEWARE-GUIDE.md)   |
+| **Framework Integration**   | Next.js, SvelteKit, Express    | [Framework Guides](docs/sdk/framework-integration.md) |
+
+---
+
+### 🏢 Enterprise & Production Features
+
+**Production-ready capabilities for regulated industries:**
+
+| Feature                     | Description                        | Use Case                  | Documentation                                               |
+| --------------------------- | ---------------------------------- | ------------------------- | ----------------------------------------------------------- |
+| **Enterprise Proxy**        | Corporate proxy support            | Behind firewalls          | [Proxy Setup](docs/ENTERPRISE-PROXY-SETUP.md)               |
+| **Redis Memory**            | Distributed conversation state     | Multi-instance deployment | [Redis Guide](docs/getting-started/provider-setup.md#redis) |
+| **Cost Optimization**       | Automatic cheapest model selection | Budget control            | [Cost Guide](docs/advanced/index.md)                        |
+| **Multi-Provider Failover** | Automatic provider switching       | High availability         | [Failover Guide](docs/advanced/index.md)                    |
+| **Telemetry & Monitoring**  | OpenTelemetry integration          | Observability             | [Telemetry Guide](docs/TELEMETRY-GUIDE.md)                  |
+| **Security Hardening**      | Credential management, auditing    | Compliance                | [Security Guide](docs/advanced/enterprise.md)               |
+| **Custom Model Hosting**    | SageMaker integration              | Private models            | [SageMaker Guide](docs/SAGEMAKER-INTEGRATION.md)            |
+| **Load Balancing**          | LiteLLM proxy integration          | Scale & routing           | [Load Balancing](docs/LITELLM-INTEGRATION.md)               |
+
+**Security & Compliance:**
+
+- ✅ SOC2 Type II compliant deployments
+- ✅ ISO 27001 certified infrastructure compatible
+- ✅ GDPR-compliant data handling (EU providers available)
+- ✅ HIPAA compatible (with proper configuration)
+- ✅ Hardened OS verified (SELinux, AppArmor)
+- ✅ Zero credential logging
+- ✅ Encrypted configuration storage
+
+**[📖 Enterprise Deployment Guide](docs/advanced/enterprise.md)** - Complete production checklist
+
+---
+
+### 🎨 Professional CLI
+
+**15+ commands** for every workflow:
+
+| Command    | Purpose                            | Example                    | Documentation                             |
+| ---------- | ---------------------------------- | -------------------------- | ----------------------------------------- |
+| `setup`    | Interactive provider configuration | `neurolink setup`          | [Setup Guide](docs/cli/index.md)          |
+| `generate` | Text generation                    | `neurolink gen "Hello"`    | [Generate](docs/cli/commands.md#generate) |
+| `stream`   | Streaming generation               | `neurolink stream "Story"` | [Stream](docs/cli/commands.md#stream)     |
+| `status`   | Provider health check              | `neurolink status`         | [Status](docs/cli/commands.md#status)     |
+| `loop`     | Interactive session                | `neurolink loop`           | [Loop](docs/cli/commands.md#loop)         |
+| `mcp`      | MCP server management              | `neurolink mcp discover`   | [MCP CLI](docs/cli/commands.md#mcp)       |
+| `models`   | Model listing                      | `neurolink models`         | [Models](docs/cli/commands.md#models)     |
+| `eval`     | Model evaluation                   | `neurolink eval`           | [Eval](docs/cli/commands.md#eval)         |
+
+**[📖 Complete CLI Reference](docs/cli/commands.md)** - All commands and options
+
+## 💰 Smart Model Selection
+
+NeuroLink features intelligent model selection and cost optimization:
+
+### Cost Optimization Features
+
+- **💰 Automatic Cost Optimization**: Selects cheapest models for simple tasks
+- **🔄 LiteLLM Model Routing**: Access 100+ models with automatic load balancing
+- **🔍 Capability-Based Selection**: Find models with specific features (vision, function calling)
+- **⚡ Intelligent Fallback**: Seamless switching when providers fail
+
+```bash
+# Cost optimization - automatically use cheapest model
+npx @juspay/neurolink generate "Hello" --optimize-cost
+
+# LiteLLM specific model selection
+npx @juspay/neurolink generate "Complex analysis" --provider litellm --model "anthropic/claude-3-5-sonnet"
+
+# Auto-select best available provider
+npx @juspay/neurolink generate "Write code" # Automatically chooses optimal provider
+```
+
+## ✨ Interactive Loop Mode
+
+NeuroLink features a powerful **interactive loop mode** that transforms the CLI into a persistent, stateful session. This allows you to run multiple commands, set session-wide variables, and maintain conversation history without restarting.
+
+### Start the Loop
+
+```bash
+npx @juspay/neurolink loop
+```
+
+### Example Session
+
+```bash
+# Start the interactive session
+$ npx @juspay/neurolink loop
+
+neurolink » set provider google-ai
+✓ provider set to google-ai
+
+neurolink » set temperature 0.8
+✓ temperature set to 0.8
+
+neurolink » generate "Tell me a fun fact about space"
+The quietest place on Earth is an anechoic chamber at Microsoft's headquarters in Redmond, Washington. The background noise is so low that it's measured in negative decibels, and you can hear your own heartbeat.
+
+# Exit the session
+neurolink » exit
+```
+
+### Conversation Memory in Loop Mode
+
+Start the loop with conversation memory to have the AI remember the context of your previous commands.
 
 ```bash
 npx @juspay/neurolink loop --enable-conversation-memory
@@ -67,8 +263,11 @@ const neurolink = new NeuroLink({
 
 const result = await neurolink.generate({
   input: {
-    text: "Create a multimodal onboarding script",
-    images: ["./diagrams/architecture.png"],
+    text: "Create a comprehensive analysis",
+    files: [
+      "./sales_data.csv", // Auto-detected as CSV
+      "./diagrams/architecture.png", // Auto-detected as image
+    ],
   },
   enableEvaluation: true,
   region: "us-east-1",
@@ -82,15 +281,15 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 
 ## Platform Capabilities at a Glance
 
-| Capability               | Highlights                                                                                    |
-| ------------------------ | --------------------------------------------------------------------------------------------- |
-| **Provider unification** | 12+ providers with automatic fallback, cost-aware routing, provider orchestration (Q3).       |
-| **Multimodal pipeline**  | Stream images + text across providers with local/remote assets (Q3 2025).                     |
-| **Quality & governance** | Auto-evaluation engine (Q3), guardrails middleware (Q4), HITL workflows (Q4), audit logging.  |
-| **Memory & context**     | Conversation memory, Mem0 integration, Redis history export (Q4), context summarization (Q4). |
-| **CLI tooling**          | Loop sessions (Q3), setup wizard, config validation, Redis auto-detect, JSON output.          |
-| **Enterprise ops**       | Proxy support, regional routing (Q3), telemetry hooks, configuration management.              |
-| **Tool ecosystem**       | MCP auto discovery, LiteLLM hub access, SageMaker custom deployment, web search.              |
+| Capability               | Highlights                                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **Provider unification** | 12+ providers with automatic fallback, cost-aware routing, provider orchestration (Q3).                  |
+| **Multimodal pipeline**  | Stream images + CSV data across providers with local/remote assets. Auto-detection for mixed file types. |
+| **Quality & governance** | Auto-evaluation engine (Q3), guardrails middleware (Q4), HITL workflows (Q4), audit logging.             |
+| **Memory & context**     | Conversation memory, Mem0 integration, Redis history export (Q4), context summarization (Q4).            |
+| **CLI tooling**          | Loop sessions (Q3), setup wizard, config validation, Redis auto-detect, JSON output.                     |
+| **Enterprise ops**       | Proxy support, regional routing (Q3), telemetry hooks, configuration management.                         |
+| **Tool ecosystem**       | MCP auto discovery, LiteLLM hub access, SageMaker custom deployment, web search.                         |
 
 ## Documentation Map
 

package/dist/agent/directTools.d.ts

@@ -346,6 +346,61 @@ export declare const directAgentTools: {
             count?: undefined;
         }>;
     };
+    analyzeCSV: import("ai").Tool<z.ZodObject<{
+        filePath: z.ZodEffects<z.ZodString, string, string>;
+        operation: z.ZodEnum<["count_by_column", "sum_by_column", "average_by_column", "min_max_by_column", "describe"]>;
+        column: z.ZodOptional<z.ZodString>;
+        maxRows: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+        filePath: string;
+        maxRows?: number | undefined;
+        column?: string | undefined;
+    }, {
+        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+        filePath: string;
+        maxRows?: number | undefined;
+        column?: string | undefined;
+    }>, {
+        success: boolean;
+        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+        column: string | undefined;
+        result: string;
+        rowCount: number;
+    } | {
+        success: boolean;
+        error: string;
+        operation?: undefined;
+        column?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+        column: string | undefined;
+    }> & {
+        execute: (args: {
+            operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+            filePath: string;
+            maxRows?: number | undefined;
+            column?: string | undefined;
+        }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+            column: string | undefined;
+            result: string;
+            rowCount: number;
+        } | {
+            success: boolean;
+            error: string;
+            operation?: undefined;
+            column?: undefined;
+        } | {
+            success: boolean;
+            error: string;
+            operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+            column: string | undefined;
+        }>;
+    };
     websearchGrounding: import("ai").Tool<z.ZodObject<{
         query: z.ZodString;
         maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;

package/dist/agent/directTools.js

@@ -8,6 +8,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { logger } from "../utils/logger.js";
 import { VertexAI } from "@google-cloud/vertexai";
+import { CSVProcessor } from "../utils/csvProcessor.js";
 // Runtime Google Search tool creation - bypasses TypeScript strict typing
 function createGoogleSearchTools() {
     const searchTool = {};
@@ -336,6 +337,271 @@ export const directAgentTools = {
             }
         },
     }),
+    analyzeCSV: tool({
+        description: "Analyze CSV file for accurate counting, aggregation, and statistical analysis. Use this for precise data operations like counting rows by column, calculating sums/averages, finding min/max values, etc. The tool reads the file directly - do NOT pass CSV content.",
+        parameters: z.object({
+            filePath: z
+                .string()
+                .refine((inputPath) => {
+                const resolvedPath = path.resolve(inputPath);
+                const normalizedPath = resolvedPath
+                    .toLowerCase()
+                    .replace(/\\/g, "/");
+                const sensitivePatterns = [
+                    "/etc/",
+                    "/sys/",
+                    "/proc/",
+                    "/dev/",
+                    "/root/",
+                    "/.ssh/",
+                    "/private/etc/",
+                    "/private/var/",
+                    "c:/windows/",
+                    "c:/program files/",
+                    "c:/programdata/",
+                ];
+                return !sensitivePatterns.some((pattern) => normalizedPath.startsWith(pattern));
+            }, {
+                message: "Invalid file path: access to system directories is not allowed",
+            })
+                .describe("Path to the CSV file to analyze (e.g., 'test/data.csv' or '/absolute/path/file.csv')"),
+            operation: z
+                .enum([
+                "count_by_column",
+                "sum_by_column",
+                "average_by_column",
+                "min_max_by_column",
+                "describe",
+            ])
+                .describe("Type of analysis to perform"),
+            column: z
+                .string()
+                .optional()
+                .describe("Column name for the operation (required for most operations)"),
+            maxRows: z
+                .number()
+                .optional()
+                .describe("Maximum rows to process (default: 1000)"),
+        }),
+        execute: async ({ filePath, operation, column, maxRows = 1000 }) => {
+            const startTime = Date.now();
+            logger.info(`[analyzeCSV] 🚀 START: file=${filePath}, operation=${operation}, column=${column}, maxRows=${maxRows}`);
+            try {
+                // Resolve file path
+                logger.debug(`[analyzeCSV] Resolving file: ${filePath}`);
+                const path = await import("path");
+                // Resolve path (support both relative and absolute)
+                const resolvedPath = path.isAbsolute(filePath)
+                    ? filePath
+                    : path.resolve(process.cwd(), filePath);
+                logger.debug(`[analyzeCSV] Resolved path: ${resolvedPath}`);
+                // Parse CSV using streaming from disk (memory efficient)
+                logger.info(`[analyzeCSV] Starting CSV parsing (max ${maxRows} rows)...`);
+                const rows = (await CSVProcessor.parseCSVFile(resolvedPath, maxRows));
+                logger.info(`[analyzeCSV] ✅ CSV parsing complete: ${rows.length} rows`);
+                if (rows.length === 0) {
+                    logger.warn(`[analyzeCSV] No data rows found`);
+                    return {
+                        success: false,
+                        error: "No data rows found in CSV",
+                    };
+                }
+                // Log column names
+                const columnNames = rows.length > 0 ? Object.keys(rows[0]) : [];
+                logger.info(`[analyzeCSV] Found ${rows.length} rows with columns:`, columnNames);
+                logger.info(`[analyzeCSV] Executing operation: ${operation}`);
+                let result;
+                switch (operation) {
+                    case "count_by_column": {
+                        logger.info(`[analyzeCSV] count_by_column: column=${column}`);
+                        if (!column) {
+                            return {
+                                success: false,
+                                error: "Column name required for count_by_column operation",
+                            };
+                        }
+                        // Count occurrences of each value in the column
+                        const counts = {};
+                        logger.debug(`[analyzeCSV] Counting rows...`);
+                        for (const row of rows) {
+                            const value = row[column];
+                            if (value !== undefined) {
+                                counts[value] = (counts[value] || 0) + 1;
+                            }
+                        }
+                        logger.debug(`[analyzeCSV] Found ${Object.keys(counts).length} unique values`);
+                        // Sort by count descending
+                        logger.debug(`[analyzeCSV] Sorting results...`);
+                        result = Object.fromEntries(Object.entries(counts).sort(([, a], [, b]) => b - a));
+                        logger.info(`[analyzeCSV] ✅ count_by_column complete. Result:`, result);
+                        break;
+                    }
+                    case "sum_by_column": {
+                        logger.info(`[analyzeCSV] sum_by_column: column=${column}`);
+                        if (!column) {
+                            return {
+                                success: false,
+                                error: "Column name required for sum_by_column operation",
+                            };
+                        }
+                        // Sum numeric values from the target column itself for each group
+                        const groups = {};
+                        logger.debug(`[analyzeCSV] Grouping and summing ${rows.length} rows...`);
+                        let processedRows = 0;
+                        let totalNumericValuesFound = 0;
+                        for (const row of rows) {
+                            const key = row[column];
+                            if (!key) {
+                                continue;
+                            }
+                            // Parse numeric value from the target column
+                            const value = row[column];
+                            if (value === undefined || value === null || value === "") {
+                                continue;
+                            }
+                            const num = parseFloat(value);
+                            if (isNaN(num)) {
+                                continue;
+                            }
+                            if (!groups[key]) {
+                                groups[key] = 0;
+                            }
+                            groups[key] += num;
+                            totalNumericValuesFound++;
+                            processedRows++;
+                            if (processedRows % 10 === 0) {
+                                logger.debug(`[analyzeCSV] Processed ${processedRows}/${rows.length} rows`);
+                            }
+                        }
+                        // Fail fast if no numeric data found in the requested column
+                        if (totalNumericValuesFound === 0) {
+                            return {
+                                success: false,
+                                error: `No numeric data found in column "${column}" for sum_by_column operation`,
+                            };
+                        }
+                        logger.debug(`[analyzeCSV] Calculated sums for ${Object.keys(groups).length} groups (${totalNumericValuesFound} numeric values)`);
+                        result = groups;
+                        logger.info(`[analyzeCSV] ✅ sum_by_column complete`);
+                        break;
+                    }
+                    case "average_by_column": {
+                        logger.info(`[analyzeCSV] average_by_column: column=${column}`);
+                        if (!column) {
+                            return {
+                                success: false,
+                                error: "Column name required for average_by_column operation",
+                            };
+                        }
+                        // Average numeric values from the target column itself for each group
+                        const groups = {};
+                        logger.debug(`[analyzeCSV] Grouping and averaging ${rows.length} rows...`);
+                        let processedRows = 0;
+                        let totalNumericValuesFound = 0;
+                        for (const row of rows) {
+                            const key = row[column];
+                            if (!key) {
+                                continue;
+                            }
+                            // Parse numeric value from the target column
+                            const value = row[column];
+                            if (value === undefined || value === null || value === "") {
+                                continue;
+                            }
+                            const num = parseFloat(value);
+                            if (isNaN(num)) {
+                                continue;
+                            }
+                            if (!groups[key]) {
+                                groups[key] = { sum: 0, count: 0 };
+                            }
+                            groups[key].sum += num;
+                            groups[key].count++;
+                            totalNumericValuesFound++;
+                            processedRows++;
+                            if (processedRows % 10 === 0) {
+                                logger.debug(`[analyzeCSV] Processed ${processedRows}/${rows.length} rows`);
+                            }
+                        }
+                        // Fail fast if no numeric data found in the requested column
+                        if (totalNumericValuesFound === 0) {
+                            return {
+                                success: false,
+                                error: `No numeric data found in column "${column}" for average_by_column operation`,
+                            };
+                        }
+                        logger.debug(`[analyzeCSV] Calculated averages for ${Object.keys(groups).length} groups (${totalNumericValuesFound} numeric values)`);
+                        result = Object.fromEntries(Object.entries(groups).map(([k, v]) => [
+                            k,
+                            v.count > 0 ? v.sum / v.count : 0,
+                        ]));
+                        logger.info(`[analyzeCSV] ✅ average_by_column complete`);
+                        break;
+                    }
+                    case "min_max_by_column": {
+                        if (!column) {
+                            return {
+                                success: false,
+                                error: "Column name required for min_max_by_column operation",
+                            };
+                        }
+                        const values = rows
+                            .map((row) => row[column])
+                            .filter((v) => v !== undefined && v !== "");
+                        const numericValues = values
+                            .map((v) => parseFloat(v))
+                            .filter((n) => !isNaN(n));
+                        if (numericValues.length === 0) {
+                            return {
+                                success: false,
+                                error: `No numeric data found in column "${column}" for min_max_by_column operation`,
+                            };
+                        }
+                        result = {
+                            min: Math.min(...numericValues),
+                            max: Math.max(...numericValues),
+                            numericCount: numericValues.length,
+                            totalCount: values.length,
+                        };
+                        break;
+                    }
+                    case "describe": {
+                        const columnNames = rows.length > 0 ? Object.keys(rows[0]) : [];
+                        result = {
+                            total_rows: rows.length,
+                            columns: columnNames,
+                            column_count: columnNames.length,
+                        };
+                        break;
+                    }
+                    default:
+                        return {
+                            success: false,
+                            error: `Unknown operation: ${operation}`,
+                        };
+                }
+                const duration = Date.now() - startTime;
+                logger.info(`[analyzeCSV] 🏁 COMPLETE: ${operation} took ${duration}ms`);
+                const response = {
+                    success: true,
+                    operation,
+                    column,
+                    result: JSON.stringify(result, null, 2),
+                    rowCount: rows.length,
+                };
+                logger.debug(`[analyzeCSV] 📤 RETURNING TO LLM:`, JSON.stringify(response, null, 2));
+                return response;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    operation,
+                    column,
+                };
+            }
+        },
+    }),
     websearchGrounding: tool({
         description: "Search the web for current information using Google Search grounding. Returns raw search data for AI processing.",
         parameters: z.object({

package/dist/cli/factories/commandFactory.d.ts

@@ -6,6 +6,8 @@ export declare class CLICommandFactory {
     private static readonly commonOptions;
     private static buildOptions;
     private static processCliImages;
+    private static processCliCSVFiles;
+    private static processCliFiles;
     private static processOptions;
     private static handleOutput;
     private static isValidTokenUsage;