krauncher 0.1.0__tar.gz

krauncher-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+dist/
+*.egg-info/
+.venv/
+calibration/
+/test*.sh
+/hello.txt
+/pp.py
+.env
+temp/

krauncher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Sergeev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

krauncher-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: krauncher
+Version: 0.1.0
+Summary: Run Python functions and notebook cells on the cheapest suitable remote GPU — per-task billing, no instances
+Project-URL: Homepage, https://krauncher.com
+Project-URL: Repository, https://github.com/Ilya-a-sergeyev-ger/krauncher
+Author: Ilya Sergeev
+License: MIT
+License-File: LICENSE
+Keywords: cloud,gpu,jupyter,machine-learning,remote-execution,task
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: grpcio>=1.80
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: protobuf>=4.25
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Krauncher
+
+**Run your training script on a remote GPU. Nothing more.**
+
+Krauncher is a minimal Python library for researchers who have a working
+local script and need a GPU — not a platform.
+
+Website & API keys: **[krauncher.com](https://krauncher.com)**
+
+---
+
+## Quickstart
+
+```bash
+pip install krauncher
+export CAS_API_KEY="cas_..."        # krauncher.com → Account → API Keys
+```
+
+Requires Python 3.11+.
+
+```python
+import asyncio
+from krauncher import KrauncherClient
+
+client = KrauncherClient()           # reads CAS_API_KEY / CAS_BROKER_URL from env or .env
+
+@client.task(vram_gb=1, timeout=120)
+def multiply(size: int):
+    import numpy as np               # imports go INSIDE the function
+    a, b = np.random.rand(size, size), np.random.rand(size, size)
+    return {"mean": float((a @ b).mean())}
+
+async def main():
+    handle = await multiply(size=1000)   # submit → TaskHandle
+    print("task:", handle.task_id)
+    result = await handle                # await the handle → TaskResult
+    print("output:", result.output)
+    print("gpu:", result.actual_gpu, "·", f"{result.execution_time_sec:.1f}s")
+
+asyncio.run(main())
+```
+
+The decorated function becomes **async**: calling it submits the task and
+returns a `TaskHandle`; awaiting the handle (or `await handle.wait(...)`)
+returns a `TaskResult`.
+
+> **Using an LLM / coding agent?** Read **[AGENTS.md](AGENTS.md)** — a single
+> accurate reference of the API, parameters, result fields, errors and
+> constraints. Runnable examples live in **[tutorial/](tutorial/)**.
+
+---
+
+## The problem with serverless ML platforms
+
+Serverless orchestration platforms are genuinely impressive pieces of
+infrastructure. They handle container builds, secret management, artifact
+storage, scheduling, persistent volumes, and team dashboards.
+
+They also charge you for all of it — whether you use it or not.
+
+If you're fine-tuning a small model, running ablations, or iterating on
+a research experiment with a dataset under 2 GB, you're likely paying for
+an orchestration layer you don't need.
+
+Krauncher does less, on purpose. It runs your existing Python function on
+a remote GPU, returns the result, and gets out of the way.
+
+---
+
+## What Krauncher is (and isn't)
+
+**Good fit:**
+- Fine-tuning, LoRA, small-scale experiments with training datasets up to ~2 GB
+- Researchers who already have a working local script
+- Anyone tired of rewriting their code to fit a platform's abstractions
+- Teams where "infrastructure" means one person and a credit card
+
+**Not the right tool if:**
+- You need managed versioned artifact storage
+- Your team requires persistent shared volumes across runs
+- Your dataset is hundreds of GBs with complex multi-node sharding
+- You want a UI dashboard for experiment tracking
+
+---
+
+## How it works
+
+Add a decorator. Await your function. Get a result. Your existing code
+doesn't change — no base images, no volume mounts, no platform imports.
+
+```python
+import asyncio
+from krauncher import KrauncherClient
+
+client = KrauncherClient()
+
+@client.task(gpu_name="RTX4090", group_id="mistral-run", timeout=3600)
+def finetune():
+    from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
+    from datasets import load_dataset
+
+    # Weights download to worker storage on first run (~15 GB for 7B);
+    # later runs in the same group_id reuse the cached weights.
+    model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
+    dataset = load_dataset("tatsu-lab/alpaca", split="train[:2000]")
+
+    # ... your training logic, unchanged from local ...
+
+    model.save_pretrained("/tmp/output")
+    # Worker storage is ephemeral — sync checkpoints out before returning.
+    upload_to_s3("/tmp/output", "my-checkpoints/run-1")
+    return {"status": "done", "checkpoint": "s3://my-checkpoints/run-1"}
+
+async def main():
+    result = await finetune()        # submit and wait
+    print(result.output)
+
+asyncio.run(main())
+```
+
+> The decorated function is **async** — always call it from an `async`
+> context and `await` the handle (which submits and waits). See the
+> [Quickstart](#quickstart) for the canonical shape.
+
+### Choosing a GPU
+
+| Decorator argument          | Effect                                                        |
+|-----------------------------|--------------------------------------------------------------|
+| `vram_gb=24`                | Require at least 24 GB VRAM                                   |
+| `gpu_name="H100"`           | Require a specific model (case-insensitive substring)        |
+| `gpu_arch="Ada"`            | Require a GPU architecture                                    |
+| *(omit `vram_gb`)*          | **Auto-classify**: the analyzer inspects your code and picks the VRAM tier for you |
+
+Leaving `vram_gb` unset is the recommended default — Krauncher analyzes your
+code statically and sizes the GPU automatically.
+
+---
+
+## Security model
+
+Krauncher doesn't store anything. Your API key and training code are
+encrypted on your machine before leaving it, and decrypted only inside the
+ephemeral worker. The relay that routes your jobs cannot read the payload —
+it doesn't have the keys.
+
+| What                       | Visible to Krauncher |
+|----------------------------|----------------------|
+| Your storage credentials   | No                   |
+| Your training code         | No                   |
+| Your model weights/outputs | No                   |
+| Job timing and GPU type    | Yes                  |
+
+This isn't a feature we added. It's a consequence of not wanting to be in
+the data custody business. E2E encryption is on by default (`CAS_ENCRYPT=true`).
+
+---
+
+## Data locality
+
+Tasks with the same `group_id` are routed to the same physical host, so
+whatever your first run downloaded to local NVMe is still there for the next.
+
+```python
+@client.task(gpu_name="RTX4090", group_id="my-experiment-v1")
+def train_epoch(epoch: int):
+    import os
+    cache_path = "/tmp/dataset.bin"
+    if not os.path.exists(cache_path):
+        download_from_s3("my-bucket", "dataset.bin", cache_path)
+        # subsequent tasks in this group skip this step
+    run_training(cache_path, epoch=epoch)
+    return {"epoch": epoch, "status": "complete"}
+
+async def main():
+    for epoch in range(10):
+        await train_epoch(epoch=epoch)
+```
+
+For larger or registered datasets, use the **data bridge** (`data_urls=` /
+`data=`), which downloads into `/data` inside the sandbox — see
+[tutorial/06](tutorial/06_data_bridge.py) and
+[tutorial/15](tutorial/15_data_sources_s3.py).
+
+---
+
+## Inspecting a finished task
+
+After a task completes, the broker keeps a structured record — the same one
+the web UI renders on the task detail page.
+
+```python
+task   = await client.get_task(task_id)         # what GET /tasks/{id} returns
+report = await client.get_task_report(task_id)  # task + extended report
+```
+
+`get_task` returns status, timing breakdown (queue / download / pip / setup /
+execution), classification, costs, GPU and worker specs, and the result.
+
+`get_task_report` adds an extended `report` field: peak/average GPU
+utilization, peak VRAM, the actual GPU's hardware specs, and an estimated
+time/cost comparison across all known GPUs at the worker's measured host
+capabilities. It is intended as feedback for an LLM author of the user
+code — pure data, no interpretation.
+
+---
+
+## Examples
+
+Numbered, runnable tutorials in [`tutorial/`](tutorial/):
+
+| #   | File                              | Demonstrates                                  |
+|-----|-----------------------------------|-----------------------------------------------|
+| 01  | `01_remote_simple.py`             | Minimal submit + await                        |
+| 02  | `02_remote_with_deps.py`          | `pip=` dependencies in the sandbox            |
+| 03  | `03_error_handling.py`            | Catching `TaskError` / remote tracebacks      |
+| 04  | `04_timeout.py`                   | Execution timeout behaviour                   |
+| 05  | `05_task_groups.py`               | `group_id` host affinity                      |
+| 06  | `06_data_bridge.py`               | `data_urls=` downloads into `/data`           |
+| 09  | `09_streaming_logs.py`            | Live logs via `wait(on_log=...)`              |
+| 10  | `10_progress_bar.py`              | Progress reporting                            |
+| 11  | `11_e2e_encryption.py`            | End-to-end encryption                         |
+| 12  | `12_helper_functions.py`          | Shipping helper functions with the task       |
+| 13  | `13_bert_finetune.py`             | Real ML code → analyzer classification        |
+| 15  | `15_data_sources_s3.py`           | Registered S3 data sources                    |
+| 17  | `17_multiphase_training.py`       | Multi-phase training in one group             |
+| 18  | `18_resnet152_food101.py`         | ResNet-152 on Food-101                        |
+| 19  | `19_huggingface_dataset.py`       | HuggingFace dataset bridge                    |
+| 20  | `20_bert_imdb.py`                 | BERT fine-tuning on IMDB                       |
+| 21  | `21_qwen25_7b_lora_alpaca.py`     | Qwen2.5-7B LoRA fine-tuning                    |
+| 22  | `22_qwen25_7b_inference_gsm8k.py` | Qwen2.5-7B inference                           |
+| 23  | `23_gnn_node_classification_cora.py` | GCN node classification                    |
+| 30+ | `30_…`–`36_…`                     | LLM inference and batched inference           |
+
+---
+
+## Install
+
+```bash
+pip install krauncher
+export CAS_API_KEY="your_api_key"
+```
+
+Requires Python 3.11+.
+
+---
+
+## License
+
+MIT

krauncher-0.1.0/README.md

@@ -0,0 +1,249 @@
+# Krauncher
+
+**Run your training script on a remote GPU. Nothing more.**
+
+Krauncher is a minimal Python library for researchers who have a working
+local script and need a GPU — not a platform.
+
+Website & API keys: **[krauncher.com](https://krauncher.com)**
+
+---
+
+## Quickstart
+
+```bash
+pip install krauncher
+export CAS_API_KEY="cas_..."        # krauncher.com → Account → API Keys
+```
+
+Requires Python 3.11+.
+
+```python
+import asyncio
+from krauncher import KrauncherClient
+
+client = KrauncherClient()           # reads CAS_API_KEY / CAS_BROKER_URL from env or .env
+
+@client.task(vram_gb=1, timeout=120)
+def multiply(size: int):
+    import numpy as np               # imports go INSIDE the function
+    a, b = np.random.rand(size, size), np.random.rand(size, size)
+    return {"mean": float((a @ b).mean())}
+
+async def main():
+    handle = await multiply(size=1000)   # submit → TaskHandle
+    print("task:", handle.task_id)
+    result = await handle                # await the handle → TaskResult
+    print("output:", result.output)
+    print("gpu:", result.actual_gpu, "·", f"{result.execution_time_sec:.1f}s")
+
+asyncio.run(main())
+```
+
+The decorated function becomes **async**: calling it submits the task and
+returns a `TaskHandle`; awaiting the handle (or `await handle.wait(...)`)
+returns a `TaskResult`.
+
+> **Using an LLM / coding agent?** Read **[AGENTS.md](AGENTS.md)** — a single
+> accurate reference of the API, parameters, result fields, errors and
+> constraints. Runnable examples live in **[tutorial/](tutorial/)**.
+
+---
+
+## The problem with serverless ML platforms
+
+Serverless orchestration platforms are genuinely impressive pieces of
+infrastructure. They handle container builds, secret management, artifact
+storage, scheduling, persistent volumes, and team dashboards.
+
+They also charge you for all of it — whether you use it or not.
+
+If you're fine-tuning a small model, running ablations, or iterating on
+a research experiment with a dataset under 2 GB, you're likely paying for
+an orchestration layer you don't need.
+
+Krauncher does less, on purpose. It runs your existing Python function on
+a remote GPU, returns the result, and gets out of the way.
+
+---
+
+## What Krauncher is (and isn't)
+
+**Good fit:**
+- Fine-tuning, LoRA, small-scale experiments with training datasets up to ~2 GB
+- Researchers who already have a working local script
+- Anyone tired of rewriting their code to fit a platform's abstractions
+- Teams where "infrastructure" means one person and a credit card
+
+**Not the right tool if:**
+- You need managed versioned artifact storage
+- Your team requires persistent shared volumes across runs
+- Your dataset is hundreds of GBs with complex multi-node sharding
+- You want a UI dashboard for experiment tracking
+
+---
+
+## How it works
+
+Add a decorator. Await your function. Get a result. Your existing code
+doesn't change — no base images, no volume mounts, no platform imports.
+
+```python
+import asyncio
+from krauncher import KrauncherClient
+
+client = KrauncherClient()
+
+@client.task(gpu_name="RTX4090", group_id="mistral-run", timeout=3600)
+def finetune():
+    from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
+    from datasets import load_dataset
+
+    # Weights download to worker storage on first run (~15 GB for 7B);
+    # later runs in the same group_id reuse the cached weights.
+    model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
+    dataset = load_dataset("tatsu-lab/alpaca", split="train[:2000]")
+
+    # ... your training logic, unchanged from local ...
+
+    model.save_pretrained("/tmp/output")
+    # Worker storage is ephemeral — sync checkpoints out before returning.
+    upload_to_s3("/tmp/output", "my-checkpoints/run-1")
+    return {"status": "done", "checkpoint": "s3://my-checkpoints/run-1"}
+
+async def main():
+    result = await finetune()        # submit and wait
+    print(result.output)
+
+asyncio.run(main())
+```
+
+> The decorated function is **async** — always call it from an `async`
+> context and `await` the handle (which submits and waits). See the
+> [Quickstart](#quickstart) for the canonical shape.
+
+### Choosing a GPU
+
+| Decorator argument          | Effect                                                        |
+|-----------------------------|--------------------------------------------------------------|
+| `vram_gb=24`                | Require at least 24 GB VRAM                                   |
+| `gpu_name="H100"`           | Require a specific model (case-insensitive substring)        |
+| `gpu_arch="Ada"`            | Require a GPU architecture                                    |
+| *(omit `vram_gb`)*          | **Auto-classify**: the analyzer inspects your code and picks the VRAM tier for you |
+
+Leaving `vram_gb` unset is the recommended default — Krauncher analyzes your
+code statically and sizes the GPU automatically.
+
+---
+
+## Security model
+
+Krauncher doesn't store anything. Your API key and training code are
+encrypted on your machine before leaving it, and decrypted only inside the
+ephemeral worker. The relay that routes your jobs cannot read the payload —
+it doesn't have the keys.
+
+| What                       | Visible to Krauncher |
+|----------------------------|----------------------|
+| Your storage credentials   | No                   |
+| Your training code         | No                   |
+| Your model weights/outputs | No                   |
+| Job timing and GPU type    | Yes                  |
+
+This isn't a feature we added. It's a consequence of not wanting to be in
+the data custody business. E2E encryption is on by default (`CAS_ENCRYPT=true`).
+
+---
+
+## Data locality
+
+Tasks with the same `group_id` are routed to the same physical host, so
+whatever your first run downloaded to local NVMe is still there for the next.
+
+```python
+@client.task(gpu_name="RTX4090", group_id="my-experiment-v1")
+def train_epoch(epoch: int):
+    import os
+    cache_path = "/tmp/dataset.bin"
+    if not os.path.exists(cache_path):
+        download_from_s3("my-bucket", "dataset.bin", cache_path)
+        # subsequent tasks in this group skip this step
+    run_training(cache_path, epoch=epoch)
+    return {"epoch": epoch, "status": "complete"}
+
+async def main():
+    for epoch in range(10):
+        await train_epoch(epoch=epoch)
+```
+
+For larger or registered datasets, use the **data bridge** (`data_urls=` /
+`data=`), which downloads into `/data` inside the sandbox — see
+[tutorial/06](tutorial/06_data_bridge.py) and
+[tutorial/15](tutorial/15_data_sources_s3.py).
+
+---
+
+## Inspecting a finished task
+
+After a task completes, the broker keeps a structured record — the same one
+the web UI renders on the task detail page.
+
+```python
+task   = await client.get_task(task_id)         # what GET /tasks/{id} returns
+report = await client.get_task_report(task_id)  # task + extended report
+```
+
+`get_task` returns status, timing breakdown (queue / download / pip / setup /
+execution), classification, costs, GPU and worker specs, and the result.
+
+`get_task_report` adds an extended `report` field: peak/average GPU
+utilization, peak VRAM, the actual GPU's hardware specs, and an estimated
+time/cost comparison across all known GPUs at the worker's measured host
+capabilities. It is intended as feedback for an LLM author of the user
+code — pure data, no interpretation.
+
+---
+
+## Examples
+
+Numbered, runnable tutorials in [`tutorial/`](tutorial/):
+
+| #   | File                              | Demonstrates                                  |
+|-----|-----------------------------------|-----------------------------------------------|
+| 01  | `01_remote_simple.py`             | Minimal submit + await                        |
+| 02  | `02_remote_with_deps.py`          | `pip=` dependencies in the sandbox            |
+| 03  | `03_error_handling.py`            | Catching `TaskError` / remote tracebacks      |
+| 04  | `04_timeout.py`                   | Execution timeout behaviour                   |
+| 05  | `05_task_groups.py`               | `group_id` host affinity                      |
+| 06  | `06_data_bridge.py`               | `data_urls=` downloads into `/data`           |
+| 09  | `09_streaming_logs.py`            | Live logs via `wait(on_log=...)`              |
+| 10  | `10_progress_bar.py`              | Progress reporting                            |
+| 11  | `11_e2e_encryption.py`            | End-to-end encryption                         |
+| 12  | `12_helper_functions.py`          | Shipping helper functions with the task       |
+| 13  | `13_bert_finetune.py`             | Real ML code → analyzer classification        |
+| 15  | `15_data_sources_s3.py`           | Registered S3 data sources                    |
+| 17  | `17_multiphase_training.py`       | Multi-phase training in one group             |
+| 18  | `18_resnet152_food101.py`         | ResNet-152 on Food-101                        |
+| 19  | `19_huggingface_dataset.py`       | HuggingFace dataset bridge                    |
+| 20  | `20_bert_imdb.py`                 | BERT fine-tuning on IMDB                       |
+| 21  | `21_qwen25_7b_lora_alpaca.py`     | Qwen2.5-7B LoRA fine-tuning                    |
+| 22  | `22_qwen25_7b_inference_gsm8k.py` | Qwen2.5-7B inference                           |
+| 23  | `23_gnn_node_classification_cora.py` | GCN node classification                    |
+| 30+ | `30_…`–`36_…`                     | LLM inference and batched inference           |
+
+---
+
+## Install
+
+```bash
+pip install krauncher
+export CAS_API_KEY="your_api_key"
+```
+
+Requires Python 3.11+.
+
+---
+
+## License
+
+MIT