csv-charts-ai 1.8.0 → 1.10.0

package/README.md

@@ -7,23 +7,39 @@ AI-powered CSV analysis, chart generation, and interactive visualization. Built
 ## Installation
 
 ```bash
-pnpm add csv-charts-ai ai zod
+pnpm add csv-charts-ai
 ```
 
-**Peer dependencies:** `ai`, `zod` (required). `react`, `recharts`, `lucide-react` (optional — only needed for React chart components).
+Then install **only the AI provider(s) you need**:
+
+```bash
+# Pick one or more
+pnpm add @ai-sdk/openai      # OpenAI / OpenAI-compatible (Ollama, vLLM, LM Studio…)
+pnpm add @ai-sdk/anthropic    # Anthropic
+pnpm add @ai-sdk/google       # Google Generative AI
+pnpm add @ai-sdk/mistral      # Mistral
+```
+
+Core dependencies (`ai`, `zod`, `read-excel-file`) are bundled. AI provider SDKs are **optional peer dependencies** — you only install what you use.
+
+**Optional peer dependencies** (only for React chart components): `react`, `recharts`, `lucide-react`.
 
 ## Quick Start
 
 ```ts
-import { parseCSV, analyzeData, suggestQuestions } from "csv-charts-ai";
+import { registerProvider, fromSDK, parseCSV, analyzeData, suggestQuestions } from "csv-charts-ai";
+import { createOpenAI } from "@ai-sdk/openai";
+
+// 1. Register your provider(s) — once, at app startup
+registerProvider("openai", fromSDK(createOpenAI));
 
-// 1. Parse CSV string into structured data
+// 2. Parse CSV string into structured data
 const data = parseCSV(`name,age,city,salary
 Alice,30,Paris,75000
 Bob,25,London,62000
 Charlie,35,Berlin,88000`);
 
-// 2. Run full AI analysis (summary + anomalies + charts) in parallel
+// 3. Run full AI analysis (summary + anomalies + charts) in parallel
 const result = await analyzeData({
   model: { apiKey: "sk-...", model: "gpt-4o" },
   data,
@@ -33,7 +49,7 @@ console.log(result.summary.keyInsights);
 console.log(`Found ${result.anomalies.length} anomalies`);
 console.log(`Generated ${result.charts.length} chart suggestions`);
 
-// 3. Suggest questions the user could ask
+// 4. Suggest questions the user could ask
 const questions = await suggestQuestions({
   model: { apiKey: "sk-...", model: "gpt-4o" },
   data,
@@ -41,6 +57,56 @@ const questions = await suggestQuestions({
 questions.forEach(q => console.log(`[${q.category}] ${q.question}`));
 ```
 
+## Provider Setup
+
+Register AI providers **once** at app startup, before calling any AI function. You only install and register the providers you need.
+
+### Using `@ai-sdk/*` packages
+
+The `fromSDK()` helper wraps any `@ai-sdk/*` creator into the format the library expects:
+
+```ts
+import { registerProvider, fromSDK } from "csv-charts-ai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createMistral } from "@ai-sdk/mistral";
+
+registerProvider("openai", fromSDK(createOpenAI));
+registerProvider("anthropic", fromSDK(createAnthropic));
+registerProvider("google", fromSDK(createGoogleGenerativeAI));
+registerProvider("mistral", fromSDK(createMistral));
+```
+
+### Custom / self-hosted providers
+
+For full control, pass a `ProviderFactory` directly — a function that receives `{ apiKey, model, baseURL?, headers? }` and returns a `LanguageModel`:
+
+```ts
+import { registerProvider } from "csv-charts-ai";
+
+registerProvider("my-llm", (config) => {
+  return myCustomSDK.createModel(config.apiKey, config.model);
+});
+```
+
+### Batch registration
+
+```ts
+import { registerProviders, fromSDK } from "csv-charts-ai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+registerProviders({
+  openai: fromSDK(createOpenAI),
+  anthropic: fromSDK(createAnthropic),
+});
+```
+
+### Aliases
+
+npm package names are resolved automatically — `"@ai-sdk/openai"` and `"openai"` map to the same slot. So `createModel({ provider: "openai" })` and `createAppModel({ providerNpm: "@ai-sdk/openai" })` both work after a single registration.
+
 ## CSV Parsing
 
 Parse CSV strings into the `TabularData` format with automatic delimiter detection and column type inference.
