csv-charts-ai 1.3.1 → 1.4.0

package/README.md

@@ -1,6 +1,8 @@
 # csv-charts-ai
 
-AI-powered chart generation and visualization for tabular data, built on [Recharts](https://recharts.org/) and the [Vercel AI SDK](https://sdk.vercel.ai/).
+AI-powered CSV analysis, chart generation, and interactive visualization. Built on the [Vercel AI SDK](https://sdk.vercel.ai/) and [Recharts](https://recharts.org/).
+
+**Works with any LLM provider** — OpenAI, Anthropic, Google, Mistral, Ollama, or any OpenAI-compatible endpoint.
 
 ## Installation
 
@@ -8,75 +10,112 @@ AI-powered chart generation and visualization for tabular data, built on [Rechar
 pnpm add csv-charts-ai ai zod
 ```
 
-Peer dependencies: `react`, `recharts`, `lucide-react`, `ai`, `zod`.
-
-## AI Chart Generation
+**Peer dependencies:** `ai`, `zod` (required). `react`, `recharts`, `lucide-react` (optional — only needed for React chart components).
 
-### Simple — OpenAI
+## Quick Start
 
 ```ts
-import { suggestCharts } from "csv-charts-ai";
+import { parseCSV, analyzeData, suggestQuestions } from "csv-charts-ai";
 
-const charts = await suggestCharts({
+// 1. 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
+const result = await analyzeData({
   model: { apiKey: "sk-...", model: "gpt-4o" },
-  data: myData,
-  dataSummary: "10,000 rows, columns: date, category, revenue, quantity...",
+  data,
 });
-```
 
-### Custom endpoint — Ollama / vLLM / LM Studio
+console.log(result.summary.keyInsights);
+console.log(`Found ${result.anomalies.length} anomalies`);
+console.log(`Generated ${result.charts.length} chart suggestions`);
 
-```ts
-const charts = await suggestCharts({
-  model: {
-    apiKey: "",
-    model: "llama3",
-    baseURL: "http://localhost:11434/v1",
-  },
-  data: myData,
-  dataSummary: "...",
+// 3. Suggest questions the user could ask
+const questions = await suggestQuestions({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
 });
+questions.forEach(q => console.log(`[${q.category}] ${q.question}`));
 ```
 
-### Other providers — Anthropic, Google, Mistral
+## CSV Parsing
+
+Parse CSV strings into the `TabularData` format with automatic delimiter detection and column type inference.
 
 ```ts
-// Dynamic import — install @ai-sdk/anthropic
-const charts = await suggestCharts({
-  model: { apiKey: "sk-ant-...", model: "claude-sonnet-4-20250514", provider: "anthropic" },
-  data: myData,
-  dataSummary: "...",
+import { parseCSV } from "csv-charts-ai";
+
+// Auto-detects delimiter (comma, semicolon, tab, pipe)
+const data = parseCSV(csvString);
+
+// Explicit options
+const data = parseCSV(csvString, {
+  delimiter: ";",
+  hasHeader: true,
+  skipEmpty: true,
 });
+
+console.log(data.headers);   // ["name", "age", "city"]
+console.log(data.rowCount);  // 100
+console.log(data.columns);   // [{ name: "name", type: "string", index: 0 }, ...]
 ```
 
-### Advanced — any LanguageModel
+**Type inference** detects `string`, `number`, `date`, and `boolean` columns by sampling values. Handles quoted fields, escaped quotes, multi-line values, and BOM stripping (RFC 4180).
+
+> For very large files or exotic encodings, consider using [PapaParse](https://www.papaparse.com/) and passing the result as `TabularData` directly.
+
+## AI Functions
+
+All AI functions accept either a simple config object or a pre-built `LanguageModel` from the Vercel AI SDK. All support an optional `signal` (AbortSignal) for cancellation.
+
+### Chart Suggestions
 
 ```ts
 import { suggestCharts } from "csv-charts-ai";
-import { anthropic } from "@ai-sdk/anthropic";
 
+// Simple — OpenAI
+const charts = await suggestCharts({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+});
+
+// Custom endpoint — Ollama / vLLM / LM Studio
+const charts = await suggestCharts({
+  model: { apiKey: "", model: "llama3", baseURL: "http://localhost:11434/v1" },
+  data,
+});
+
+// Other providers — Anthropic, Google, Mistral
+const charts = await suggestCharts({
+  model: { apiKey: "sk-ant-...", model: "claude-sonnet-4-20250514", provider: "anthropic" },
+  data,
+});
+
+// Advanced — any LanguageModel instance
+import { anthropic } from "@ai-sdk/anthropic";
 const charts = await suggestCharts({
   model: anthropic("claude-sonnet-4-20250514"),
-  data: myData,
-  dataSummary: "...",
+  data,
   language: "French",
 });
 ```
 
-### Generate a chart from a prompt
+### Custom Chart from Prompt
 
 ```ts
 import { suggestCustomChart } from "csv-charts-ai";
 
 const chart = await suggestCustomChart({
   model: { apiKey: "sk-...", model: "gpt-4o" },
-  data: myData,
-  dataSummary: "...",
+  data,
   prompt: "Show me a bar chart of revenue by category",
 });
 ```
 
-### Repair a broken chart
+### Repair a Broken Chart
 
 ```ts
 import { repairChart } from "csv-charts-ai";
@@ -89,9 +128,130 @@ const fixed = await repairChart({
 });
 ```
 
+### Data Summary
+
+```ts
+import { summarizeData } from "csv-charts-ai";
+
+const result = await summarizeData({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+});
+
+console.log(result.summary);      // "This dataset contains sales records..."
+console.log(result.keyInsights);   // ["Revenue peaks in Q4", "Product A leads..."]
+console.log(result.dataQuality);   // "Good completeness, 2 missing values in..."
+```
+
+### Anomaly Detection
+
+```ts
+import { detectAnomalies } from "csv-charts-ai";
+
+const anomalies = await detectAnomalies({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  maxRows: 100, // default: 50
+});
+
+anomalies.forEach(a =>
+  console.log(`[${a.severity}] Row ${a.row}, ${a.column}: ${a.issue}`)
+);
+```
+
+### Ask Questions About Data
+
+```ts
+import { askAboutData, streamAskAboutData } from "csv-charts-ai";
+
+// Non-streaming
+const answer = await askAboutData({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  question: "What is the average revenue by region?",
+  history: [{ prompt: "How many rows?", response: "There are 1000 rows." }],
+});
+
+// Streaming
+await streamAskAboutData({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  question: "What trends do you see?",
+  onChunk: (chunk) => process.stdout.write(chunk),
+  onComplete: (full) => console.log("\nDone:", full.length, "chars"),
+});
+```
+
+### Suggest Questions
+
+```ts
+import { suggestQuestions } from "csv-charts-ai";
+
+const questions = await suggestQuestions({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  count: 5,
+});
+
+questions.forEach(q => console.log(`[${q.category}] ${q.question}`));
+// [trend] How has revenue changed month over month?
+// [comparison] Which region has the highest average order value?
+// [correlation] Is there a relationship between marketing spend and sales?
+```
+
+### Full Analysis Pipeline
+
+Runs summary, anomaly detection, and chart suggestions in parallel:
+
+```ts
+import { analyzeData } from "csv-charts-ai";
+
+const result = await analyzeData({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  detectAnomalies: true,  // default: true
+  suggestCharts: true,    // default: true
+});
+
+// result.summary   — DataSummaryResult
+// result.anomalies — AnomalyResult[]
+// result.charts    — ChartConfig[]
+```
+
+## Cancellation (AbortSignal)
+
+All AI functions support `signal` for cancellation — essential for React cleanup and timeouts:
+
+```ts
+const controller = new AbortController();
+
+const charts = await suggestCharts({
+  model: { apiKey: "sk-...", model: "gpt-4o" },
+  data,
+  signal: controller.signal,
+});
+
+// Cancel from elsewhere
+controller.abort();
+```
+
+React example:
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  analyzeData({ model, data, signal: controller.signal })
+    .then(setResult)
+    .catch(() => {});
+  return () => controller.abort();
+}, [data]);
+```
+
 ## React Components
 
-### Display charts
+> **Requires** `react`, `recharts`, `lucide-react`, and **Tailwind CSS** for styling.
+
+### Display Charts
 
 ```tsx
 import { ChartDisplay } from "csv-charts-ai";
@@ -99,7 +259,7 @@ import { ChartDisplay } from "csv-charts-ai";
 <ChartDisplay data={data} charts={charts} />
 ```
 
-### With theme
+### With Theme
 
 ```tsx
 import { ChartDisplay, defaultLightTheme } from "csv-charts-ai";
@@ -107,32 +267,108 @@ import { ChartDisplay, defaultLightTheme } from "csv-charts-ai";
 <ChartDisplay data={data} charts={charts} theme={defaultLightTheme} />
 ```
 
-## Components
+### Custom Card Wrapper
+
+```tsx
+<ChartDisplay
+  data={data}
+  charts={charts}
+  cardWrapper={({ children, title }) => (
+    <div className="my-card">
+      <h2>{title}</h2>
+      {children}
+    </div>
+  )}
+  onRegenerate={async (chart) => {
+    const fixed = await repairChart({ model, failedChart: chart, columns: data.headers, errorContext: "Rendering failed" });
+    // update state with fixed chart
+  }}
+/>
+```
+
+### Unstyled Mode (No Tailwind Required)
+
+Pass `unstyled` to strip all built-in Tailwind classes and style components yourself:
+
+```tsx
+<ChartDisplay
+  data={data}
+  charts={charts}
+  unstyled
+  className="my-charts-container"
+  chartClassName="my-chart-card"
+  titleClassName="my-chart-title"
+/>
+```
+
+You can also pass `className` to any component to add classes alongside the built-in ones:
+
+```tsx
+<ChartDisplay data={data} charts={charts} className="my-extra-class" />
+```
+
+### Headless Usage (No React)
+
+The AI functions and CSV parsing work without React — use them in Node.js scripts, APIs, or CLI tools:
+
+```ts
+import { parseCSV, analyzeData } from "csv-charts-ai";
+import { readFileSync } from "fs";
+
+const csv = readFileSync("sales.csv", "utf-8");
+const data = parseCSV(csv);
+
+const result = await analyzeData({
+  model: { apiKey: process.env.OPENAI_API_KEY!, model: "gpt-4o" },
+  data,
+});
+
+console.log(result.summary.keyInsights);
+```
+
+## Components Reference
 
 | Export | Description |
 |--------|-------------|
 | `ChartDisplay` | Multi-chart container with optional card wrapper and theme |
 | `SingleChart` | Individual chart with toolbar (sort, zoom, trendline, CSV/PNG export) |
 | `ChartToolbar` | Standalone toolbar component |
-| `processChartData` | Data processing utility with aggregation |
-| `COLORS` | Default color palette |
 | `ChartThemeProvider` | React context for chart theming |
 | `defaultDarkTheme` / `defaultLightTheme` | Built-in themes |
 
-## AI Functions
+## AI Functions Reference
 
 | Export | Description |
 |--------|-------------|
 | `suggestCharts(options)` | Generate 2-4 chart suggestions from data |
 | `suggestCustomChart(options)` | Generate a single chart from a text prompt |
 | `repairChart(options)` | Fix a chart config that failed to render |
+| `summarizeData(options)` | AI-generated data summary with key insights |
+| `detectAnomalies(options)` | Find outliers, missing values, type mismatches |
+| `askAboutData(options)` | Ask natural language questions about data |
+| `streamAskAboutData(options)` | Streaming version of askAboutData |
+| `suggestQuestions(options)` | Suggest interesting questions to ask about the data |
+| `analyzeData(options)` | Full pipeline: summary + anomalies + charts in parallel |
+
+## Utilities Reference
+
+| Export | Description |
+|--------|-------------|
+| `parseCSV(csv, options?)` | Parse CSV string into `TabularData` |
+| `createModel(config)` | Create a LanguageModel from an AIConfig |
+| `resolveModel(input)` | Resolve AIConfig or LanguageModel to LanguageModel |
+| `summarizeTabularData(data)` | Generate text summary for AI consumption |
+| `getAIErrorMessage(error)` | Extract user-friendly error messages |
+| `processChartData(data, chart)` | Process and aggregate chart data |
+| `processChartDataMultiSeries(data, chart)` | Multi-series data processing |
+| `COLORS` | Default 8-color palette |
 
 ## Validation Schemas
 
 | Export | Description |
 |--------|-------------|
 | `AIConfigSchema` | Zod schema for validating AI config objects |
-| `TabularDataSchema` | Zod schema for validating tabular data input |
+| `TabularDataSchema` | Zod schema for validating TabularData input |
 
 ## Chart Types
 

package/dist/index.d.ts

@@ -52,6 +52,51 @@ interface ChartTheme {
 declare const defaultDarkTheme: ChartTheme;
 declare const defaultLightTheme: ChartTheme;
 
+interface ParseCSVOptions {
+    /** Column delimiter. Auto-detected if omitted (supports , ; \t |). */
+    delimiter?: string;
+    /** Whether the first row is a header row (default: true). */
+    hasHeader?: boolean;
+    /** Skip empty lines (default: true). */
+    skipEmpty?: boolean;
+}
+/**
+ * Parse a CSV string into TabularData with automatic delimiter detection
+ * and column type inference.
+ *
+ * Handles quoted fields (RFC 4180), escaped quotes, and mixed line endings.
+ *
+ * @example
+ * ```ts
+ * import { parseCSV } from "csv-charts-ai";
+ *
+ * const data = parseCSV(`name,age,city
+ * Alice,30,"New York"
+ * Bob,25,Paris`);
+ *
+ * console.log(data.headers);   // ["name", "age", "city"]
+ * console.log(data.rowCount);  // 2
+ * console.log(data.columns);   // [{ name: "name", type: "string", ... }, ...]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Auto-detects semicolon delimiter
+ * const data = parseCSV("nom;age;ville\nAlice;30;Paris");
+ *
+ * // Explicit delimiter
+ * const data = parseCSV(tsv, { delimiter: "\t" });
+ *
+ * // No header row
+ * const data = parseCSV(raw, { hasHeader: false });
+ * ```
+ *
+ * For very complex CSV files (multi-line quoted fields with nested newlines,
+ * exotic encodings), consider using PapaParse and passing the result as
+ * TabularData directly to the AI functions.
+ */
+declare function parseCSV(csv: string, options?: ParseCSVOptions): TabularData;
+
 interface ChartDisplayProps {
     data: TabularData;
     charts: ChartConfig[];
@@ -64,15 +109,29 @@ interface ChartDisplayProps {
     }>;
     /** 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, }: ChartDisplayProps): react_jsx_runtime.JSX.Element | null;
+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 }: SingleChartProps): react_jsx_runtime.JSX.Element;
+declare function SingleChart({ data, chart, onRegenerate, className, unstyled }: SingleChartProps): react_jsx_runtime.JSX.Element;
 
 interface ChartToolbarProps {
     chartType: ChartType;
@@ -89,8 +148,12 @@ interface ChartToolbarProps {
     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, }: ChartToolbarProps): react_jsx_runtime.JSX.Element;
+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;
@@ -173,6 +236,8 @@ interface SuggestChartsOptions {
     language?: string;
     /** Temperature for AI generation (default: 0.5) */
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 interface SuggestCustomChartOptions {
     /** The AI model — either a simple config or a LanguageModel instance */
@@ -187,6 +252,8 @@ interface SuggestCustomChartOptions {
     language?: string;
     /** Temperature (default: 0.5) */
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 interface RepairChartOptions {
     /** The AI model — either a simple config or a LanguageModel instance */
@@ -201,6 +268,8 @@ interface RepairChartOptions {
     language?: string;
     /** Temperature (default: 0.3) */
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 /**
  * Generate chart suggestions from tabular data using AI.
@@ -282,6 +351,8 @@ interface SummarizeDataOptions {
     dataSummary?: string;
     language?: string;
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 /**
  * Generate an AI summary of tabular data.
@@ -306,6 +377,8 @@ interface DetectAnomaliesOptions {
     maxRows?: number;
     language?: string;
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 /**
  * Detect anomalies in tabular data using AI.
@@ -332,6 +405,8 @@ interface AskAboutDataOptions {
     }>;
     language?: string;
     temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
 }
 /**
  * Ask a question about the data and get a text response.
@@ -347,9 +422,11 @@ interface AskAboutDataOptions {
  * ```
  */
 declare function askAboutData(options: AskAboutDataOptions): Promise<string>;
-interface StreamAskAboutDataOptions extends AskAboutDataOptions {
+interface StreamAskAboutDataOptions extends Omit<AskAboutDataOptions, "signal"> {
     onChunk: (chunk: string) => void;
     onComplete: (fullText: string) => void;
+    /** AbortSignal to cancel the stream */
+    signal?: AbortSignal;
 }
 /**
  * Ask a question with streaming response.
@@ -375,6 +452,8 @@ interface AnalyzeOptions {
     detectAnomalies?: boolean;
     /** Set to false to skip chart suggestions (default: true) */
     suggestCharts?: boolean;
+    /** AbortSignal to cancel all parallel requests */
+    signal?: AbortSignal;
 }
 /**
  * Run a complete AI analysis on tabular data in one call.
@@ -397,5 +476,38 @@ interface AnalyzeOptions {
  * ```
  */
 declare function analyzeData(options: AnalyzeOptions): Promise<AnalysisResult>;
+interface SuggestQuestionsOptions {
+    model: ModelInput;
+    data: TabularData;
+    dataSummary?: string;
+    language?: string;
+    /** Number of questions to suggest (default: 6) */
+    count?: number;
+    temperature?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+interface SuggestedQuestion {
+    question: string;
+    category: "trend" | "comparison" | "correlation" | "anomaly" | "insight";
+}
+/**
+ * Suggest interesting questions a user could ask about their data.
+ * Great for onboarding users who don't know where to start with their dataset.
+ *
+ * @example
+ * ```ts
+ * const questions = await suggestQuestions({
+ *   model: { apiKey: "sk-...", model: "gpt-4o" },
+ *   data: myData,
+ * });
+ *
+ * questions.forEach(q => console.log(`[${q.category}] ${q.question}`));
+ * // [trend] How has revenue changed over the last 6 months?
+ * // [comparison] Which product category generates the most revenue?
+ * // [correlation] Is there a relationship between price and quantity sold?
+ * ```
+ */
+declare function suggestQuestions(options: SuggestQuestionsOptions): Promise<SuggestedQuestion[]>;
 
-export { type AIConfig, AIConfigSchema, type AggregationType, type AnalysisResult, type AnalyzeOptions, type AnomalyResult, type AskAboutDataOptions, COLORS, type ChartConfig, type ChartDataPoint, ChartDisplay, type ChartDisplayProps, type ChartTheme, ChartThemeProvider, ChartToolbar, type ChartType, type DataSummaryResult, type DetectAnomaliesOptions, type ModelInput, type ProcessedChartResult, type RepairChartOptions, SingleChart, type SingleChartProps, type SortOrder, type StreamAskAboutDataOptions, type SuggestChartsOptions, type SuggestCustomChartOptions, type SummarizeDataOptions, type TabularData, TabularDataSchema, VERSION, analyzeData, askAboutData, createModel, defaultDarkTheme, defaultLightTheme, detectAnomalies, getAIErrorMessage, processChartData, processChartDataMultiSeries, repairChart, resolveModel, streamAskAboutData, suggestCharts, suggestCustomChart, summarizeData, summarizeTabularData, useChartTheme };
+export { type AIConfig, AIConfigSchema, type AggregationType, type AnalysisResult, type AnalyzeOptions, type AnomalyResult, type AskAboutDataOptions, COLORS, type ChartConfig, type ChartDataPoint, ChartDisplay, type ChartDisplayProps, type ChartTheme, ChartThemeProvider, ChartToolbar, type ChartType, type DataSummaryResult, type DetectAnomaliesOptions, type ModelInput, type ParseCSVOptions, type ProcessedChartResult, type RepairChartOptions, SingleChart, type SingleChartProps, type SortOrder, type StreamAskAboutDataOptions, type SuggestChartsOptions, type SuggestCustomChartOptions, type SuggestQuestionsOptions, type SuggestedQuestion, type SummarizeDataOptions, type TabularData, TabularDataSchema, VERSION, analyzeData, askAboutData, createModel, defaultDarkTheme, defaultLightTheme, detectAnomalies, getAIErrorMessage, parseCSV, processChartData, processChartDataMultiSeries, repairChart, resolveModel, streamAskAboutData, suggestCharts, suggestCustomChart, suggestQuestions, summarizeData, summarizeTabularData, useChartTheme };