Quickstart

Creation paths for ML teams

Three ways to fine-tune a base model on custom data.

BrewSLM exposes the same small language model training workflow through a CLI, an HTTP/Python API, and the workspace UI. Pick the surface that matches how your team works, not a different feature tier.

At-a-glance

Fit by team shape

CLI

You already script your ML lifecycle. You want one binary per stage, exit codes, and stdout you can grep.

First milestone: a scripted import + train + export job under CI.

HTTP / Python API

The SLM lifecycle is one piece of a larger backend. You want the same pipeline as a service call.

First milestone: a service-triggered import + run flow with task-id polling.

The workspace

You're new to this, a non-shell user, or just want to see what's happening. Six places per project — Overview, Data, Train, Results, Ship, Settings — with inline Coach notices where they apply.

First milestone: a starter project trained and scored without typing a flag.

CLI

Shell-first, scriptable, no hidden state

The subcommand surface

$ python -m app.cli.dataset_import sources

csv hf jsonl kaggle

 

$ python -m app.cli.dataset_import mappers

bio_to_spans → task_profile=structured_extraction

chat_messages_passthrough → task_profile=chat_sft

kv_to_structured → task_profile=structured_extraction

label_to_classification → task_profile=classification

preference_pair → task_profile=dpo

qa_pair_passthrough → task_profile=qa

rag_passthrough → task_profile=rag_qa

text_only → task_profile=language_modeling

 

$ python -m app.cli.dataset_import introspect \

    --locator hf:imdb:train

 

$ python -m app.cli.dataset_import run \

    --locator hf:imdb:train --project 1 --auto --limit 5000

Flag highlights

  • --auto picks the mapper from the introspector's top proposal (gated at 0.80 confidence).
  • --force overrides the confidence gate. Pairs with --auto.
  • --map K=V + --map-json '{…}' override the auto-suggested field map.
  • --drop REASON bulk-drops a rejection category (counts stay in the audit).
  • --limit N stops after N source rows.
  • --llm-assist (opt-in) lets the teacher model propose a mapping when confidence is low.

Every command is also exposed via HTTP. The CLI is a thin wrapper over the same service functions the API hits.

HTTP / Python API

Same pipeline, callable from any service

Import: introspect → preview → run

POST /api/dataset-import/introspect

  { "locator": "hf:imdb:train", "sample_size": 20 }

 

POST /api/projects/1/dataset-import/preview

  { "locator": "hf:imdb:train",

    "mapper_id": "label_to_classification",

    "field_map": { "text_field": "text", "label_field": "label" },

    "sample_cap": 5 }

 

POST /api/projects/1/dataset-import/run

  { "locator": "hf:imdb:train",

    "mapper_id": "label_to_classification",

    "field_map": { "text_field": "text", "label_field": "label" },

    "drop_reasons": ["missing_text"] }

Save once, re-run forever

# 1. Save the mapping after the first import lands.

POST /api/projects/1/dataset-import/configs

  { "name": "weekly-pii-refresh",

    "locator": "kaggle:competition:pii-detection-…",

    "mapper_id": "bio_to_spans",

    "field_map": {…} }

 

# 2. Re-run anytime against the (refreshed) source.

POST /api/projects/1/dataset-import/configs/12/run

 

# 3. Read the audit stream.

GET /api/projects/1/run-events?stage=ingestion

The workspace

Start a project, land on its Overview

The projects home has one button and one shelf. + New Project asks for a name and "What problem do you want this model to solve?" and sets the defaults from the answer (base model, task profile, output schema — all changeable later; manifest import sits under Advanced options). Below it, Or begin with a starter project: three quick demos with data and an answer key already in place (Demo · PII / PCI Detector, Demo · Sentiment classifier, Demo · Support FAQ — "Open demo") and a row of starters with data and an answer key ("Use this starter"). Every path lands on the project's Overview.