@@ -69,11 +135,7 @@ console.log(data.columns);   // [{ name: "name", type: "string", index: 0 }, ...
 
 ## XLSX Parsing
 
-Parse Excel (.xlsx) files into the same `TabularData` format. Requires `read-excel-file` as an optional peer dependency.
-
-```bash
-pnpm add read-excel-file
-```
+Parse Excel (.xlsx) files into the same `TabularData` format. `read-excel-file` is bundled.
 
 ### Browser
 
@@ -107,13 +169,13 @@ All AI functions accept either a simple config object or a pre-built `LanguageMo
 ```ts
 import { suggestCharts } from "csv-charts-ai";
 
-// Simple — OpenAI
+// Simple — OpenAI (provider must be registered, see Provider Setup)
 const charts = await suggestCharts({
   model: { apiKey: "sk-...", model: "gpt-4o" },
   data,
 });
 
-// Custom endpoint — Ollama / vLLM / LM Studio
+// Custom endpoint — Ollama / vLLM / LM Studio (uses the "openai" provider)
 const charts = await suggestCharts({
   model: { apiKey: "", model: "llama3", baseURL: "http://localhost:11434/v1" },
   data,
@@ -125,8 +187,9 @@ const charts = await suggestCharts({
   data,
 });
 
-// Advanced — any LanguageModel instance
-import { anthropic } from "@ai-sdk/anthropic";
+// Advanced — any LanguageModel instance (no registration needed)
+import { createAnthropic } from "@ai-sdk/anthropic";
+const anthropic = createAnthropic({ apiKey: "sk-ant-..." });
 const charts = await suggestCharts({
   model: anthropic("claude-sonnet-4-20250514"),
   data,
@@ -278,14 +341,19 @@ useEffect(() => {
 }, [data]);
 ```
 
-## React Components
+## React Components (`csv-charts-ai/charts`)
 
-> **Requires** `react`, `recharts`, `lucide-react`, and **Tailwind CSS** for styling.
+Chart components are available as a **separate entry point** so projects that only need AI/parsing don't pull in React, Recharts, or Lucide.
+
+```bash
+# Optional peer dependencies — only needed if you import from csv-charts-ai/charts
+pnpm add react recharts lucide-react
+```
 
 ### Display Charts
 
 ```tsx
-import { ChartDisplay } from "csv-charts-ai";
+import { ChartDisplay } from "csv-charts-ai/charts";
 
 <ChartDisplay data={data} charts={charts} />
 ```
@@ -293,7 +361,7 @@ import { ChartDisplay } from "csv-charts-ai";
 ### With Theme
 
 ```tsx
-import { ChartDisplay, defaultLightTheme } from "csv-charts-ai";
+import { ChartDisplay, defaultLightTheme } from "csv-charts-ai/charts";
 
 <ChartDisplay data={data} charts={charts} theme={defaultLightTheme} />
 ```
@@ -301,6 +369,9 @@ import { ChartDisplay, defaultLightTheme } from "csv-charts-ai";
 ### Custom Card Wrapper
 
 ```tsx
+import { ChartDisplay } from "csv-charts-ai/charts";
+import { repairChart } from "csv-charts-ai";
+
 <ChartDisplay
   data={data}
   charts={charts}
@@ -340,12 +411,15 @@ You can also pass `className` to any component to add classes alongside the buil
 
 ### Headless Usage (No React)
 
-The AI functions and CSV parsing work without React — use them in Node.js scripts, APIs, or CLI tools:
+The core entry point (`csv-charts-ai`) works without React — use it in Node.js scripts, APIs, or CLI tools:
 
 ```ts
-import { parseCSV, analyzeData } from "csv-charts-ai";
+import { registerProvider, fromSDK, parseCSV, analyzeData } from "csv-charts-ai";
+import { createOpenAI } from "@ai-sdk/openai";
 import { readFileSync } from "fs";
 
+registerProvider("openai", fromSDK(createOpenAI));
+
 const csv = readFileSync("sales.csv", "utf-8");
 const data = parseCSV(csv);
 
@@ -357,7 +431,7 @@ const result = await analyzeData({
 console.log(result.summary.keyInsights);
 ```
 
-## Components Reference
+## Components Reference (`csv-charts-ai/charts`)
 
 | Export | Description |
 |--------|-------------|
@@ -381,16 +455,30 @@ console.log(result.summary.keyInsights);
 | `suggestQuestions(options)` | Suggest interesting questions to ask about the data |
 | `analyzeData(options)` | Full pipeline: summary + anomalies + charts in parallel |
 
+## Provider Registry Reference
+
+| Export | Description |
+|--------|-------------|
+| `registerProvider(name, factory)` | Register a provider by name |
+| `registerProviders(map)` | Register multiple providers at once |
+| `fromSDK(creator)` | Wrap an `@ai-sdk/*` creator into a `ProviderFactory` |
+| `getProvider(name)` | Get a registered provider (or `undefined`) |
+| `hasProvider(name)` | Check if a provider is registered |
+| `clearProviders()` | Remove all registered providers (for testing) |
+
 ## Utilities Reference
 
 | Export | Description |
 |--------|-------------|
 | `parseCSV(csv, options?)` | Parse CSV string into `TabularData` |
-| `parseXLSX(file, options?)` | Parse XLSX file into `TabularData` (browser, requires `read-excel-file`) |
-| `convertXLSXRows(rows, options?)` | Convert raw XLSX rows into `TabularData` (universal, zero deps) |
+| `parseXLSX(file, options?)` | Parse XLSX file into `TabularData` (browser) |
+| `convertXLSXRows(rows, options?)` | Convert raw XLSX rows into `TabularData` (universal) |
+| `computeDiff(dataA, dataB, options)` | Compare two datasets (index, key, or content matching) |
 | `createModel(config)` | Create a LanguageModel from an AIConfig |
-| `resolveModel(input)` | Resolve AIConfig or LanguageModel to LanguageModel |
-| `summarizeTabularData(data)` | Generate text summary for AI consumption |
+| `createAppModel(config)` | Create a LanguageModel from multi-provider app config |
+| `resolveModel(input)` | Resolve AIConfig, AppModelConfig, or LanguageModel |
+| `generateDataSummary(data)` | Detailed human-readable data summary with sample rows |
+| `summarizeTabularData(data)` | Compact data summary for AI prompt consumption |
 | `getAIErrorMessage(error)` | Extract user-friendly error messages |
 | `processChartData(data, chart)` | Process and aggregate chart data |
 | `processChartDataMultiSeries(data, chart)` | Multi-series data processing |
@@ -413,16 +501,38 @@ Multi-series supported via `groupBy` for bar, line, and area charts.
 
 `sum` | `avg` | `count` | `min` | `max` | `none`
 
+## CSV Diff
+
+Compare two datasets and detect added, removed, and changed rows:
+
+```ts
+import { computeDiff } from "csv-charts-ai";
+
+const diff = computeDiff(dataA, dataB, { matchMode: "key", keyColumn: "id" });
+
+console.log(diff.counts); // { same: 10, changed: 3, added: 2, removed: 1 }
+diff.rows.forEach(r => {
+  if (r.status === "changed") {
+    console.log(`Row ${r.indexA}: changed columns: ${[...r.changedCols].join(", ")}`);
+  }
+});
+```
+
+Match modes: `"index"` (positional), `"key"` (by column value), `"content"` (full row match).
+
 ## Provider Support
 
-| Provider | Config | Extra install |
-|----------|--------|---------------|
-| OpenAI | `{ apiKey, model }` | None (bundled) |
-| Ollama / vLLM / LM Studio | `{ apiKey: "", model, baseURL }` | None |
-| Mistral (via OpenAI compat) | `{ apiKey, model, baseURL: "https://api.mistral.ai/v1" }` | None |
-| Anthropic | `{ provider: "anthropic", apiKey, model }` | `@ai-sdk/anthropic` |
-| Google | `{ provider: "google", apiKey, model }` | `@ai-sdk/google` |
-| Any LanguageModel | Pass instance directly | Provider SDK |
+Install only the provider(s) you need and register them at startup (see [Provider Setup](#provider-setup)).
+
+| Provider | Install | Config |
+|----------|---------|--------|
+| OpenAI | `@ai-sdk/openai` | `{ apiKey, model }` |
+| Anthropic | `@ai-sdk/anthropic` | `{ provider: "anthropic", apiKey, model }` |
+| Google | `@ai-sdk/google` | `{ provider: "google", apiKey, model }` |
+| Mistral | `@ai-sdk/mistral` | `{ provider: "mistral", apiKey, model }` |
+| Ollama / vLLM / LM Studio | `@ai-sdk/openai` | `{ apiKey: "", model, baseURL }` |
+| Custom provider | — | `registerProvider("name", factory)` |
+| Any LanguageModel | — | Pass instance directly |
 
 ## License
 

package/dist/charts.d.ts

@@ -0,0 +1,69 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { T as TabularData, C as ChartConfig, c as ChartTheme, d as ChartType, S as SortOrder } from './constants-hUsrIT8W.js';
+export { A as AggregationType, a as COLORS, b as ChartDataPoint, P as ProcessedChartResult, e as defaultDarkTheme, f as defaultLightTheme, p as processChartData, g as processChartDataMultiSeries } from './constants-hUsrIT8W.js';
+
+interface ChartDisplayProps {
+    data: TabularData;
+    charts: ChartConfig[];
+    onRegenerate?: (chart: ChartConfig) => Promise<void>;
+    /** Optional wrapper component for each chart card */
+    cardWrapper?: React.ComponentType<{
+        children: React.ReactNode;
+        title?: string;
+        className?: string;
+    }>;
+    /** Optional theme override */
+    theme?: ChartTheme;
+    /** Additional CSS class for the outer container */
+    className?: string;
+    /** Additional CSS class for each chart card */
+    chartClassName?: string;
+    /** Additional CSS class for chart title */
+    titleClassName?: string;
+    /** Additional CSS class for chart description */
+    descriptionClassName?: string;
+    /** When true, removes all built-in Tailwind classes. You must style everything yourself. */
+    unstyled?: boolean;
+}
+declare function ChartDisplay({ data, charts, onRegenerate, cardWrapper: CardWrapper, theme, className, chartClassName, titleClassName, descriptionClassName, unstyled, }: ChartDisplayProps): react_jsx_runtime.JSX.Element | null;
+
+interface SingleChartProps {
+    data: TabularData;
+    chart: ChartConfig;
+    onRegenerate?: (chart: ChartConfig) => Promise<void>;
+    /** Additional CSS class for the chart container */
+    className?: string;
+    /** When true, removes all built-in Tailwind classes from toolbar and metadata tags */
+    unstyled?: boolean;
+}
+declare function SingleChart({ data, chart, onRegenerate, className, unstyled }: SingleChartProps): react_jsx_runtime.JSX.Element;
+
+interface ChartToolbarProps {
+    chartType: ChartType;
+    sortOrder: SortOrder;
+    limitResults: number;
+    showBrush: boolean;
+    showTrendline: boolean;
+    isRegenerating: boolean;
+    hasRegenerate: boolean;
+    onToggleSort: () => void;
+    onLimitChange: (limit: number) => void;
+    onToggleBrush: () => void;
+    onToggleTrendline: () => void;
+    onExportCSV: () => void;
+    onExportPNG: () => void;
+    onRegenerate: () => void;
+    /** Additional CSS class for the toolbar container */
+    className?: string;
+    /** When true, removes all built-in Tailwind classes */
+    unstyled?: boolean;
+}
+declare function ChartToolbar({ chartType, sortOrder, limitResults, showBrush, showTrendline, isRegenerating, hasRegenerate, onToggleSort, onLimitChange, onToggleBrush, onToggleTrendline, onExportCSV, onExportPNG, onRegenerate, className, unstyled, }: ChartToolbarProps): react_jsx_runtime.JSX.Element;
+
+declare function ChartThemeProvider({ theme, children, }: {
+    theme: ChartTheme;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useChartTheme(): ChartTheme;
+
+export { ChartConfig, ChartDisplay, type ChartDisplayProps, ChartTheme, ChartThemeProvider, ChartToolbar, ChartType, SingleChart, type SingleChartProps, SortOrder, TabularData, useChartTheme };