Metadata-Version: 2.5
Name: jack-data-science-agent
Version: 4.3.2
Summary: An Evidence-Grounded Autonomous Data Science System — from natural language to reproducible analysis
Project-URL: Homepage, https://github.com/Jackxiaozhiren/data-science-agent
Project-URL: Repository, https://github.com/Jackxiaozhiren/data-science-agent
Project-URL: Documentation, https://github.com/Jackxiaozhiren/data-science-agent/blob/main/docs/getting-started.md
Project-URL: Changelog, https://github.com/Jackxiaozhiren/data-science-agent/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Jackxiaozhiren/data-science-agent/issues
Author-email: Data Science Agent Contributors <jackxiaozhiren@users.noreply.github.com>
Maintainer-email: Data Science Agent Maintainers <jackxiaozhiren@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: agent,benchmark,data-science,duckdb,evidence,llm,mcp,polars,reproducibility
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: duckdb>=1.0
Requires-Dist: fastapi>=0.110
Requires-Dist: greenlet>=3.5.5
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph>=0.2
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: openpyxl>=3.1
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.7
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.12
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev-jupyter
Requires-Dist: ipykernel>=6.0; extra == 'dev-jupyter'
Requires-Dist: ipython>=8.0; extra == 'dev-jupyter'
Requires-Dist: jupyterlab>=4.0; extra == 'dev-jupyter'
Requires-Dist: nest-asyncio>=1.5; extra == 'dev-jupyter'
Provides-Extra: jupyter
Requires-Dist: ipykernel>=6.0; extra == 'jupyter'
Requires-Dist: ipython>=8.0; extra == 'jupyter'
Requires-Dist: nest-asyncio>=1.5; extra == 'jupyter'
Provides-Extra: time-series
Requires-Dist: statsmodels>=0.14; extra == 'time-series'
Description-Content-Type: text/markdown

<div align="center">

# Data Science Agent

### The AI data scientist that shows its work.

Ask questions about CSV files and databases in natural language. DSA runs SQL, statistics, machine learning, and visualization, then returns **claim-level evidence, a reproducible report, and the artifacts needed to inspect how each conclusion was produced**.

