Metadata-Version: 2.4
Name: warpdrive-cli
Version: 0.5.0
Summary: The data plane for a physicist's research — an installed CLI, no hosting
Project-URL: Homepage, https://github.com/warpdrive-inc/warpdrive
Project-URL: Source, https://github.com/warpdrive-inc/warpdrive
Author: Warpdrive
Keywords: agents,astrophysics,cli,globus,research-data,slurm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Description-Content-Type: text/markdown

# Warpdrive

The data plane for a physicist's research, as a CLI that installs in one
line and deploys nothing:

```
uv tool install warpdrive-cli   # installs the `warpdrive` command
warpdrive                       # the manual — short, personalized, agent-readable
```

Before the first PyPI release — or for a lab tracking the branch — the same
one line installs straight from the repo:

```
uv tool install git+https://github.com/warpdrive-inc/warpdrive
uv tool upgrade warpdrive-cli   # picks up the latest commit / release
```

One command surface over the researcher's Google Drive, GitHub, Hugging
Face and Globus, the astronomy archives (MAST, IRSA, HEASARC, VizieR,
SIMBAD, NED), the literature (arXiv, INSPIRE-HEP, NASA ADS), Zenodo, their
Slurm cluster, and their own compute endpoints — with a persistent memory
layer and a provenance ledger, all in `~/.warpdrive/` on their machine.

```
warpdrive find 'muon calibration'          # federated search; results carry refs
warpdrive read drive:1aB2c3                # one shape, wherever data lives
warpdrive write drive:root/out.csv --file out.csv
warpdrive move 'globus:A:/scratch/run01' 'globus:B:/~/run01' --recursive
warpdrive slurm check --site savio job.sh  # catches the job that pends forever
warpdrive slurm submit --site perlmutter job.sh   # sbatch via NERSC's API, no SSH
warpdrive exec --endpoint <id> 'python reprocess.py'
warpdrive write mem:me 'the good flats are in drive:1aB2c3'
```

Agents bootstrap from the briefing alone: tell any harness "run
`warpdrive`" (or `warpdrive init --write AGENTS.md`). Output is JSON on
stdout; errors are one JSON object on stderr — `{code, message, retryable,
hint}` — and the hint is a concrete next step.

Connecting sources is the researcher's, once per machine, interactively:
`warpdrive connect drive|github|globus|huggingface|nersc|zenodo|ads`.
Credentials are encrypted at rest and never leave the machine; agents
cannot complete a connect flow, only ask for one.

**About Drive, so it isn't a surprise.** Warpdrive ships a Google "Desktop
app" OAuth client, whose secret Google's own guidance says is not
confidential — loopback plus PKCE is what secures the flow. That app is in
*testing* publishing status, so **Google expires its refresh tokens after
seven days**: expect to re-run `warpdrive connect drive` about weekly. It is
not a bug, and the `needs_reauth` error says as much. A lab that wants this
to stop can point Warpdrive at its own Google app — one that is Internal to
its Workspace org has no expiry clock and no user cap:

```
# ~/.warpdrive/env
WARPDRIVE_GOOGLE_CLIENT_ID=...apps.googleusercontent.com
WARPDRIVE_GOOGLE_CLIENT_SECRET=...
```

## Layout

```
warpdrive/cli_main.py     the argv layer — parse, dispatch, print
warpdrive/commands/       one module per command family; all judgment lives here
warpdrive/library/        domain clients, adapters, repositories, flows
warpdrive/models/         pydantic models
warpdrive/config/         settings (env + ~/.warpdrive/env)
warpdrive/store/          SQLite persistence under ~/.warpdrive/
```

There is no server, no database service, no worker: long-running work
(Globus transfers, NERSC jobs, compute tasks) is *reconciled on read* — the
sources remember the truth, and `warpdrive jobs` folds it in whenever
anyone asks.

Development: `just test`, `just check`, `just run <args>`. Rules and
architecture: `AGENTS.md`, then `docs/`.
