Agentic Data Science Assistant

CLI-first assistant for local CSV-style data analysis. It profiles a dataset, identifies data-quality issues, generates hypotheses, selects and runs an analysis path, creates chart artifacts, reviews analytical claims, and writes a Markdown report plus JSON artifacts.

Current status

Implemented:

• Python package scaffold and pytest setup.
• Domain schemas for runs, dataset profiles, hypotheses, plans, findings, visualizations, reports, and model configuration.
• Runtime/provider configuration for oMLX, OpenAI, and Ollama.
• Live provider preflight against OpenAI-compatible /models endpoints before analysis starts.
• User-facing dataset/provider failure messages with suggested actions.
• Dataset loading/profiling helpers with a local CSV size guard.
• Deterministic hypothesis generation, planning, pandas analysis, chart generation, and finding review fallbacks.
• Rationale, evidence, hypothesis/finding/chart traceability, limitation rendering, and unsupported-claim qualification.
• Markdown report and JSON artifact writing helpers.
• Unit, integration, contract, metric, and smoke validation for the MVP stories.

Not implemented yet:

• Full LLM prose generation beyond optional structured seams and deterministic fallback.
• Web UI, persistent database, multi-user workflows, or larger-than-memory dataset support.

Development setup

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m pytest -q

Copy .env.example to .env only for local provider settings. Do not commit real credentials.

CLI usage

Default local oMLX path:

ads-assistant run \
  --csv tests/fixtures/titanic_sample.csv \
  --goal "Find the strongest drivers of survival" \
  --output outputs/smoke-test

OpenAI option:

ads-assistant run \
  --csv tests/fixtures/titanic_sample.csv \
  --goal "Find the strongest drivers of survival" \
  --provider openai \
  --model gpt-4.1 \
  --output outputs/smoke-test-openai

Ollama option:

ads-assistant run \
  --csv tests/fixtures/titanic_sample.csv \
  --goal "Find the strongest drivers of survival" \
  --provider ollama \
  --model qwen2.5-coder:32b-instruct-q4_K_M \
  --output outputs/smoke-test-ollama

Expected successful output:

Analysis completed.
Provider: <provider>
Model: <model>
Report: <output>/report.md
Charts: <output>/charts
Artifacts: <output>/artifacts

Artifact layout

<output>/
  report.md
  charts/
    *.png
  artifacts/
    profile.json
    quality_issues.json
    hypotheses.json
    analysis_plan.json
    findings.json
    model_config.json

model_config.json contains non-secret provider metadata only. Credentials must remain in environment variables or CLI input and must not be committed.

Validation

Common checks:

python -m pytest tests/unit -q
python -m pytest tests/integration -q
python -m pytest tests/contract -q
python -m pytest tests/contract/test_cli_contract.py tests/integration/test_input_limits.py -q
python -m pytest tests/integration/test_quality_metric_suite.py tests/integration/test_hypothesis_relevance_metric.py tests/integration/test_claim_qualification_metric.py -q
python -m compileall -q src tests

Smoke run:

ads-assistant run \
  --csv tests/fixtures/titanic_sample.csv \
  --goal "Find the strongest drivers of survival" \
  --output outputs/smoke-test

Scope and limits

• MVP target: local, single-user CSV-style demo datasets with at least 100 rows and 5 columns.
• Runtime target: representative demo analysis completes within 5 minutes with a reachable configured provider.
• Default CSV size guard: 100 MiB (ADS_MAX_CSV_BYTES override for testing/local policy).
• Larger-than-memory datasets are out of scope and should be sampled or reduced before analysis.

Project docs

Feature docs live under:

• specs/001-data-science-assistant/spec.md
• specs/001-data-science-assistant/plan.md
• specs/001-data-science-assistant/tasks.md
• specs/001-data-science-assistant/contracts/cli.md
• specs/001-data-science-assistant/quickstart.md

Development principles

This project follows .specify/memory/constitution.md: code quality, automated tests, consistent UX, measurable performance, and explainable analytical outputs.