Metadata-Version: 2.5
Name: starforge-core
Version: 0.3.22
Summary: StarForge client: JobSpec / recipe contract, job-side runner, and sf CLI.
Project-URL: Homepage, https://github.com/wccdev/starforge
Project-URL: Documentation, https://github.com/wccdev/starforge
Project-URL: Repository, https://github.com/wccdev/starforge
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: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
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 a separate install, `starforge-server`. Training images do not need this whole package; the server injects a runner that carries the kernel only.

## Install

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

sf --help
```

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

`pip 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 简体中文)