The projects home: a search box with All / Draft / Active / Completed filters, a + New Project button top right, Starter projects — quick demos (Demo · PII / PCI Detector, Demo · Sentiment classifier, Demo · Support FAQ, each with Open demo), and Starter projects: with data and answer key (Agent Tool-Call Fine-Tune, Contract Clause Extractor, Data-to-SQL Assistant, Email/Chat Tone Adapter, each with Use this starter)
The projects home: + New Project, or begin with a starter project.
The New BrewSLM Project dialog: Project Name, a text area asking What problem do you want this model to solve?, a note that BrewSLM will analyze it and set sensible defaults, a collapsed Advanced options section, and Cancel / Create project buttons
+ New Project: a name and a brief in plain words. Advanced options holds the manifest import.

Data — five steps

  • Sources: upload files, Import dataset (auto-mapping), or let a model write sample documents.
  • Prepare: clean and chunk, redact PII & secrets.
  • Labels: confirm the task shape, build the answer key.
  • Generate: synthetic rows (Q&A, multi-turn, spans) from a local or cloud model.
  • Split: train / validation / test; keep the test examples on later splits.

Train, then Results

  • Train is one form: base model, task, one run or three seeds, run name, Train. Hyperparameters, LoRA, checks and presets are under More options.
  • Results → Verdict: did it beat its base model, and did the pass/fail rules pass.
  • Failures / Compare / Try it: where it fails, how it compares, and a chat with the run.

Ship

  • Package: a new export (Hugging Face, GGUF, ONNX, Docker…) and the Releases table.
  • Publish: a completed Hugging Face export to the Hub.
  • Deploy / Monitor: serve plans and served versions; run events, failure clusters, drift.

Importing in the workspace

Four steps. Same pipeline. No flags.

Data → Sources → Import dataset (auto-mapping) opens the import wizard. It runs the same introspector and mappers as the CLI and the API.

Data → Sources, step 1 of 5 (Sources, Prepare, Labels, Generate, Split): a step tip with a Watch the walkthrough link, two Coach notices, the card No documents yet? Write sample documents, and the card Import dataset (auto-mapping) with an Import dataset button
Data → Sources: sample documents, or Import dataset (auto-mapping). Uploads sit on the same step.

1 — Source · 2 — Task type

  • Source dropdown (jsonl / csv / hf / kaggle) or a browser upload.
  • Per-source helper text + auth banner for gated datasets.
  • Click Introspect; confirm the task type the sniffer proposes.

3 — Map

  • Column-signatures table (detected type + confidence per column).
  • Ranked-hypothesis dropdown pre-selected to the top proposal.
  • JSON field-map editor for overrides. Low-confidence proposals show a banner until you confirm you reviewed the proposal.

4 — Preview & Confirm

  • Summary cards (accepted, rejected, mapper, target profile).
  • Rejected rows grouped by reason; tick to bulk-drop.
  • "Save this mapping" persists the config for one-click re-runs from the Saved mappings panel on the same step.
  • Final Import commits + emits the audit RunEvent.

Learn The Concept

The lessons behind the three surfaces

The CLI, API, and workspace all wrap the same fine-tuning mechanics. These lessons help you decide what your team is doing when it picks a dataset format, adapts a base model, or moves from a notebook workflow into a platform.

Pick a door

All three lead to the same project

You can switch surfaces mid-project. A workspace import is indistinguishable from a CLI import in the audit log; a saved mapping created from the UI is callable from the API; everything composes.

# CLI

$ python -m app.cli.dataset_import run --locator hf:imdb:train --project 1 --auto

 

# API

$ curl -X POST localhost:8000/api/projects/1/dataset-import/run \

    -H 'Content-Type: application/json' \

    -d '{"locator":"hf:imdb:train","mapper_id":"label_to_classification","field_map":{}}'

 

# UI

# Data → Sources → "Import dataset (auto-mapping)" → Source → Task type → Map → Preview & Confirm