Metadata-Version: 2.4
Name: automated-data-analyst
Version: 0.7.0
Summary: The math arm for LLMs: compute and check numbers from CSV and Excel data with pandas, SciPy and statsmodels, each with its calculation, or refused with a reason. Tool definitions for Claude, Codex and open-source models (Ollama, vLLM, llama.cpp, LM Studio), cross-validated Kaggle-style models, and paper tables and figures.
Author: Sainesh Nakra
License-Expression: MIT
Project-URL: Homepage, https://github.com/saineshnakra/automated-data-analyst
Project-URL: Documentation, https://github.com/saineshnakra/automated-data-analyst/blob/main/docs/README.md
Project-URL: LLM tools, https://github.com/saineshnakra/automated-data-analyst/blob/main/docs/llm-tools.md
Project-URL: Demo, https://automated-data-analyst.streamlit.app/
Project-URL: Results, https://github.com/saineshnakra/automated-data-analyst/blob/main/results/README.md
Project-URL: Source, https://github.com/saineshnakra/automated-data-analyst
Project-URL: Issues, https://github.com/saineshnakra/automated-data-analyst/issues
Project-URL: Changelog, https://github.com/saineshnakra/automated-data-analyst/blob/main/CHANGELOG.md
Keywords: llm,llm-tools,llm-math,tool-calling,function-calling,ai-agents,agent-tools,agent-skills,claude-skills,claude-code,codex,ollama,vllm,llama-cpp,local-llm,open-source-llm,hallucination,fact-checking,claim-verification,data-analysis,ai-data-analyst,statistics,pandas,scipy,statsmodels,csv,excel,tabular-data,exploratory-data-analysis,eda,data-profiling,machine-learning,automl,kaggle,gradient-boosting,explainable-ai,interpretable-ml,research,reproducible-research,reproducibility,research-data,publication-figures,methods-section,data-dictionary,provenance,mixed-models,anomaly-detection,forecasting
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Matplotlib
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3,>=2.2
Requires-Dist: numpy<3,>=1.26
Requires-Dist: python-calamine<1,>=0.4
Requires-Dist: scipy<2,>=1.11
Requires-Dist: statsmodels<1,>=0.14.2
Requires-Dist: ruptures<2,>=1.1.10
Requires-Dist: PyYAML<7,>=6
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: python-docx<2,>=1.1
Provides-Extra: app
Requires-Dist: streamlit==1.59.2; extra == "app"
Requires-Dist: starlette<1,>=0.40; extra == "app"
Requires-Dist: plotly<7,>=5.24; extra == "app"
Provides-Extra: ai
Requires-Dist: openai<3,>=2.46; extra == "ai"
Requires-Dist: pydantic<3,>=2.11; extra == "ai"
Provides-Extra: model
Requires-Dist: scikit-learn<2,>=1.5; extra == "model"
Requires-Dist: lightgbm<5,>=4.5; extra == "model"
Requires-Dist: xgboost-cpu<4,>=3; sys_platform == "linux" and extra == "model"
Requires-Dist: xgboost<4,>=3; sys_platform != "linux" and extra == "model"
Requires-Dist: catboost<2,>=1.2; extra == "model"
Provides-Extra: dev
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Requires-Dist: openpyxl<4,>=3.1; extra == "dev"
Dynamic: license-file

# ADA: the math arm for LLMs

