Metadata-Version: 2.4
Name: acumen-cli
Version: 0.2.0
Summary: Transform raw CSV datasets into executive-ready business insights using statistical analysis and LLMs via OpenRouter.
Author: Acumen CLI Contributors
License: MIT
Project-URL: Homepage, https://github.com/acumen-cli/acumen
Project-URL: Repository, https://github.com/acumen-cli/acumen
Project-URL: Documentation, https://github.com/acumen-cli/acumen#readme
Keywords: csv,data-analysis,cli,llm,business-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.2.0
Requires-Dist: rich>=13.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: chardet>=5.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Dynamic: license-file

# Acumen CLI

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

```bash
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

```bash
pip install acumen-cli
```

Or install from source:

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

## Quick Start

1. Set your OpenRouter API key:

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

2. Run Acumen on any CSV file:

```bash
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

```bash
# 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
