Metadata-Version: 2.5
Name: nextron-cloud
Version: 0.1.0rc1
Summary: Official Python client for the NexTron Cloud fine-tuning API.
Project-URL: Homepage, https://nextron.physionlabs.ai
Project-URL: Issues, https://github.com/Physion-Labs/nextron-python/issues
Author-email: Physion Labs <support@physionlabs.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: fine-tuning,nextron,physion,training
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.9
Description-Content-Type: text/markdown

# nextron-cloud

> **Release candidate.** The API may still change before 0.1.0; install with `--prerelease=allow`.

Python SDK and CLI for [NexTron Cloud](https://nextron.physionlabs.ai): fine-tune open models with one request
(model + dataset + settings) and download the trained checkpoint.

```bash
uv venv && uv pip install --prerelease=allow nextron-cloud   # or, in a uv project: uv add --prerelease=allow nextron-cloud
export NEXTRON_API_KEY="nk_live_..."                           # API keys page on nextron.physionlabs.ai
uv run nextron-cloud models                                    # what can be trained now, at what price
```

Commands below are written as `nextron-cloud ...`; run them with `uv run` (or activate `.venv`).

```python
from nextron_cloud import NexTron

client = NexTron()
dataset = client.datasets.wait(client.datasets.upload("train.jsonl").id)   # checked locally, then by the server
draft = dict(model="qwen3.8-27b", dataset_id=dataset.id, params={"train_type": "lora", "learning_rate": 1e-4})
print(client.jobs.estimate(**draft))                                        # cost in US cents: get a yes first

job = client.jobs.wait(client.jobs.create(**draft, name="first try").id)  # only after the cost is approved
print(job.state, client.jobs.metrics(job.id)[-1])

client.jobs.wait_checkpoint(job.id)                                         # later: weights stay 30 days
client.jobs.download_checkpoint(job.id, f"checkpoints/{job.id}")
```

## Start with an agent

Install, set the key, then paste this to your coding agent (Claude Code, Codex, ...) and fill in the brackets:

```text
Run a fine-tuning experiment for me on NexTron Cloud, a managed training service: one request trains a model on
its GPUs and leaves a checkpoint to download.

Setup
- Install the SDK with uv in this project: `uv venv && uv pip install --prerelease=allow nextron-cloud`
  (in a uv project: `uv add --prerelease=allow nextron-cloud`). Run its commands with `uv run`, e.g.
  `uv run nextron-cloud guide`.
- My API key is in the environment variable NEXTRON_API_KEY. Never print it or write it into a file.
- Before anything else run `uv run nextron-cloud guide` and read all of it. At each step read its topic too:
  `nextron-cloud guide data`, `... training`, `... monitoring`, `... checkpoints`, `... api`. Follow its rules.

The experiment
- Goal: [what the model should do better, e.g. "answer our support tickets in our tone and format"]
- Data: [file path or Hugging Face link, and which fields are the input and which the answer]
- How I will judge it: [e.g. "held-out tickets, compared with the base model"]
- Model: [a model id, or "pick one from `nextron-cloud models` and tell me why"]
- Budget: at most $[N] for this experiment unless I approve more.

How to work
- Prepare and check the data, hold out a validation set, upload, and plan a small first run.
- Before anything that costs money, show me the model, settings, estimated cost, steps, time and warnings, and
  wait for my yes. Never start a job I have not approved.
- Give every job a name and a tag for this experiment.
- While jobs run, watch them (`nextron-cloud jobs progress` / `jobs events`) and tell me at once if one fails or
  stalls.
- When training ends, report loss and validation loss, what was charged, what you conclude, and what you would try
  next. Download checkpoints only when I ask.
- Keep everything you write in this project directory.
```

## Documentation

The guide is written for people and coding agents alike, in [skills/nextron-cloud](skills/nextron-cloud/SKILL.md):

- [SKILL.md](skills/nextron-cloud/SKILL.md): setup, rules, an experiment end to end
- [data.md](skills/nextron-cloud/references/data.md): the sample format, what training learns from, checks
- [training.md](skills/nextron-cloud/references/training.md): models, params, batch, cost and time, sweeps
- [monitoring.md](skills/nextron-cloud/references/monitoring.md): states, metrics, failures, API errors
- [checkpoints.md](skills/nextron-cloud/references/checkpoints.md): download, serve, evaluate
- [api.md](skills/nextron-cloud/references/api.md): every SDK call and CLI command
- [examples/compare_outputs.py](examples/compare_outputs.py): answer held-out prompts with the fine-tuned and the base
  model side by side

Claude Code: `/plugin install nextron-cloud --marketplace Physion-Labs/nextron-python` installs it as a skill.
Other agents: point them at [AGENTS.md](AGENTS.md).
