InsightDispatch

Turn a CSV into an auditable statistical report, a presentation-ready chart, and an optional AI-assisted executive brief.

InsightDispatch is a local-first Python CLI for repeatable CSV analysis. It profiles data with pandas, creates a deterministic Matplotlib visualization, writes a Markdown report, and can optionally ask Groq for an executive interpretation or send the finished artifacts to Slack.

Why InsightDispatch?

• Local by default — reading, statistics, Markdown generation, and charting require no network service.
• Explicit input selection — pass a file directly, or place exactly one CSV in data/; it never silently chooses between multiple datasets.
• Privacy-aware AI — with --ai, Groq receives aggregate statistics rather than raw rows. Category labels are included in the Groq payload only when you explicitly add --share-category-values.
• Explicit Slack boundary — with --slack, Slack receives the complete local Markdown report, including its displayed leading category labels, plus the generated chart when available.
• Useful artifacts — each run produces a standalone Markdown report and, when possible, a high-resolution PNG chart.
• Optional delivery — Slack is used only with --slack; Groq is used only with --ai.
• Automation-friendly — typed modules, stable exit codes, offline tests, and a CI quality gate make the pipeline straightforward to extend.

How it works

CSV input
   │
   ├── Local pandas profile ──> Markdown evidence report
   │
   ├── Local Matplotlib chart ─> PNG dashboard
   │
   ├── --ai ───────────────────> Groq executive brief (aggregates only)
   │
   └── --slack ────────────────> Slack message + chart

For a mixed dataset, the chart shows the mean of the first alphabetically sorted numeric column by the first eligible categorical column. Numeric-only data produces a histogram; categorical-only data produces a count chart. This rule keeps repeated runs predictable.

Quick start

Requirements: Python 3.10 or newer.

git clone https://github.com/muhammadzain-byte/InsightDispatch.git
cd InsightDispatch
python -m venv .venv

Activate the environment:

# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install and run the included fictional sample:

python -m pip install --upgrade pip
python -m pip install -e .
insightdispatch examples/sample_sales.csv

Artifacts are written to output/sample_sales-report.md and output/sample_sales-chart.png. The legacy-friendly entry point also works:

python agent.py examples/sample_sales.csv

Command reference

insightdispatch [CSV] [options]

--data-dir PATH              Discovery directory when CSV is omitted (default: data)
--output-dir PATH            Artifact directory (default: output)
--delimiter CHAR             CSV delimiter (default: comma)
--max-rows N                 Row cap; 0 removes the cap (default: 100000)
--no-chart                   Skip PNG generation
--ai                         Add a Groq-generated executive brief
--model NAME                 Override GROQ_MODEL
--share-category-values      Include leading category labels in the AI payload
--slack                      Deliver the report and chart to Slack
--env-file PATH              Load a specific dotenv file instead of ./.env

If no CSV argument is supplied, automatic discovery succeeds only when data/ contains exactly one CSV. Multiple files cause an actionable error so a new file can never change which dataset is analyzed.

Optional Groq reports

Install the AI integration and create local configuration:

python -m pip install -e ".[ai]"
cp .env.example .env  # Windows: Copy-Item .env.example .env

Set GROQ_API_KEY in .env, then run:

insightdispatch data/quarterly-sales.csv --ai

The default model is openai/gpt-oss-20b. Set GROQ_MODEL in .env or pass --model to select another model available to your Groq project.

By default the request contains the filename, column names and types, missing/distinct counts, and numeric aggregates. It does not contain raw rows or categorical labels. Review column names and filenames for sensitive information before enabling AI. See Privacy and data handling for the exact boundary.

Optional Slack delivery

Install Slack support, then configure a bot token and target channel:

python -m pip install -e ".[slack]"

SLACK_BOT_TOKEN=xoxb-your-token
SLACK_CHANNEL_ID=C0123456789

Invite the bot to the destination channel and grant the app chat:write and files:write scopes. Then send a fully local report:

insightdispatch data/quarterly-sales.csv --slack

AI and Slack are independent; use both only when desired:

python -m pip install -e ".[ai,slack]"
insightdispatch data/quarterly-sales.csv --ai --slack

InsightDispatch validates that credentials exist but never prints token or API-key fragments. If a credential may have been exposed, revoke and rotate it at the provider immediately.

Project structure

.
├── src/insightdispatch/
│   ├── analysis.py       # CSV loading and local statistics
│   ├── charting.py       # Headless PNG generation
│   ├── cli.py            # Command-line interface
│   ├── config.py         # Environment configuration
│   ├── discovery.py      # Unambiguous file selection
│   ├── pipeline.py       # Workflow orchestration
│   ├── providers.py      # Opt-in Groq and Slack adapters
│   └── reporting.py      # Markdown and AI payloads
├── tests/                # Offline unit and integration tests
├── examples/             # Fictional sample data
├── agent.py              # Friendly source-checkout entry point
└── pyproject.toml        # Package, dependencies, and tooling

Development

python -m pip install -e ".[ai,slack,dev]"
ruff format --check .
ruff check .
pytest

Tests use fakes for Groq and Slack and make no network requests. Contributions are welcome; read CONTRIBUTING.md before opening a pull request.

Limits and responsible use

• The default 100,000-row cap keeps memory use predictable. The report clearly marks a truncated analysis; use --max-rows 0 only when the machine can hold the dataset in memory.
• Generated summaries are decision support, not a substitute for domain review. AI output can be incomplete or wrong.
• Slack and Groq are third-party services with their own retention and access policies.
• Local datasets, .env, and generated outputs are ignored by Git, but repository history should still be reviewed before publication.