CSVBrain Natural Language Data Queries

CSVBrain

Version: 1.0.3 Author: @TheShadowRose License: MIT

Description

Load CSV files and ask questions in plain English. AI-powered natural language queries via Anthropic, OpenAI, or local Ollama. No SQL required.

CSVBrain parses CSV files (comma, semicolon, or tab-delimited), profiles your data automatically, and lets you query it with structured filters or plain English questions powered by AI.

Features

• CSV Loading — Parse CSV files with automatic delimiter detection (comma, semicolon, tab). Handles quoted fields and escaped quotes.
• Data Profiling — Instant statistics for every column: count, missing values, unique values, min/max/avg for numeric columns.
• Structured Queries — Filter, sort, limit, and aggregate your data programmatically.
• Natural Language Ask — Ask questions about your data in plain English. AI analyzes your dataset's structure, types, and statistics to give accurate answers with specific numbers.
• Multi-Provider AI — Route questions to Anthropic (Claude), OpenAI (GPT), or local Ollama models. Just change the model prefix.
• Zero Dependencies — Pure Node.js. No npm packages required. HTTP calls use built-in https/http modules.

Installation

Copy src/csv-brain.js into your project.

const { CSVBrain } = require('./src/csv-brain');

Quick Start

const { CSVBrain } = require('./src/csv-brain');

const brain = new CSVBrain();
const info = brain.load('sales.csv');
console.log(info);
// { rows: 1200, columns: 8, types: { month: 'text', revenue: 'number', ... } }

// Profile your data
const stats = brain.profile();
console.log(stats.revenue);
// { type: 'number', count: 1200, missing: 0, unique: 987, min: 12.5, max: 94200, avg: 8450.32 }

// Ask a question in plain English
const result = await brain.ask('What was our best month for revenue?');
console.log(result.answer);
// "Based on the data, March had the highest total revenue at $94,200."
console.log(result.model);
// "anthropic/claude-haiku-4-5"

API

new CSVBrain(options?)

Create a new instance.

const brain = new CSVBrain({ model: 'openai/gpt-4o-mini' });

load(filePath, options?)

Load a CSV file synchronously.

Returns: { rows: number, columns: number, types: object }

const info = brain.load('data.csv');
const info2 = brain.load('data.tsv', { delimiter: '\t' });

profile()

Get statistical profile of all columns.

Returns: Object keyed by column name, each with type, count, missing, unique, and (for numeric columns) min, max, avg.

const stats = brain.profile();
console.log(stats);

query(options)

Run a structured query against loaded data.

// Filter and sort
const topSales = brain.query({
  filter: { column: 'revenue', operator: '>', value: 10000 },
  sort: { column: 'revenue', order: 'desc' },
  limit: 10
});

// Aggregate
const totals = brain.query({
  aggregate: { column: 'revenue' }
});
console.log(totals);
// { count: 1200, sum: 10140384, avg: 8450.32, min: 12.5, max: 94200 }

async ask(question, options?)

Ask a natural language question about your data. Requires an AI provider API key (or local Ollama).

Returns: { answer: string, data: any, query: object|null, model: string }

// Using Anthropic (default)
// Requires ANTHROPIC_API_KEY environment variable
const result = await brain.ask('Which product category has the highest average price?');
console.log(result.answer);
// "Electronics has the highest average price at $342.50, followed by Appliances at $289.00."

// Using OpenAI
// Requires OPENAI_API_KEY environment variable
const result2 = await brain.ask('How many orders were placed in Q4?', {
  model: 'openai/gpt-4o-mini'
});

// Using local Ollama (no API key needed)
const result3 = await brain.ask('Summarize the sales trends', {
  model: 'ollama/llama3'
});

AI Provider Setup

Anthropic (Claude)

Set your API key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Models: anthropic/claude-haiku-4-5, anthropic/claude-sonnet-4-20250514, etc.

OpenAI (GPT)

export OPENAI_API_KEY="sk-..."

Models: openai/gpt-4o-mini, openai/gpt-4o, etc.

Ollama (Local)

No API key required. Just run Ollama locally:

ollama serve
ollama pull llama3

Models: ollama/llama3, ollama/mistral, etc.

Optionally set a custom host:

export OLLAMA_HOST="http://192.168.1.100:11434"

Error Handling

If the AI provider is unavailable, ask() returns a graceful error instead of throwing:

const result = await brain.ask('What is the trend?');
if (result.answer.startsWith('AI unavailable:')) {
  console.log('Falling back to manual query...');
  const data = brain.query({ sort: { column: 'date', order: 'asc' } });
}

Supported File Formats

• CSV — Comma-separated values (.csv)
• TSV — Tab-separated values (.tsv, .txt)
• Semicolon-delimited — Common in European locale exports

Delimiter is auto-detected from the first line, or can be specified manually.

Note: Excel files (.xlsx, .xls) are not supported. Export your spreadsheet to CSV first.

Limitations

• Files are loaded synchronously and fully into memory. Very large files (100MB+) may cause performance issues.
• AI answers depend on the quality and context window of the chosen model. Only column profiles and the first 5 sample rows are sent to the AI — not the entire dataset.
• No streaming support. The full AI response is returned at once.
• No built-in export functionality. Use query() results with your own file-writing logic.

Disclaimer

CSVBrain is provided as-is under the MIT License. AI-generated answers may not always be accurate — always verify critical data analysis. API usage may incur costs from your AI provider.

Support

• Issues: github.com/TheShadowRose/CSVBrain/issues
• Author: @TheShadowRose