[**Try Live Demo**](https://data-science-agent-web.vercel.app/datasets) ·
[**Product Tour**](https://jackxiaozhiren.github.io/data-science-agent/) ·
[**60-second quickstart**](#-60-second-quickstart) ·
[**Install from PyPI**](https://pypi.org/project/jack-data-science-agent/) ·
[**Case studies**](case-studies/) ·
[**Evaluation**](docs/evaluation.md) ·
[**Docs**](docs/getting-started.md) ·
[**v4.3.0**](https://github.com/Jackxiaozhiren/data-science-agent/releases/tag/v4.3.0)

[![PyPI](https://img.shields.io/pypi/v/jack-data-science-agent?logo=pypi&logoColor=white)](https://pypi.org/project/jack-data-science-agent/)
[![Latest release](https://img.shields.io/github/v/release/Jackxiaozhiren/data-science-agent?logo=github&label=release)](https://github.com/Jackxiaozhiren/data-science-agent/releases/latest)
[![Python](https://img.shields.io/pypi/pyversions/jack-data-science-agent?logo=python&logoColor=white)](https://pypi.org/project/jack-data-science-agent/)
[![License](https://img.shields.io/github/license/Jackxiaozhiren/data-science-agent)](LICENSE)

<br />

<img src="docs/assets/hero.svg" alt="Data Science Agent — Ask your data. Verify the answer." width="100%" />

**For analysts, researchers, and ML engineers who need answers they can inspect, audit, reproduce, and challenge.**

Live browser demo: [upload a dataset and run DSA](https://data-science-agent-web.vercel.app/datasets) · Static artifact tour: [browse verified runs](https://jackxiaozhiren.github.io/data-science-agent/)

</div>

---

## Why DSA?

Most AI data-analysis tools stop at the answer.

**Data Science Agent is built to preserve the path from a claim back to the computation and dataset that produced it.**

```text
Question
   ↓
Executed analysis
   ↓
Evidence
   ↓
Claim
   ↓
Reproducible report
```

That means an analysis can be **inspected, audited, reproduced, and challenged** instead of accepted on confidence alone.

> **If an AI makes a data-science claim, you should be able to inspect how it got there.**

---

## ⚡ 60-second quickstart

Install:

```bash
pip install jack-data-science-agent
```

Run the built-in demo:

```bash
dsa demo
```

Analyze your own data:

```bash
dsa analyze sales.csv \
  --task "Which factors explain revenue, and are the effects statistically significant?"
```

Python **3.12+** is required.

A successful run produces more than chat output:

```text
analysis run
├── report.md
├── experiment.json
├── evidence_graph.json
├── analysis.ipynb
└── reproduce.sh
```

| Artifact | Purpose |
|---|---|
| `report.md` | Human-readable findings |
| `experiment.json` | Structured run metadata |
| `evidence_graph.json` | Claim → evidence → computation lineage |
| `analysis.ipynb` | Inspectable notebook representation |
| `reproduce.sh` | Re-run the analysis |

### Hosted browser demo

The verified public demo is available at **[data-science-agent-web.vercel.app](https://data-science-agent-web.vercel.app/datasets)**. It runs the Next.js web interface on Vercel and the FastAPI analysis service on Render.

The demo supports the core product flow:

```text
Upload CSV / Excel
      ↓
Inspect dataset
      ↓
Ask a natural-language question
      ↓
Planner selects analysis tools
      ↓
Statistics / ML / visualization execute
      ↓
Evidence is verified
      ↓
Validation + report
```

A useful smoke-test question is:

> Explain which features are most important for revenue, test whether the main associations are statistically significant, assess the impact of campaign_group on the outcome, and clearly distinguish association from causation. Include a visualization.

The hosted preview intentionally runs in deterministic heuristic/offline mode, so it does not require or expose a model API key. The public Render instance uses ephemeral local storage: **uploaded datasets and generated artifacts are temporary and may disappear after a restart or redeploy, so re-upload the dataset if it is no longer listed.** A free instance may also need a short cold-start period after inactivity.

See [Hosted Demo Deployment](docs/hosted-demo.md) for the deployment topology, environment variables, and limitations.

### Where DSA fits

| You are... | DSA helps you... |
|---|---|
| **Analyst** | move from a natural-language question to SQL, statistics, plots, and an auditable report |
| **Researcher** | preserve dataset hashes, evidence lineage, and reproduction artifacts alongside conclusions |
| **ML engineer / data scientist** | run regression, classification, forecasting, and evaluation inside one inspectable workflow |

---

## See it in action

**Interactive path: [Try the live hosted demo →](https://data-science-agent-web.vercel.app/datasets)**

**Artifact-only path: [Open the verified Product Tour →](https://jackxiaozhiren.github.io/data-science-agent/)**

The Product Tour is a static view of repository artifacts from verified DSA runs. It does not accept uploads or pretend to be a live hosted model/API service. The live demo is separate and is explicitly labeled as a temporary public preview.

<div align="center">

<img src="docs/assets/demo.svg" alt="Data Science Agent terminal demo: profile, plan, execute, build evidence, check claims, and generate a reproducible report" width="92%" />

<sub>Question → profile → plan → tools → evidence → critic → reproducible report.</sub>

</div>

### Start with 3 flagship workflows

| Workflow | Ask DSA | What it demonstrates |
|---|---|---|
| **[Sales analytics](case-studies/01-sales/)** | What drives revenue across regions and categories? | SQL + statistics → evidence → reproducible report |
| **[Time-series forecasting](case-studies/03-time-series/)** | What are the next 30 values, and how well does the baseline forecast perform? | Forecasting, holdout evaluation, reproducibility, and visible failure recovery |
| **[ML classification](case-studies/08-classification/)** | Can DSA train, evaluate, and explain an imbalanced classifier? | Model evaluation + feature importance inside the same provenance trail |

**[Browse all 8 verified case studies →](case-studies/)**

These are verified repository workflows intended to show product behavior and evidence artifacts. They are **not** presented as independent real-LLM leaderboard results.

---

## What makes DSA different?

### 1. Claim-level evidence

Supported findings can be connected to the analysis that produced them:

```text
Claim
└── statistical result
    └── executed tool
        └── parameters
            └── dataset SHA-256
```

### 2. Reproducibility by default

DSA records run metadata and reproduction artifacts instead of treating the final prose answer as the only output.

### 3. Evidence-aware critique

A critic stage checks whether conclusions go beyond available evidence. Causal language can be rejected when the underlying analysis only supports association.

### 4. Statistical and modeling guardrails

The current analysis path can select semantic outcome/treatment columns, run significance tests, encode categorical features for RandomForest importance, exclude exact target copies from feature importance, and preserve an explicit association-vs-causation boundary.

### 5. Real data-science tools

Core workflows can coordinate:

- dataset profiling and exploratory analysis
- SQL with DuckDB
- correlation and hypothesis testing
- regression and classification
- forecasting and feature importance
- visualization
- report generation

### 6. One runtime, multiple interfaces

| Surface | Entry point |
|---|---|
| CLI | `dsa <command>` |
| Python SDK | `from data_science_agent import Agent` |
| REST API | FastAPI |
| Streaming | Server-Sent Events |
| MCP | MCP server |
| Jupyter | `%load_ext dsa_jupyter` |
| VS Code | Dataset explorer + analysis replay |
| Plugins | Custom data-science tools |

---

## Python SDK

```python
import asyncio
from data_science_agent import Agent

async def main():
    result = await Agent().analyze(
        "sales.csv",
        "Which region drives the most revenue, and is the trend statistically significant?",
    )

    print(result.report_markdown)

asyncio.run(main())
```

Inspect evidence programmatically:

```python
for evidence in result.evidence:
    print(evidence.claim)
    print(evidence.source_id)
    print(evidence.result)
```

---

## Evaluation

DSA is developed against versioned benchmark suites rather than relying only on hand-picked demos.

The repository contains deterministic benchmark and evaluator-validation results, including frozen task suites and reproducibility checks. These results are useful for regression testing and validating the evaluation harness, but **they should not be interpreted as an independent comparison of real LLM model quality unless the run identifies a real model/provider and reproducible configuration**.

The current public result registry includes a `stub/small` validation run. It is intentionally labeled as such so test-harness scores are not confused with real-model performance.

- [Evaluation methodology](docs/evaluation.md)
- [Benchmark documentation](docs/benchmark.md)
- [Reproducible result registry](benchmarks/leaderboard/)
- [Research & limitations](docs/research.md)

---

## Architecture

```mermaid
flowchart LR
    A["Natural-language question"] --> B["Planner"]
    B --> C["Data-science tools"]
    C --> D["SQL / Statistics / ML / Visualization"]
    D --> E["Evidence graph"]
    E --> F["Critic"]
    F --> G["Evidence-backed report"]
    G --> H["Reproduction artifacts"]
```

Hosted demo topology:

```mermaid
flowchart LR
    U["Browser"] --> W["Next.js · Vercel"]
    W --> A["FastAPI · Render"]
    A --> D["Temporary dataset storage"]
    A --> T["DSA tools"]
    T --> R["Evidence + report"]
```

The runtime uses a LangGraph-based orchestration layer over typed data-science tools, with local-first data operations built around Python, DuckDB, Polars, SciPy, scikit-learn, and Matplotlib.

---

## DSA vs. typical AI data analysis

| Capability | Chat-with-data tools | Generic coding agents | Data Science Agent |
|---|:---:|:---:|:---:|
| Natural-language analysis | ✓ | ✓ | ✓ |
| SQL / statistics / ML | ✓ | ✓ | ✓ |
| Autonomous workflow | Limited | ✓ | ✓ |
| Dataset hashing | — | — | ✓ |
| Claim-level evidence | — | — | ✓ |
| Evidence graph | — | — | ✓ |
| Reproduction bundle | Limited | Limited | ✓ |
| Evidence-aware critic | — | — | ✓ |
| MCP interface | Varies | Varies | ✓ |
| Plugin runtime | Varies | Varies | ✓ |

DSA is not intended to be only another natural-language interface to a dataframe. Its focus is **verifiable, reproducible AI data science**.

---

## Documentation

Start here:

- [Live Demo](https://data-science-agent-web.vercel.app/datasets)
- [Product Tour](https://jackxiaozhiren.github.io/data-science-agent/)
- [Getting Started](docs/getting-started.md)
- [Hosted Demo Deployment](docs/hosted-demo.md)
- [SDK & API Reference](docs/api.md)
- [Evaluation](docs/evaluation.md)
- [Benchmarks](docs/benchmark.md)
- [MCP](docs/mcp.md)
- [Research & Limitations](docs/research.md)
- [Case Studies](case-studies/)
- [Roadmap](ROADMAP.md)
- [Changelog](CHANGELOG.md)
- [Releases](https://github.com/Jackxiaozhiren/data-science-agent/releases)

---

## Development

```bash
git clone https://github.com/Jackxiaozhiren/data-science-agent.git
cd data-science-agent
uv sync --dev
uv run dsa demo
uv run pytest
```

Static checks:

```bash
uv run ruff check .
uv run mypy .
```

---

## Contributing

Contributions are welcome, especially:

- real-model benchmark baselines
- reproducibility failures
- new datasets and benchmark tasks
- statistical validation improvements
- data-science tools and plugins
- case studies and documentation

**New contributor?** Start with the [`good first issue`](https://github.com/Jackxiaozhiren/data-science-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) queue.

See [CONTRIBUTING.md](CONTRIBUTING.md), [ROADMAP.md](ROADMAP.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

---

## Citation, security, and license

- Academic use: [CITATION.cff](CITATION.cff)
- Security reports: [SECURITY.md](SECURITY.md)
- License: [MIT](LICENSE)

---

<div align="center">

### Ask. Analyze. Verify. Reproduce.

[Live Demo](https://data-science-agent-web.vercel.app/datasets) ·
[Product Tour](https://jackxiaozhiren.github.io/data-science-agent/) ·
[Get Started](docs/getting-started.md) ·
[Case Studies](case-studies/) ·
[Evaluation](docs/evaluation.md) ·
[Roadmap](ROADMAP.md) ·
[Contribute](CONTRIBUTING.md)

⭐ If reproducible AI data analysis is useful to you, consider starring the project.

</div>
