Run your first decision.

Run the checkpoint locally, use the local playground, or join the waitlist for hosted API access.

Hosted API · waitlist

The hosted API and browser playground are not open for public access yet. Join the API waitlist to hear when access is available. The local Python and HTTP interfaces are documented below.

1. Install the package and weights

Use Python 3.10–3.12 and PyTorch 2.8.0 for your device. The commands below use CPU inference, so you can begin without a GPU. The download command requires the GitHub CLI and access to the repository.

git clone https://github.com/erphq/smalldecide.git
cd smalldecide
git checkout c321d7f0560578d7396f39e67cd0b9c6a44f03b9
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

python tools/download_model.py --output artifacts && \
  tar -xzf artifacts/smalldecide-model.tar.gz -C artifacts

The download helper verifies the pinned SHA-256 before reporting OK. Extraction runs only after verification succeeds. An existing verified download is reused.

The checkpoint is approximately 967 MB compressed and includes the tokenizer and merged weights. These commands use the September 18 source snapshot with frozen v0.3.0 weights (ec832471…). The release wheel is an older source snapshot. The public-data experiment uses different weights and is not this download.

2. Open the local playground

smalldecide playground --model artifacts/model --device cpu

Open http://127.0.0.1:8080 in your browser. Edit the state, add Choice, Score, or Noul questions, and inspect the actual checkpoint’s response. Keep the command running while using the playground.

The server binds to loopback and has no authentication. It is intended for local use. Hosted access is on the API waitlist.

3. Use it from Python

Load the checkpoint once, then reuse it across reviews. State can be text or JSON.

from smalldecide import SmallDecide, Choice, Noul, Score

model = SmallDecide.from_pretrained("artifacts/model", device="cpu")
result = model.review(
    {"message": "Please refund the duplicate charge on my invoice."},
    {
        "team": Choice("Which team handles this?", {
            "billing": "Charges and refunds",
            "technical": "Software faults",
        }),
        "refund": Noul("Is a refund requested?"),
        "priority": Score("Rate urgency.", [
            "Routine", "Time-sensitive", "Emergency",
        ]),
    },
)
print(result.to_dict())

Choice returns a label and probabilities; Noul returns P(true); Score returns the expected zero-based rubric index. Read the complete API reference →

4. Send a JSON request

smalldecide infer --model artifacts/model \
  --request examples/request.json --device cpu

The inference/training CLI defaults to CUDA when --device is omitted; the Python loader defaults to CPU. The examples explicitly select CPU.

The repository includes a request with all three question types. See a recorded CPU response from the released checkpoint. Model probabilities can vary slightly across devices.

5. Train on your own examples

Start with reviewed labels or a trustworthy verifier. Keep related records together using group, and separate train, validation, and test data. The repository includes an editable data generator:

python examples/generate_data.py --output data/custom \
  --train 3000 --validation 400 --test 400 --heldout 400
smalldecide validate --data data/custom
smalldecide train --data data/custom --output runs/my-model \
  --steps 1800 --updates 90 --max-length 4096 \
  --environments route,workflow,control \
  --policy-temperature 2 --device cuda

The generator teaches simple threshold rules. Replace its sampling and verifier functions with your own task. Training combines supervised learning, built-in environment RL, and validation-only calibration. Custom supervised data does not automatically create an RL reward for that domain. This command starts from the pinned Qwen base; it does not fine-tune the downloaded merged checkpoint. For continuation, --initial-checkpoint requires a compatible training adapter. The output checkpoint is runs/my-model/model; load it with the same playground or Python commands.

The released checkpoint used 28,234 prepared training decisions from public datasets, verifier-labelled tasks, and converted/redacted session execution examples. Private session rows are not distributed. A public-data recipe and your own data can train the same architecture, but cannot exactly reproduce this mixed-data checkpoint.

Full training recipe, provenance, and resume instructions ↗

Hardware and limits

Use --device cuda with a compatible GPU and PyTorch installation. Runtime memory grows with context length and candidate batch size. Each candidate repeats the state; a long candidate list is more expensive than a short one.

The checkpoint rejects prompts over 16,384 tokens per candidate. Training used a 4,096-token guard, so the larger inference limit does not establish long-context reliability.