Metadata-Version: 2.4
Name: keras-kinetic
Version: 0.0.3
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/)
[![PyPI - Version](https://img.shields.io/pypi/v/keras-kinetic)](https://pypi.org/project/keras-kinetic/)

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.** Use `func.run_async()` 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`.

## Documentation
Comprehensive documentation is available at: https://kinetic.readthedocs.io

## Install

```bash
uv pip install "keras-kinetic[cli]"
```

The base `keras-kinetic` package installs the `@kinetic.run()`
decorator. The `[cli]` extra adds the dependencies the `kinetic` CLI
needs to provision and manage infrastructure. Drop the `[cli]` extra
only if you just need to submit jobs against an already-provisioned
cluster.

## One-time setup

```bash
kinetic init
```

This detects your local environment, then either joins an existing
Kinetic cluster in the project (your own or a teammate's — discovery
goes through the shared state bucket) or walks you through creating a
new one. It ends by saving a profile that becomes your active context
— subsequent commands pick up project, zone, and cluster automatically.

Behind the scenes, the Create path runs `kinetic up` to enable APIs,
provision a GKE cluster with an accelerator node pool, and configure
local Docker / `kubectl` access. Run `kinetic down` when you're done.

## Recommended first run

```bash
python examples/fashion_mnist.py
```

No environment variables needed — `kinetic init` set an active
profile. 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 `run_async()` 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

The recommended way to configure Kinetic is via a profile — the named
context that `kinetic init` creates and `kinetic profile ls | use`
manages. For ad-hoc overrides, every profile field also has a
`KINETIC_*` env-var equivalent (`KINETIC_PROJECT`, `KINETIC_ZONE`,
`KINETIC_CLUSTER`, `KINETIC_NAMESPACE`) and a matching CLI flag.

Precedence is: **CLI flag > `KINETIC_*` env var > active profile >
built-in default.**

The full surface — every variable, every CLI flag, and the profile
model — 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)
