Metadata-Version: 2.4
Name: quai-atlas
Version: 0.1.0
Summary: A read-only desktop browser for quai experiments, artifacts, and data provenance.
Author: Aaron Ponti
Author-email: Aaron Ponti <aaron@aaronponti.ch>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Dist: pyside6>=6.12
Requires-Dist: pyyaml>=6.0.3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# quai-atlas

A read-only desktop application for looking at quai's work: experiments, runs,
results, data versions, annotations, and the provenance that links them. It
reads quai's records, its local MLflow tracking databases and the data
repository's Git history, and changes none of them. It doesn't run quai, DVC,
training or inference.

Atlas runs on Linux, Windows and macOS.

## Install

quai-atlas is distributed on PyPI and requires Python 3.12 or newer.
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) once,
then create an environment of its own. The example uses Python 3.12;
uv downloads it if needed.

```
uv venv --python 3.12 .venv
source .venv/bin/activate        # Windows (PowerShell): .venv\Scripts\Activate.ps1
uv pip install quai-atlas
quai-atlas
```

Git must be on the `PATH` for the data repository's checks. quai, DVC, MLflow
and napari aren't needed to browse existing records.

## First steps

1. Open **Roots and mappings…**. Add the experiment folder (the one holding
   `quai_experiment.json`, or a folder of experiments) with **Add
   experiments…**, and the data repository's root (the folder holding `.git`
   and `.dvc`) with **Add data repository…**. Save.
2. Choose an experiment on the left. Its overview lists the runs, with their
   analyses below them. The lineage graph above the table shows source →
   derived runs, recorded dataset IDs and separate analyses. Double-click a
   graph card or click a table row to open the run's summary.
3. The summary starts with its provenance verdict: what Atlas could check, and
   what it couldn't. **Related items** leads to the run's sources and to what
   was made from it.

A copy moved from another machine may need a mapping from the recorded path to
its new folder, in **Roots and mappings…**. Tutorial 15 of the quai tutorials,
"Browsing experiments and data repositories with quai-atlas", walks through all
of it: verdicts, configuration, tracking, data versions, annotations, moved
copies and network shares.

## Images and annotations

Atlas can hand an image or label to napari, and start the annotation workbench
for a project. Install them in the environment Atlas runs in:

```
uv pip install "napari[all]" quai-workbench-napari
```

quai-workbench-napari is distributed on PyPI too.

## What Atlas keeps, and what it never does

Atlas keeps its settings and caches in `quai/quai-atlas` under the platform's
user configuration folder, never inside a folder you register. It reads only
inside the registered folders, and writes nothing there: no record, no Git
command that changes the repository, no MLflow write. Opening a file or folder
hands it to another application, whose own behaviour applies.

## License

Apache License 2.0; see the LICENSE file.
