Metadata-Version: 2.4
Name: krayne
Version: 0.1.0
Summary: CLI and SDK for creating, managing, and scaling Ray clusters on Kubernetes
Keywords: ray,kubernetes,kuberay,ml,distributed-computing,cluster-management,cli,sdk
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Dist: typer>=0.9,<1
Requires-Dist: rich>=13,<14
Requires-Dist: pydantic>=2,<3
Requires-Dist: kubernetes>=28,<32
Requires-Dist: pyyaml>=6,<7
Requires-Dist: questionary>=2,<3
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/roulbac/krayne
Project-URL: Documentation, https://roulbac.github.io/krayne/
Project-URL: Repository, https://github.com/roulbac/krayne
Project-URL: Issues, https://github.com/roulbac/krayne/issues
Project-URL: Changelog, https://github.com/roulbac/krayne/releases
Description-Content-Type: text/markdown

# Krayne

**CLI and SDK for creating, managing, and scaling Ray clusters on Kubernetes.**

Krayne wraps the [KubeRay](https://ray-project.github.io/kuberay/) operator behind a clean, opinionated interface so ML practitioners can get distributed compute without touching Kubernetes manifests.

## Quickstart

```bash
pip install krayne
```

Create a Ray cluster with a single command:

```bash
krayne create my-cluster --gpus-per-worker 1 --workers 2
```

Or use the Python SDK to define code and infrastructure together:

```python
import ray
from krayne.api import managed_cluster
from krayne.config import ClusterConfig, WorkerGroupConfig

config = ClusterConfig(
    name="hello-world",
    worker_groups=[WorkerGroupConfig(replicas=2)],
)

with managed_cluster(config) as managed:
    ray.init(managed.tunnel.client_url)     # ray://localhost:... (tunneled)

    @ray.remote
    def hello(x):
        return f"Hello from worker, {x}!"

    futures = [hello.remote(i) for i in range(4)]
    print(ray.get(futures))

    ray.shutdown()
# Tunnels closed, then cluster deleted
```

Tunnels are opened by default — access the dashboard, notebook, and other services via `localhost`:

```python
from krayne.api import managed_cluster
from krayne.config import ClusterConfig

config = ClusterConfig(name="my-cluster")

with managed_cluster(config) as managed:
    # Tunnel (localhost) URLs via managed.tunnel
    print(managed.tunnel.dashboard_url)  # http://localhost:...
    print(managed.tunnel.client_url)     # ray://localhost:...

    # In-cluster IPs via managed.cluster
    print(managed.cluster.dashboard_url) # http://10.0.0.1:8265
# Tunnels closed, then cluster deleted
```

## Features

- **Zero-config defaults** — every command works with no flags. Sensible defaults get you a working cluster instantly.
- **CLI and SDK** — the CLI is a thin shell over the Python SDK. Anything you do from the terminal, you can do from code.
- **Functional API** — stateless free functions, not class hierarchies. Easy to test, easy to compose.
- **Pydantic config** — validated configuration with YAML override support. No silent failures.
- **Rich output** — beautiful terminal tables via Rich, with `--output json` for scripting.

## CLI Overview

```
krayne create <name>      Create a new Ray cluster
krayne get                List clusters in a namespace
krayne describe <name>    Show detailed cluster info
krayne scale <name>       Scale a worker group
krayne delete <name>      Delete a cluster
```

All commands support `-n/--namespace`, `--output json`, and `--debug` flags.

## Documentation

Full documentation is available at the [Krayne docs site](https://roulbac.github.io/krayne/).

- [Getting Started](https://roulbac.github.io/krayne/guide/quickstart/)
- [CLI Reference](https://roulbac.github.io/krayne/reference/cli/)
- [Python SDK Reference](https://roulbac.github.io/krayne/reference/sdk/)
- [Configuration](https://roulbac.github.io/krayne/guide/configuration/)
- [Architecture](https://roulbac.github.io/krayne/architecture/)
- [Error Handling](https://roulbac.github.io/krayne/reference/errors/)

## Requirements

- Python 3.10+
- A Kubernetes cluster with the [KubeRay operator](https://ray-project.github.io/kuberay/) installed
- A valid kubeconfig (or running inside the cluster)

## Development

```bash
# Clone and install
git clone https://github.com/roulbac/krayne.git
cd krayne
uv sync

# Run tests
uv run pytest

# Run integration tests (sandbox is provisioned automatically by test fixtures)
uv run pytest -m integration
```

## License

Apache 2.0
