Metadata-Version: 2.4
Name: autonima
Version: 0.1.0
Summary: LLM-powered automated systematic review and meta-analysis
Home-page: https://github.com/neurostuff/autonima
Author: Alejandro de la Vega
Author-email: delavega@utexas.edu
License: MIT
Project-URL: Documentation, https://neurostuff.github.io/autonima/
Project-URL: Source, https://github.com/neurostuff/autonima
Project-URL: Tracker, https://github.com/neurostuff/autonima/issues
Keywords: systematic-review,meta-analysis,neuroimaging,pubmed,llm,ai,literature-search,prisma,evidence-synthesis
Classifier: Development Status :: 3 - Alpha
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10,<3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28.0
Requires-Dist: typing-extensions>=4.0
Requires-Dist: biopython>=1.81
Requires-Dist: pandas>=2.0
Requires-Dist: pubget>=0.0.8
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: lxml>=4.6.0
Requires-Dist: tqdm>=4.60
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == "llm"
Provides-Extra: readability
Requires-Dist: readabilipy>=0.2.0; extra == "readability"
Provides-Extra: meta
Requires-Dist: nimare>=0.1.0; extra == "meta"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-click>=0.8; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Provides-Extra: ui
Requires-Dist: fastapi>=0.115; extra == "ui"
Requires-Dist: uvicorn>=0.30; extra == "ui"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Autonima

Autonima is a large language model (LLM)-guided framework for neuroimaging
meta-analysis. It automates article screening against expert-defined eligibility
criteria, parses heterogeneous coordinate tables into the distinct analyses that
produced them, and selects individual analyses for quantitative synthesis.

Full documentation: https://neurostuff.github.io/autonima/

## The workflow

<p align="center">
  <img src="docs/assets/pipeline-overview.png" width="520"
       alt="Autonima pipeline: expert-defined configuration, PubMed search, abstract and full-text screening, coordinate parsing, analysis selection, coordinate-based meta-analysis">
</p>

A project is one YAML file: a PubMed query, article-level inclusion and exclusion
criteria, retrieval sources, parsing settings, and one set of contrast-specific
criteria per target.

1. **Search** — PubMed through the Entrez API.
2. **Abstract screening** — an LLM judges each record against the article-level
   criteria, returning a decision, a criterion-by-criterion assessment and its
   reasoning. Abstract criteria are usually more permissive, since an abstract
   carries incomplete information.
3. **Full-text retrieval** — PubMed Central via pubget, publisher text-mining
   APIs (Elsevier, Springer Nature), and user-supplied HTML. Records with no
   usable text are marked unavailable rather than rejected: a retrieval failure
   is not an eligibility decision.
4. **Full-text screening** — the same procedure against the complete criteria,
   with the full text in context.
5. **Coordinate parsing** — heuristics identify candidate tables; an LLM reads
   each table with its caption and footnotes and separates it into the distinct
   statistical analyses it reports, keyed on contrast, direction, group,
   condition, session or any other explicitly labelled dimension.
6. **Analysis selection** — every parsed analysis is evaluated against each
   target's criteria in the context of its article, producing an
   analysis × target inclusion matrix. One analysis may serve several targets.
7. **Meta-analysis** — selected coordinates are written as a NiMADS studyset and
   submitted to NiMARE (MKDA, ALE or KDA; FWE or FDR correction).

Stage outputs are cached, so re-running resumes rather than repeating paid API
calls.

## Two ways to run it

Both drive the same pipeline and produce identical outputs.

**The CLI** runs one config, once, into one folder. Use it for scripted and
reproducible work.

```bash
autonima run config.yaml
```

**The web UI** manages many projects over time — live progress, cancellation,
cloning a project to make a variant, browsing meta-analysis artifacts, and
storing API credentials. Use it while developing criteria.

```bash
autonima ui --workspace .
```

The CLI has no memory between invocations; the UI keeps a workspace. A project
created in one can be run from the other. See the
[Web UI guide](https://neurostuff.github.io/autonima/guides/web-ui/).

## Install

```bash
git clone git@github.com:neurostuff/autonima.git
cd autonima
pip install -e .
```

Extras:

```bash
pip install -e .[llm]          # screening and other LLM-backed workflows
pip install -e .[meta]         # `autonima meta`
pip install -e .[readability]  # enhanced HTML extraction
pip install -e .[ui]           # `autonima ui` local web app
pip install -e .[docs]         # local docs build
```

## Quickstart

```bash
autonima create-sample-config > config.yaml   # a starting config
autonima validate config.yaml                 # check it before spending anything
autonima run config.yaml                      # run the pipeline
autonima meta config/outputs                  # meta-analyse the NiMADS output
```

Omitting `OUTPUT_FOLDER` derives it from the config filename stem, so
`projects/cue_reactivity/default.yaml` writes to
`projects/cue_reactivity/default/`. Pass one explicitly to override:

```bash
autonima run config.yaml runs/my_review
```

`run-search` and `run-abstract` execute the pipeline only as far as those stages,
which is useful for checking a query or a criteria set cheaply before committing
to full-text retrieval.

## Minimal config

```yaml
search:
  database: "pubmed"
  query: "schizophrenia AND working memory AND fMRI"
  max_results: 100

retrieval:
  sources:
    - pubget
  load_excluded: false

screening:
  abstract:
    model: "gpt-5-mini-2025-08-07"
    objective: "Identify fMRI studies of working memory in schizophrenia"
    inclusion_criteria:
      - Human participants
      - fMRI neuroimaging
  fulltext:
    model: "gpt-5-mini-2025-08-07"
    objective: "Identify fMRI studies of working memory in schizophrenia"
    inclusion_criteria:
      - Human participants
      - fMRI neuroimaging

parsing:
  parse_coordinates: false
  coordinate_model: "gpt-4o-mini"

output:
  directory: "results"

annotation:
  enabled: false
```

Model identifiers and API endpoints are configurable, so any OpenAI-compatible
provider can be used.

## Documentation

- [Quickstart](https://neurostuff.github.io/autonima/getting-started/quickstart/)
- [Configuration](https://neurostuff.github.io/autonima/guides/configuration/)
- [CLI usage](https://neurostuff.github.io/autonima/guides/cli/)
- [Web UI](https://neurostuff.github.io/autonima/guides/web-ui/)
- [Full-text sources](https://neurostuff.github.io/autonima/guides/full-text-sources/)
- [Meta-analysis](https://neurostuff.github.io/autonima/guides/meta-analysis/)
- [Interpreting outputs](https://neurostuff.github.io/autonima/guides/interpreting-outputs/)

## Citation

Autonima v0.1.0 is the version evaluated in the AutoNIMA manuscript. See
[releases](https://github.com/neurostuff/autonima/releases).
