Metadata-Version: 2.4
Name: keras-kinetic
Version: 0.0.2
Summary: Run Keras models remotely on TPU seamlessly.
Project-URL: Homepage, https://github.com/keras-team/kinetic
Project-URL: Issues, https://github.com/keras-team/kinetic/issues
Author-email: Keras team <keras-users@googlegroups.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: absl-py
Requires-Dist: cloudpickle
Requires-Dist: google-auth>=2.49
Requires-Dist: google-cloud-artifact-registry>=1.11
Requires-Dist: google-cloud-billing>=1.19
Requires-Dist: google-cloud-build>=3.36
Requires-Dist: google-cloud-compute>=1.47
Requires-Dist: google-cloud-container>=2.64
Requires-Dist: google-cloud-iam>=2.20
Requires-Dist: google-cloud-resource-manager>=1.17
Requires-Dist: google-cloud-service-usage>=1.16
Requires-Dist: google-cloud-storage>=3.10
Requires-Dist: keras
Requires-Dist: kubernetes>=35.0
Requires-Dist: numpy
Requires-Dist: pyopenssl>=26.0
Requires-Dist: requests>=2.33
Requires-Dist: rich>=14.0
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Requires-Dist: google-cloud-secret-manager>=2.20; extra == 'cli'
Requires-Dist: pulumi-command>=1.0; extra == 'cli'
Requires-Dist: pulumi-gcp>=9.0; extra == 'cli'
Requires-Dist: pulumi-kubernetes>=4.0; extra == 'cli'
Requires-Dist: pulumi>=3.0; extra == 'cli'
Provides-Extra: demo
Requires-Dist: jax; extra == 'demo'
Requires-Dist: keras; extra == 'demo'
Requires-Dist: keras-hub; extra == 'demo'
Requires-Dist: numpy; extra == 'demo'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: click>=8.1; extra == 'dev'
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: google-cloud-secret-manager>=2.20; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pulumi-command>=1.0; extra == 'dev'
Requires-Dist: pulumi-gcp>=9.0; extra == 'dev'
Requires-Dist: pulumi-kubernetes>=4.0; extra == 'dev'
Requires-Dist: pulumi>=3.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx-book-theme; extra == 'docs'
Requires-Dist: sphinx-click; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-llm; extra == 'docs'
Provides-Extra: release
Requires-Dist: build; extra == 'release'
Requires-Dist: twine; extra == 'release'
Provides-Extra: test
Requires-Dist: coverage>=7.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.0; extra == 'test'
Description-Content-Type: text/markdown

# Kinetic

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

Run Keras and JAX workloads on cloud TPUs and GPUs with a simple decorator. No infrastructure management required.

```python
import kinetic

@kinetic.run(accelerator="tpu-v5e-1")
def train_model():
    import keras
    model = keras.Sequential([...])
    model.fit(x_train, y_train)
    return model.history.history["loss"][-1]

# Executes on a TPU v5e-1 slice, returns the result locally
final_loss = train_model()
```

## Why Kinetic

- **Simple remote execution.** A `@kinetic.run()` decorator runs the
  function on the accelerator you ask for and returns the result.
  Nothing else changes about your code.
- **Detached jobs.** Switch to `@kinetic.submit()` for long runs.
  You get a `JobHandle` back — poll status, tail logs, collect the
  result later, or reattach from another machine entirely.
- **Data and checkpoint support.** Wrap inputs in `kinetic.Data(...)`
  to ship local files (or stream from GCS) into the job. Write durable
  outputs and resumable checkpoints under `KINETIC_OUTPUT_DIR`.

## Install

```bash
uv pip install keras-kinetic
```

This installs both the decorator and the `kinetic` CLI.

## One-time setup

If nobody on your team has provisioned a Kinetic cluster yet, run:

```bash
kinetic up
```

This enables the required GCP APIs, creates an Artifact Registry
repository, provisions a GKE cluster with an accelerator node pool,
and configures local Docker / `kubectl` access. Run `kinetic down`
when you're finished to tear everything back down.

## Recommended first run

```bash
export KINETIC_PROJECT="your-gcp-project-id"
python examples/fashion_mnist.py
```

The first run takes ~5 minutes (it builds a container image with your
dependencies via Cloud Build). Subsequent runs with unchanged
dependencies start in under a minute.

For the full first-run walkthrough, see the
[Getting Started](https://kinetic.readthedocs.io/en/latest/getting_started.html)
guide.

## Where to go next

| Question                                         | Where to look                                                                                                                                             |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How do I get my first job running?               | [Getting Started](https://kinetic.readthedocs.io/en/latest/getting_started.html)                                                                          |
| When should I use `submit()` instead of `run()`? | [Detached Jobs](https://kinetic.readthedocs.io/en/latest/advanced/async_jobs.html)                                                                        |
| How do I ship data and persist outputs?          | [Data](https://kinetic.readthedocs.io/en/latest/guides/data.html) and [Checkpointing](https://kinetic.readthedocs.io/en/latest/guides/checkpointing.html) |
| Bundled vs prebuilt vs custom image — which one? | [Execution Modes](https://kinetic.readthedocs.io/en/latest/guides/execution_modes.html)                                                                   |
| Something's broken; where do I start?            | [Troubleshooting](https://kinetic.readthedocs.io/en/latest/troubleshooting.html)                                                                          |

## Configuration

Kinetic reads `KINETIC_PROJECT` (required), `KINETIC_ZONE`,
`KINETIC_CLUSTER`, and a handful of other environment variables. The
short version:

```bash
export KINETIC_PROJECT="your-project-id"      # required
export KINETIC_ZONE="us-central1-a"           # optional
export KINETIC_CLUSTER="kinetic-cluster"      # optional
```

The full surface — every variable, every CLI flag, and how the
precedence rules combine them — lives in the
[Configuration reference](https://kinetic.readthedocs.io/en/latest/configuration.html).

## Contributing

See the [Contributing guide](https://kinetic.readthedocs.io/en/latest/contributing.html).

## License

[Apache 2.0](LICENSE)
