Metadata-Version: 2.4
Name: adduce
Version: 0.1.2
Summary: A local research-artifact auditor: checks that a paper's claims, code, configs, data, and results still agree, and produces the artifacts reviewers ask for.
Project-URL: Homepage, https://github.com/QHarshil/adduce
Project-URL: Repository, https://github.com/QHarshil/adduce
Project-URL: Issues, https://github.com/QHarshil/adduce/issues
Project-URL: Changelog, https://github.com/QHarshil/adduce/blob/main/CHANGELOG.md
Author-email: Harshil Chudasama <chudasama.h@northeastern.edu>
License: MIT License
        
        Copyright (c) 2026 Harshil Chudasama
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: artifact-evaluation,auditing,machine-learning,provenance,reproducibility,research,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: libcst>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: twine>=5.1; extra == 'release'
Description-Content-Type: text/markdown

# adduce

[![CI](https://github.com/QHarshil/adduce/actions/workflows/ci.yml/badge.svg)](https://github.com/QHarshil/adduce/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/adduce.svg)](https://pypi.org/project/adduce/)
[![Python versions](https://img.shields.io/pypi/pyversions/adduce.svg)](https://pypi.org/project/adduce/)
[![License: MIT](https://img.shields.io/github/license/QHarshil/adduce.svg)](https://github.com/QHarshil/adduce/blob/main/LICENSE)

**A local research-artifact auditor.**

`adduce` checks whether a paper's claims, code, configs, data, dependencies, remote models, precision settings, and generated results still agree with each other before submission. It also drafts repository-observable NeurIPS/ACL checklist items, an ACM Artifact Appendix, archival metadata (RO-Crate, Croissant, CodeMeta, Zenodo), and a claim-by-claim evidence trail for author review.

The north-star question: *for every number in the paper, can I point to the artifact that produced it, and will that artifact still produce it elsewhere?*

## Install

```console
pipx install adduce        # or: pip install adduce / uvx adduce
adduce check .
```

[PyPI `0.1.2`](https://pypi.org/project/adduce/0.1.2/) is the current release.

Upgrade commands per installer, and the caveat that existing installations do
not update themselves, are in [docs/cli-reference.md](https://github.com/QHarshil/adduce/blob/main/docs/cli-reference.md#installing-and-upgrading).

Adduce is beta software. Findings are static-analysis signals for review, and
scores, tiers, and reviewer-time estimates are provisional pending calibration
against manually reviewed real repositories. Generated submission material is
always a draft.

> Built-in checks are offline by default. Public-metadata requests require the
> explicit `--online` or `pin-remotes` modes and use a bounded public-HTTPS
> resolver; pre-existing cache entries never count as network evidence. Read
> the [security model](https://github.com/QHarshil/adduce/blob/main/docs/security-model.md) before using network, provider,
> plugin, or dynamic-execution features on untrusted input.

## What it reports

Verbatim excerpt from `adduce check` on [nanoGPT](https://github.com/karpathy/nanoGPT)
at commit `3adf61e`. Omitted whole: eight of the fourteen category rows, the
no-paper-sources notice, the inferred claim-trail block, the last two fixes, and
the closing `Next:` line. Nothing is reworded, and every `…` is the tool's own
truncation marker.

```
╭─ adduce  ·  nanogpt  ·  commit 3adf61e ────────────────────────────────────────────────────────╮
│ Reproducibility  54/100   Bronze   ·   profile: default                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯
Reviewer time to first result: 23–83 min (Risky)
  - no one-command reproduction path
  - environment must be assembled by hand (no container or conda env)
  - dependency resolution may not converge to the original environment
  - no smoke/quick-run target for a minutes-scale sanity check

Category                        Score  Notes
Code & Execution                 8/12  Commands are documented, but there is no run script or
                                       Makefile target to execute them; The README shows run
                                       command(s) (e.g. `python
                                       data/shakespeare_char/prepare.py`), but …
Environment & Tooling            1/10  No dependency manifest found (requirements.txt,
                                       pyproject.toml, environment.yml); No lockfile found
                                       (poetry.lock, uv.lock, Pipfile.lock, conda-lock); No
                                       Dockerfile, …
Data                             8/10  No checksums or content-addressed data tracking detected; A
                                       data directory exists but does not separate raw from
                                       processed content
Determinism & Model              3/12  Some RNG sources are seeded, but not all: missing python
                                       (random.seed), numpy (np.random.seed or default_rng);
                                       Neither torch.backends.cudnn.deterministic=True nor …
Numerical Precision & Hardware    2/4  TF32 / float32-matmul precision control in use
                                       (torch.backends.cuda.matmul.allow_tf32 = True;
                                       torch.backends.cudnn.allow_tf32 = True) but no precision
                                       policy is documented …
Portability                       3/3  all detected checks satisfied

Top fixes (largest score gains first)
 1. Extend the seeding helper to cover: python (random.seed), numpy (np.random.seed or
default_rng).
     adduce fix --scaffold seeds
 2. Set torch.backends.cudnn.deterministic = True and torch.backends.cudnn.benchmark = False in
the seeding helper.
     adduce fix --scaffold seeds
 3. Declare dependencies, then pin them (pip freeze, pip-compile, uv lock, poetry lock).

Statuses are detected signals from static analysis, not a certification of reproducibility.
```

Location-bearing findings are anchored to source lines—the TF32 finding above
points at `train.py:107`, and the unpinned hub call at `model.py:238`. Six of
the fourteen categories that applied to this repository are shown above; the
full run also covers Documentation, Run Traceability, Checkpoint & Experiment
State, Notebooks, Remote Artifacts & Rot, Versioning, Access & Legal, and
Archival Readiness.

When a manifest declares claims, the report adds a per-claim trail. Trimmed
output from `adduce manifest` followed by `adduce check` on the synthetic
positive-control repository
[`corpus/synthetic/synthetic_rounding_match`](https://github.com/QHarshil/adduce/tree/main/corpus/synthetic/synthetic_rounding_match)
in this repository, where the paper states an accuracy of 81.4 and the logged
run recorded 81.37:

```
Claim trails (manifest; draft claims remain inferred until author-confirmed)
  paper/main.tex:3  ·  "accuracy of 81.4" [inferred draft]
    metric      results/eval.csv:accuracy  (found: 81.37)   ~ rounding vs paper
(81.4) ✓
    log         results/eval.csv ✓
    status      PARTIAL
```

Every finding carries a status (`pass` / `partial` / `fail` / `not-applicable`
/ `unknown`), a confidence, available file:line locations, and a concrete
remediation. `partial` is used when the repository supports only part of a
check.

## Honest limits

adduce reports detected signals, never a certification of reproducibility. It
never says a repository "is reproducible", and it never assesses
execution-based badges (Results Reproduced/Replicated) — only badge
*eligibility* signals. Static analysis never implies execution: the opt-in
`--online`/`pin-remotes` (network) and `reproduce` (execution) layers are the
only parts of adduce that leave the offline, static default, and both are
explicitly fenced.

Scores and named tiers are experimental prioritisation aids, not calibrated
quality grades. The [validation corpus protocol](https://github.com/QHarshil/adduce/blob/main/corpus/README.md) defines a
pending release-quality gate, and no effectiveness or calibration claim is
made until its human-review requirements are complete.

The full list of limits — automatic claim inference as scaffolding only, the
static-resolution ceiling, remote pinning as a forward guarantee rather than
historical recovery, dynamic reproduction's non-sandboxed execution, and more
— is in [docs/honest-limits.md](https://github.com/QHarshil/adduce/blob/main/docs/honest-limits.md).

## Documentation

Adduce ships **78 rules across 17 categories**, each gated on whether it
applies, so an inapplicable category drops out of scoring rather than counting
against a repository.

Full documentation — every rule, the CLI reference, the manifest and
claim-trail model, CI recipes, generation safety, the optional LLM layer, and
the security model — starts at [docs/index.md](https://github.com/QHarshil/adduce/blob/main/docs/index.md). The [rule
reference](https://github.com/QHarshil/adduce/blob/main/docs/rules/README.md) and [honest limits](https://github.com/QHarshil/adduce/blob/main/docs/honest-limits.md)
are the two pages most worth reading before relying on a score.

## Contributing

Contributions are welcome, especially incorrect or low-value finding reports.
See [CONTRIBUTING.md](https://github.com/QHarshil/adduce/blob/main/CONTRIBUTING.md) for the development setup, design
constraints, and how to add a rule. Report vulnerabilities privately under the
[security policy](https://github.com/QHarshil/adduce/blob/main/SECURITY.md).

## License

[MIT](https://github.com/QHarshil/adduce/blob/main/LICENSE)
