Metadata-Version: 2.5
Name: starforge-core
Version: 0.3.34
Summary: StarForge client: JobSpec / recipe contract, job-side runner, and sf CLI.
Project-URL: Homepage, https://github.com/wccdev/starforge
Project-URL: Documentation, https://starforge.mintlify.site/
Project-URL: Repository, https://github.com/wccdev/starforge
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: grpo,llm,post-training,rlhf,sft,starforge
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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
Requires-Python: >=3.10
Requires-Dist: packaging>=24
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: data
Requires-Dist: datasets>=2.18; extra == 'data'
Provides-Extra: environments
Requires-Dist: openenv-core>=0.3.0; extra == 'environments'
Requires-Dist: starlette>=0.40; extra == 'environments'
Requires-Dist: uvicorn>=0.29; extra == 'environments'
Description-Content-Type: text/markdown

# starforge-core

Client for StarForge. You get the `sf` command and a Python package named `starforge`.

Use this to scaffold a lab, lock a post-training method, and submit jobs to a StarForge console. The control plane is not on PyPI: it ships as a container image and a Helm chart. Training images do not need this whole package; the server injects a runner that carries the kernel only.

## Install

```bash
uv tool install starforge-core
# or, without uv
pip install starforge-core

sf --help
```

`uv tool install` is recommended: it gives `sf` its own environment, and it is the
installation `sf update` can upgrade. Installed into a system Python, `sf update` refuses
rather than risk disturbing other tools there.

Upgrade with `sf update` — it detects how `sf` was installed and runs the right command,
or names the one you should run when upgrading in place would break something.

Python 3.10 or newer. Import name is `starforge`, not `starforge_core`.

`uv tool install "starforge-core[data]"` adds HuggingFace `datasets` for local prepare scripts.

## Start a lab

Do not clone the platform repo. This package writes a project for you:

```bash
sf init my-lab --yes
cd my-lab
sf login --server https://<your-console>
sf new my-grpo --method nemo-rl/grpo
sf validate my-grpo
sf submit my-grpo --profile h200:8
sf job logs
```

`sf methods` lists the catalog on the server you logged into. Methods look like `nemo-rl/grpo`, `verl/sft`, `trl/kto`, `openrlhf/ppo`, `evalkit/benchmark`, `custom/custom`.

Examples live in `starforge-tutorial`. Day-to-day work should be your own `sf init` tree.

## Python

Catalog methods already forward framework logs. Custom `train.sh` jobs that want console curves call:

```python
from starforge.report import init, log, finish

init()
log({"loss": 0.12}, step=1)
finish()
```

`starforge.spec_to_env` is the JobSpec to environment mapping used on both the client and the job. `starforge.get_recipe` / `starforge.recipe_names` read the bundled catalog.

## What this package contains

- `sf` CLI: init, login, experiments, submit, sweep, jobs, datasets, plugins, bench, serve
- JobSpec types and `spec_to_env`
- Recipe catalog and framework adapters (NeMo-RL, verl, TRL, OpenRLHF, evalkit, custom)
- Job-side reporter (`starforge.report`)

Cluster credentials stay on the server. Your laptop keeps an access token under `~/.forge/`.

## Docs and source

- Platform repo: https://github.com/wccdev/starforge
- User docs: `mintlify/` in that repo (English and 简体中文)
