acumen-cli 0.1.0

Transform raw CSV datasets into executive-ready business insights using statistical analysis and LLMs via OpenRouter.

Acumen CLI

Transform raw CSV datasets into executive-ready business insights using statistical analysis and Large Language Models via OpenRouter.

pip install acumen-cli
acumen sales_data.csv

Features

• Load CSV files — Read any CSV with automatic encoding detection
• Validate datasets — Check for empty data, malformed rows, missing values
• Generate statistics — Descriptive stats per column: mean, median, std, quartiles, unique counts, missing values
• LLM-powered insights — Send only the statistical summary (never raw data) to OpenRouter for business-level analysis
• Beautiful terminal output — Rich-formatted tables, panels, and color-coded insights
• Privacy-first — Raw dataset rows never leave your machine

Installation

pip install acumen-cli

Or install from source:

git clone https://github.com/acumen-cli/acumen.git
cd acumen
pip install -e .

Quick Start

1. Set your OpenRouter API key:

export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

2. Run Acumen on any CSV file:

acumen dataset.csv

Options

Flag	Description
--model	LLM model to use (default: openai/gpt-4o-mini)
--verbose	Enable detailed logging
--version	Show version and exit
--help	Show help message

How It Works

CSV File → Validate → Statistics → JSON Summary → Prompt Builder → OpenRouter → Parse → Rich Output

1. Load — Reads CSV with encoding detection using chardet
2. Validate — Ensures dataset is non-empty, rows are consistent
3. Statistics — Computes descriptive statistics per column
4. JSON Summary — Builds a structured summary (no raw data)
5. Prompt — Constructs a focused prompt for the LLM
6. Analyze — Sends to OpenRouter for business insights
7. Display — Renders insights in a beautiful Rich terminal UI

Configuration

Acumen uses environment variables loaded from a .env file (optional).

Variable	Required	Default	Description
OPENROUTER_API_KEY	✅ Yes	—	Your OpenRouter API key
ACUMEN_MODEL	No	openai/gpt-4o-mini	LLM model identifier
ACUMEN_TIMEOUT	No	30	API timeout in seconds
ACUMEN_LOG_LEVEL	No	WARNING	Logging verbosity
ACUMEN_MAX_RETRIES	No	3	API retry attempts

Development

# Clone and install in editable mode
git clone https://github.com/acumen-cli/acumen.git
cd acumen
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check (requires pyright or mypy)
mypy src/

Architecture

Acumen CLI follows a clean, modular architecture:

• acumen/models/ — Data types and value objects
• acumen/orchestration/ — Pipeline orchestrator tying all steps together
• acumen/*.py — Each processing step is a standalone module

License

MIT