Metadata-Version: 2.5
Name: ai-almanac
Version: 0.1.0a1
Summary: Local-first benchmarking platform for AI weather and climate models.
Project-URL: Homepage, https://ai-almanac.org
Project-URL: Source, https://github.com/AI-Almanac/ai-almanac
Project-URL: Issues, https://github.com/AI-Almanac/ai-almanac/issues
Author: AI Almanac contributors
License-Expression: MIT
License-File: LICENSE
Keywords: benchmarking,climate,forecasting,machine-learning,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.18.4
Requires-Dist: anyio>=4.14.2
Requires-Dist: certifi
Requires-Dist: cryptography<51,>=48.0.1
Requires-Dist: fastapi>=0.135.3
Requires-Dist: gcsfs<2027,>=2026.5.0
Requires-Dist: globus-sdk<5,>=4.8.0
Requires-Dist: google-cloud-storage<4,>=3.12.0
Requires-Dist: greenlet>=3.4.0
Requires-Dist: h5netcdf>=1.8.1
Requires-Dist: h5py>=3.16.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: modal<2,>=1.5.0
Requires-Dist: netcdf4>=1.7.4
Requires-Dist: openai>=2.32.0
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: psycopg[binary]<4,>=3.3.4
Requires-Dist: pydantic-ai<3,>=2
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pyjwt>=2.14.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: sqlalchemy>=2.0.49
Requires-Dist: titiler-core<3,>=2.0.5
Requires-Dist: typer>=0.15.1
Requires-Dist: uvicorn[standard]>=0.44.0
Requires-Dist: xarray>=2026.2.0
Description-Content-Type: text/markdown

# ai-almanac

Local-first benchmarking platform for AI weather and climate models.

Pick a region and an event type (e.g. monsoon onset), select one or more models,
submit a benchmark, and see per-grid-point skill maps (MAE, FAR, miss rate, RMSE,
ACC, bias) rendered in your browser. The whole thing — web UI, API, benchmark
runner, and database — is a single Python process you launch on your own GPU
workstation (NVIDIA DGX Spark, a lab box, your laptop for the LLM-driven UI).

```bash
pipx install ai-almanac      # or `uv tool install ai-almanac`
ai-almanac serve             # opens http://localhost:8765 in your browser
```

That's it.

---

## What you get

| Layer            | Where it lives                                                      |
| ---------------- | ------------------------------------------------------------------- |
| Web UI           | SvelteKit SPA, bundled into the wheel                               |
| API              | FastAPI, served on the same port as the UI                          |
| Database         | SQLite under `~/.local/share/ai-almanac/almanac.db` (auto-migrated) |
| Storage          | Filesystem under the same data directory                            |
| Benchmark runner | Detached local supervisor, with ROMP in a Pixi-managed environment  |
| Access model     | Local, single-user application bound to the loopback interface      |

One Python package. One process. One port. One data directory.

Benchmark jobs run in detached local supervisor processes. Closing or restarting
the web server does not stop active work. Restarting `ai-almanac serve`
reconciles queued and running jobs from SQLite, and active jobs can be canceled
from the benchmark UI.

---

## Install

```bash
# Recommended — uv tool install gives you a managed venv per CLI
uv tool install ai-almanac

# Or pipx
pipx install ai-almanac

# Or pip (less isolated)
pip install ai-almanac
```

Once a homebrew tap / .deb is published, `brew install ai-almanac` and
`apt install ai-almanac` will be available too. The PyPI package is the
source of truth — those channels are thin wrappers.

### Prerequisites for running real benchmarks and blends

Actual benchmark and model-blending execution need separate scientific Python
stacks. Those dependencies live in isolated Pixi-managed environments to keep
the core install small:

```bash
# Install pixi (one-time): https://pixi.sh
curl -fsSL https://pixi.sh/install.sh | bash

# Materialize both workload environments (takes a few minutes the first time)
ai-almanac env prepare
```

This also checks out the blending workflow at the version pinned by AI Almanac.
Subsequent `ai-almanac serve` runs reuse both environments. `ai-almanac env
info` prints the installed benchmark package versions.

---

## Usage

```bash
ai-almanac serve                       # default: 127.0.0.1:8765, opens browser
ai-almanac serve --port 9000           # alternate port
ai-almanac serve --no-open             # don't auto-launch a browser tab
ai-almanac serve --reload              # dev mode (uvicorn auto-reload)
ai-almanac env prepare                 # install / update workload environments
ai-almanac env info                    # show installed package versions

ai-almanac reset --confirm             # wipe ~/.local/share/ai-almanac/
ai-almanac version
```

### Test shared mode locally

Run the complete multi-user architecture locally without DNS, TLS, an OIDC
provider, or a GPU:

```bash
pixi run self-host-local
```

Open `http://localhost:18080`. The stack uses PostgreSQL, shared ownership and
authorization, persistent Docker volumes, and synthetic benchmark outputs.
Switch between the built-in administrator and regular user at
`http://localhost:18080/__dev`.

On a host with NVIDIA Container Toolkit, run real benchmarks instead:

```bash
pixi run self-host-local-gpu
```

The same shared stack can exercise GCS artifact storage or the deployed Modal
runner. GCS requires three bucket names and a service-account or Application
Default Credentials JSON file:

```bash
export GCS_DATA_BUCKET=my-data-bucket
export GCS_UPLOADS_BUCKET=my-uploads-bucket
export GCS_OUTPUTS_BUCKET=my-outputs-bucket
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"

pixi run self-host-local-gcs
```

To submit jobs to Modal, also export `MODAL_TOKEN_ID` and
`MODAL_TOKEN_SECRET`, deploy the Modal app, then run:

```bash
pixi run self-host-local-modal
```

Modal mode uses GCS because remote workers cannot access the local Compose
volume. The local runner supports either local storage or GCS.

Stop the stack with `pixi run self-host-local-down`. Use
`pixi run self-host-local-reset` to also delete its PostgreSQL and application
data volumes.

For an internet-accessible or multi-user installation, follow the
[deployment guide](./docs/deployment.md). Do not expose personal mode to
untrusted users.

### Where data lives

Everything goes under `$AI_ALMANAC_DATA_DIR`, defaulting to:

- Linux: `~/.local/share/ai-almanac/`
- macOS: `~/Library/Application Support/ai-almanac/`
- Windows: `%LOCALAPPDATA%\ai-almanac\`

```
$AI_ALMANAC_DATA_DIR/
├── almanac.db          ← SQLite (WAL mode)
├── uploads/            ← user-uploaded obs datasets
├── jobs/<job_id>/      ← run logs, NetCDF outputs, figures
├── benchmark-env/      ← Pixi environment (ROMP + scientific/geo dependencies)
├── blending-env/       ← Pixi environment and pinned blending workflow
└── cache/              ← weight cache (HuggingFace), ARCO chunks
```

Override with `AI_ALMANAC_DATA_DIR=/some/path ai-almanac serve` to move one
instance's private state. Do not point multiple running instances at the same
application data directory. Researchers may register the same read-only input
dataset directories from separate AI Almanac instances.

---

## Adding data

Open **Data** in the web UI and register local observation or model-output
directories. AI Almanac checks the file pattern and configured NetCDF variable
before making a source available to benchmark workflows.

---

## Development

Install [Pixi](https://pixi.sh/), then start the complete development stack:

```bash
pixi run dev
```

This runs FastAPI with Python auto-reload on `http://localhost:8765` and the
SvelteKit Vite server with hot module replacement on `http://localhost:5173`.
See [`DEVELOPMENT.md`](./DEVELOPMENT.md) for the full task list.

---

## License

MIT.
