Metadata-Version: 2.5
Name: fieldbook
Version: 0.1.0
Summary: Lightweight toolkit for ML experimentation: versioned data, reproducible runs, experiment tracking, and cloud GPUs, with no servers to operate.
Project-URL: Repository, https://github.com/vo-h/fieldbook
Project-URL: Documentation, https://github.com/vo-h/fieldbook/blob/main/docs/guide.md
Project-URL: Issues, https://github.com/vo-h/fieldbook/issues
Project-URL: Changelog, https://github.com/vo-h/fieldbook/blob/main/CHANGELOG.md
Author-email: hien vo <hvo.getz@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,data-versioning,experiment-tracking,machine-learning,mlops,reproducibility,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: fsspec>=2024.6.0
Requires-Dist: packaging>=23
Requires-Dist: pyarrow>=17
Requires-Dist: pydantic-settings>=2.6
Requires-Dist: pylance>=13.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6
Requires-Dist: tomlkit>=0.12
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: botocore>=1.35.16; extra == 'all'
Requires-Dist: duckdb>=1.2; extra == 'all'
Requires-Dist: mlflow>=3.9; extra == 'all'
Requires-Dist: nvidia-ml-py>=12; extra == 'all'
Requires-Dist: pandas>=2.2; extra == 'all'
Requires-Dist: pandera[io]>=0.31; extra == 'all'
Requires-Dist: psutil>=5.9; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1.12; extra == 'all'
Requires-Dist: s3fs>=2024.6.0; extra == 'all'
Requires-Dist: skypilot[aws]>=0.14; extra == 'all'
Provides-Extra: aws
Requires-Dist: botocore>=1.35.16; extra == 'aws'
Requires-Dist: s3fs>=2024.6.0; extra == 'aws'
Requires-Dist: skypilot[aws]>=0.14; extra == 'aws'
Provides-Extra: runpod
Requires-Dist: botocore>=1.35.16; extra == 'runpod'
Requires-Dist: s3fs>=2024.6.0; extra == 'runpod'
Requires-Dist: skypilot[aws]>=0.14; extra == 'runpod'
Requires-Dist: skypilot[runpod]>=0.14; extra == 'runpod'
Provides-Extra: s3
Requires-Dist: s3fs>=2024.6.0; extra == 's3'
Provides-Extra: sql
Requires-Dist: duckdb>=1.2; extra == 'sql'
Provides-Extra: tracking
Requires-Dist: mlflow>=3.9; extra == 'tracking'
Requires-Dist: nvidia-ml-py>=12; extra == 'tracking'
Requires-Dist: psutil>=5.9; extra == 'tracking'
Requires-Dist: psycopg[binary]>=3.1.12; extra == 'tracking'
Provides-Extra: validate
Requires-Dist: pandas>=2.2; extra == 'validate'
Requires-Dist: pandera[io]>=0.31; extra == 'validate'
Description-Content-Type: text/markdown

# fieldbook

fieldbook is a lightweight toolkit for machine-learning experimentation. It versions datasets, records how every result was produced (code, environment, data, seed), tracks experiments, and runs the same script on your machine or on a rented cloud GPU.

- **Low overhead.** There are no servers to deploy or operate. fieldbook is a Python package and a command-line tool; its state lives in your repository, a storage folder or bucket, and a database file. A shared project adds only a bucket and a managed database.
- **Cloud-agnostic by design.** Storage is addressed by URI and compute is launched through [SkyPilot](https://github.com/skypilot-org/skypilot), so no provider's services are built in, and research code does not change between a laptop and the cloud. Verified so far: AWS S3 for storage, AWS and RunPod for compute.
- **Agent-friendly.** Coding agents can use it as well as people can: every command has machine-readable output, what an agent runs is attributed to it, results carry notes for the next session, and a project can hold instructions that tell an agent how to work in it.

It is built from open-source components (Lance, MLflow, SkyPilot, DuckDB) and suits one person on one machine as well as a project shared between several. Status: alpha. See the [design](design/README.md).

## Quick start

Requires macOS or Linux (Windows is not supported; WSL should work but is untested), Python 3.11+, git, and [gitleaks](https://github.com/gitleaks/gitleaks) (`brew install gitleaks`).

```bash
pip install "fieldbook[all]"
cd my-project && fieldbook init

fieldbook data add pets ./images --set label=unknown    # a versioned dataset
fieldbook run train.py                                  # code, environment, and data recorded
fieldbook log                                           # what has been run
fieldbook log ui                                        # MLflow UI until Ctrl-C
```

Read the [user guide](docs/guide.md) next.

## Documentation

User documentation (`docs/`):

- [docs/guide.md](docs/guide.md): user guide
- [docs/releasing.md](docs/releasing.md): versions and releases
- [CHANGELOG.md](CHANGELOG.md)

Design (`design/`):

- [design/README.md](design/README.md): what fieldbook is, requirements, how the parts fit, and an index of the documents below
- [design/projects.md](design/projects.md): projects, settings, credentials
- [design/storage.md](design/storage.md): the storage root; local disk and S3
- [design/data.md](design/data.md): versioned datasets
- [design/runs.md](design/runs.md): `fieldbook run`, code snapshots, seeds, smoke runs
- [design/tracking.md](design/tracking.md): MLflow tracking, the model registry, costs
- [design/cloud-runs.md](design/cloud-runs.md): runs on cloud GPUs
- [design/sharing.md](design/sharing.md): projects shared between people
- [design/testing.md](design/testing.md): how the tests are organized

## Privacy

fieldbook collects nothing and sends nothing anywhere but the storage, database, and cloud accounts you configure. One of its dependencies does: SkyPilot, used for cloud runs (the `aws` and `runpod` extras), reports anonymous usage statistics to its developers unless `SKYPILOT_DISABLE_USAGE_COLLECTION=1` is set.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Report security problems as described in [SECURITY.md](SECURITY.md), not in a public issue.

## Development

Requires [uv](https://docs.astral.sh/uv/) and gitleaks.

```bash
uv sync            # create .venv and install dependencies
uv run fieldbook --help  # run the CLI
uv run pytest      # run tests, one worker per core
uv run pytest -m "not slow"  # skip the MLflow server tests
uv run ruff check  # lint
uv run ruff format # format
```

CI (`.github/workflows/ci.yml`) runs lint and tests on Linux (Python 3.11–3.13, with Postgres) and macOS, and once more at the lowest dependency versions allowed.

## License

Apache-2.0
