Metadata-Version: 2.4
Name: jovykit
Version: 3.0.4
Summary: Layered Jupyter container images and project-local JovyKit environments.
Project-URL: Homepage, https://github.com/MihneaTeodorStoica/jovykit
Project-URL: Repository, https://github.com/MihneaTeodorStoica/jovykit
Project-URL: Issues, https://github.com/MihneaTeodorStoica/jovykit/issues
Project-URL: Changelog, https://github.com/MihneaTeodorStoica/jovykit/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/MihneaTeodorStoica/jovykit/tree/main/docs
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: textual
Requires-Dist: tomlkit
Requires-Dist: typer
Dynamic: license-file

# JovyKit

JovyKit provides layered Jupyter notebook container images for data science,
machine learning, and research workflows.

The images are designed as progressively larger environments, so users can pick
the smallest image that fits their workload:

- `minimal`: Jupyter runtime plus the core scientific Python stack.
- `base`: everyday data science, classical machine learning, statistics, and
  local data access.
- `extended`: advanced machine learning, NLP, time series, distributed compute,
  and API tooling.
- `full`: heavy frameworks, generative AI tooling, graph and geospatial
  analysis, big data, and additional research utilities.

## Images

Published image variants use the following naming pattern:

```text
ghcr.io/mihneateodorstoica/jovykit-TYPE:latest
ghcr.io/mihneateodorstoica/jovykit-TYPE:nightly
ghcr.io/mihneateodorstoica/jovykit-TYPE:lts
```

`TYPE` is one of `minimal`, `base`, `extended`, or `full`.

All image variations include client-side SSH tooling for Git remotes, file
copying, and SSH-backed sync:

- `ssh`, `scp`, and `sftp` from OpenSSH
- `git`
- `rsync`

## Build Locally

Build a specific image target from the repository root:

```bash
docker build --target minimal -t jovykit-minimal ./image
docker build --target base -t jovykit-base ./image
docker build --target extended -t jovykit-extended ./image
docker build --target full -t jovykit-full ./image
```

## CLI

JovyKit includes a CLI for project-local container environments. The mental
model is:

```text
.jovy is to JovyKit what .venv is to Python.
```

Create an environment, add project packages, and run Jupyter:

```bash
jovy init .jovy --image base --gpus auto
jovy add pandas scikit-learn plotly
jovy install
jovy run
```

Run `jovy` with no subcommand to open the interactive terminal dashboard for
the current project. The dashboard shows environment status, recent logs, and a
`jovy>` command line for common operations. Closing the dashboard with `quit` or
`exit` does not stop the container; use `jovy down` or `down` inside the
dashboard when you want to stop it.

The CLI creates a local `work/` directory for project files and writes a
root `jovy.toml` plus a reproducible overlay build recipe under `.jovy/`:

```text
jovy.toml
work/
.jovy/
  jovy.lock
  Containerfile
  compose.yaml
  state.json
```

Useful commands:

```bash
jovy --version
jovy
jovy status
jovy status --json
jovy remove plotly
jovy add -r requirements.txt
jovy install
jovy install --upgrade
jovy up --no-build
jovy down --timeout 10
jovy restart
jovy build --pull
jovy run --watch
jovy logs --tail 100 --since 10m --timestamps --no-follow
jovy shell -c "python --version"
jovy exec python --version
jovy clean
jovy destroy --keep-image
```

Most commands accept `--env PATH` when you want to operate on a JovyKit
environment outside the current project tree. `jovy init` also supports
customizing the generated project name, overlay image name/tag, Jupyter port,
GPU mode, Jupyter token, Jupyter log level, and mounted work directory. The
default token is `jovykit`, so JovyKit does not rely on Jupyter's generated
token.
Docker Compose watch runs with `jovy run`; `jovy up` stays detached and starts
a lightweight watcher that restarts the container when `jovy.toml` changes.
Use `jovy up` for background startup, `jovy down` to stop the environment, and
`jovy run` when you want attached foreground Jupyter logs.

`jovy.toml` stores direct project packages under `[python].packages`. JovyKit
compiles them with uv into `.jovy/jovy.lock`, and Docker installs from that
lockfile. `jovy.toml` can also customize runtime environment variables, extra
volumes, restart policy, Jupyter command/logging, Compose Watch behavior, image
build arguments, build target/platform, apt packages, and uv/pip install
options.

## Repository Layout

```text
jovykit/              Python CLI package
image/               Dockerfile and layered image dependency manifests
docs/                mdBook documentation
.github/workflows/   CI, security, docs, and image publishing automation
```

## Documentation

The mdBook source lives in `docs/src`.

To build the documentation locally:

```bash
mdbook build docs
```

## Testing

Run the default deterministic test suite with coverage:

```bash
pytest --cov=jovykit --cov-report=term-missing --cov-fail-under=90
```

Docker-facing smoke tests are opt-in so routine CI and local test runs stay
fast and deterministic:

```bash
pytest -m docker --run-docker
```

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
development workflow and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
expectations.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).