[![CI](https://github.com/saineshnakra/automated-data-analyst/actions/workflows/ci.yml/badge.svg)](https://github.com/saineshnakra/automated-data-analyst/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/automated-data-analyst?color=635bff)](https://pypi.org/project/automated-data-analyst/)
[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-3776ab?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-20a779.svg)](https://github.com/saineshnakra/automated-data-analyst/blob/main/LICENSE)
[![Stars](https://img.shields.io/github/stars/saineshnakra/automated-data-analyst?style=flat&logo=github&color=f5b731)](https://github.com/saineshnakra/automated-data-analyst/stargazers)
[![Agent skill: Claude Code and Codex](https://img.shields.io/badge/agent%20skill-Claude%20Code%20%C2%B7%20Codex-0e0f13)](#use-it-from-claude-code-or-codex)
[![Tool calling: Ollama, vLLM, llama.cpp, LM Studio](https://img.shields.io/badge/tool%20calling-Ollama%20%C2%B7%20vLLM%20%C2%B7%20llama.cpp%20%C2%B7%20LM%20Studio-0e0f13)](docs/llm-tools.md)

<p align="center">
  <a href="https://github.com/saineshnakra/automated-data-analyst"><b>⭐ Star ADA</b></a> if it saves you an afternoon ·
  <a href="https://automated-data-analyst.streamlit.app/example-study">Try it in the browser</a> ·
  <a href="https://github.com/saineshnakra/automated-data-analyst/blob/main/docs/README.md">Docs</a> ·
  <a href="https://github.com/saineshnakra/automated-data-analyst/blob/main/CHANGELOG.md">What's new in 0.7.0</a>
  <br>
  <sub>Read this in <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=zh">中文</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=ja">日本語</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=ko">한국어</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=es">Español</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=pt">Português</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=de">Deutsch</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=fr">Français</a> · <a href="https://readme-i18n.com/saineshnakra/automated-data-analyst?lang=ru">Русский</a></sub>
</p>

ADA (Automated Data Analyst) is the part of a language model that does the
math. Point it at CSV or Excel data and ask in plain words: it computes the
answer with pandas, SciPy and statsmodels and returns the number with its
calculation and the rows behind it, or refuses with the reason. It checks
numbers stated about the data too: verified, or unverified with the reason
and the one question that would settle it.

A model never has to do arithmetic in its head again. That helps Claude and
Codex, and it helps open-source models most: a small local model run with
Ollama, llama.cpp, vLLM or LM Studio only has to pick the tool and read the
answer. ADA is a Python package, a command line and a set of tool
definitions any model with function calling can use.

```bash
pip install automated-data-analyst     # Python 3.11 or newer
```

## Give a language model a math arm

```python
from ada import tools

tools.definitions()                    # four tools for function calling: ask, check a claim, scan, model
tools.run("ada_check_claim", {"path": "flights.csv", "claim": "The average departure delay was about 13 minutes."})
```

`tools.definitions()` is in the format OpenAI-compatible servers take, local
ones included (`tools.definitions("anthropic")` for the Anthropic API), and
`tools.run` runs the tool the model picks and returns JSON to send back.
`ada tools` prints the same definitions for any other client.
[ADA as the math tool of a language model](docs/llm-tools.md) has a complete
loop with a local model, the Anthropic API and shell commands.

## Check a number

```console
$ ada claim flights.csv "The average departure delay was about 13 minutes."
verified: The average departure delay was about 13 minutes.
  12.63907026 (328,521 rows) from mean(dep_delay) lies in 12 to 14, which about 13 minutes stands for.
  calc: mean(dep_delay)
  assumes: Read "departure delay" as dep_delay.
  assumes: Left out 8,255 rows with dep_delay missing.
  assumes: Read "about" as 12 to 14.
  assumes: The unit "minutes" comes from the claim; the check compares numbers only.

$ ada claim flights.csv "The average delay was 13 minutes."
unverified: The average delay was 13 minutes.
  The claim's words fit more than one column, and they give different answers: dep_delay gives 12.63907026; arr_delay gives 6.895376757.
  to check it: Which column is meant: dep_delay or arr_delay?
```

`verified` means this number, from these rows, by this calculation, with the
assumptions listed. `unverified` is not false: only the reason `failed_check`
says the data give a different number. `--json` gives the whole record, and
`ada.check_claim(...)` does the same in Python. See
[Checking claims](docs/reference/claims.md) for the reasons, intervals and units.

## Compute an answer, or map a folder

```bash
ada scan lahman/ --template answers.yml      # the files, how they join, the questions to ask first
ada ask flights.csv "average dep_delay by origin" --json   # the numbers, the calculation, the rows used
ada claim lahman/ "Barry Bonds hit 73 home runs in 2001." --answers answers.yml
```

`ada scan` asks what the analysis should find out, what a row is, and each
choice ADA would otherwise make by default, with its proposed answer; `ada
ask` and `ada claim` take the edited file. When an answer rests on a choice,
such as leaving World and region rows out of an average, it says which, and
`--decide` picks the other ([Decisions](docs/reference/decisions.md)). A
question or claim about a folder is answered from the file it fits, or from
two files joined along a link ADA is sure of. A question ADA can't answer
comes back refused, with the reason. See [Ask ADA](docs/reference/ask-ada.md)
and [Reading a folder of tables](docs/reference/folder.md).

Before it answers, ADA reports the rows it left out and why, counts each
subject once when several rows come from one, says when groups reverse a
pooled figure, adds up the count column of a table of counts, and gives a
reason instead of a number when the data are too thin.

## Use it from Claude Code or Codex

```bash
ada skill               # .claude/skills/ada (Claude Code) and .agents/skills/ada (Codex)
ada skill --user        # the same in your home folder, for every project
```

It also installs as a plugin ([how](plugins/automated-data-analyst/README.md)).
The [skill](ada/skills/ada/SKILL.md) has the assistant let ADA do the
arithmetic, check every number it states with `ada claim`, and ask you ADA's
question instead of choosing a reading.

## Paper assets for a study

```bash
ada demo mice && cd mice           # an example study to try first
ada init data/measurements.csv     # asks about the study; writes study.yml
ada build                          # writes paper-assets/
ada verify                         # rebuilds and compares every number
```

`ada build` makes a data audit, a data dictionary, a record of every
exclusion, results tables in Word, LaTeX and CSV, figures with captions and a
methods draft. See [Paper assets for a study](docs/research.md). `ada analyze`
gives a first look at any table, and `ada app` opens the same in a browser
(`pip install "automated-data-analyst[app]"`).

## Predict a column

```bash
pip install "automated-data-analyst[model]"
ada model titanic/ --metric accuracy --out submission.csv
```

`ada model` predicts one column of a table from the others, as a tabular
Kaggle competition asks. The features come from rules on the columns' shapes,
LightGBM, XGBoost and a linear model are blended on out-of-fold predictions,
every score is cross-validated, and the submission is checked before it is
written. See [Predicting a column](docs/reference/modelling.md).

`ada auto` does the same with a wider search and takes longer: CatBoost,
LightGBM with random split points, extremely randomized trees and a neural
network join the blend, a second layer is fitted on their out-of-fold predictions, and the
weights come from greedy selection. Each step stays only when the folds say it
helps. `--jobs N` fits N learners at once and gives the same model.

`--explain` predicts with a model a person can read instead, a linear or an
additive one, with its coefficients and 95% intervals, each column's effect
curve, and what explaining costs against the full search, fold by fold.

It is scored on Kaggle competitions with no code for any one of them: the
runner passes ADA the competition's folder and the name of its metric, and
ADA does the rest. Each competition is also split inside itself, the way its
test is made, so a change is measured on all 22 without a submission. On the 22 scored so far, with `ada auto` where it was
run, it places in the top 10% on 2 (Titanic, and Housing Prices on Kaggle
Learn, at 2%), in the top 15% on 6 and in the top 30% on 13. Store Sales, a
forecast of 1,782 series, is its weakest, at 58%.
[Every score](results/kaggle/README.md).

## What it doesn't do yet

Numbers that need three files joined, many phrasings ("horsepower" for `hp`,
slopes, several numbers in one claim), and some year columns read as numbers
rather than dates. These come back unverified or refused with a
reason. See [Not covered yet](docs/reference/claims.md#not-covered-yet).

## Progress

73 cases on 20 public datasets, each expected value computed separately with
pandas, SciPy and statsmodels; a fifth of each dataset's cases are holdout
cases, only scored ([details](results/verification/README.md)).

| | ADA 0.5.0 | Now |
|---|---|---|
| Dev cases | 9/58 | 50/58 |
| Holdout cases | 0/15 | 14/15 |
| Wrong verdicts on claims | | 0/35 |
| True claims verified | 0/25 | 23/25 |
| False claims caught | 0/7 | 6/7 |

Each change is also scored on rounds of new public data, six datasets at a
time from statistics offices, city portals and research projects, with claims
written as reports write them; the pull request gives the scores.

## More

[All documentation](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
[Credits](docs/credits.md) · [Citing](CITATION.cff) · MIT [License](LICENSE)
