TrainingProject configuration reference

Define a project and protect its data

This is the schema 1.0 project contract. Save the Automatic example as training.json. Resolve paths within the project root, set the included reference model ID and keep the API key in the process environment. The configuration selects a paid teacher reference and an independently trainable student; it never downloads teacher weights.

Unknown keys are rejected. Model, data, rubric and output paths must resolve within the project root.
Teacher sharing applies only to approved training sources. Validation and final-test items stay local.
TrainingClient remains available for existing paid-job session workflows.

Project, model and teacher
Field or interface	Type or result	Default or exit code	Behavior and validation
`schema_version`	`string`	`"1.0"`	Use 1.0 exactly. Other schema versions are rejected until explicitly supported.
`mode`	`enum`	Required / no default	Required: automatic or advanced. Automatic resolves compatible defaults; Advanced exposes explicit controls.
`objective`	`string`	Required / no default	Required task description, 10–4000 characters. Name the audience, capabilities and expected outcome.
`model.path`	`string`	Required / no default	Required local model directory within the project root, or a repository identifier paired with an immutable revision. Never a teacher inference endpoint.
`model.adapter`	`string`	Required / no default	Required registered adapter ID. transformers-causal-lm selects the Transformers causal-language-model adapter.
`model.revision`	`string \| null`	`null`	Local models are fingerprinted. Repository identifiers require an immutable 40- or 64-character revision.
`teacher.provider`	`string`	Required / no default	Required provider identifier from your active paid plan. It does not transfer model ownership.
`teacher.reference_model_id`	`integer`	Required / no default	Required positive integer from the models included in that provider plan; placeholders must be replaced.

Data and privacy
Field or interface	Type or result	Default or exit code	Behavior and validation
`data.sources`	`string[]`	`[]`	Paths to local JSONL training sources containing a text field. Teacher-generated lessons may supplement these under approved_only sharing.
`data.teacher_sharing`	`enum`	`"approved_only"`	approved_only permits reviewed training content; none forbids sending customer content to the teacher. Hidden evaluation data is always excluded.
`data.validation_path`	`string \| null`	`null`	Optional independent validation JSONL. If absent, the reviewed plan defines a deterministic split before training.
`data.test_path`	`string`	Required / no default	Required independent final test file, never consumed by teacher preparation or optimization.
`data.deduplicate`	`boolean`	`true`	Remove duplicate and overlapping examples across splits; report exclusions without exposing private text.
`data.seed`	`integer`	`42`	Nonnegative integer for deterministic splitting and reproducible initialization where the backend supports it.

{
  "schema_version": "1.0",
  "mode": "automatic",
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "data": {
    "sources": ["./data/train.jsonl"], "teacher_sharing": "none",
    "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl",
    "deduplicate": true, "seed": 42
  },
  "runtime": {"target": "customer_datacenter", "devices": "auto"},
  "training": {"method": "auto"},
  "curriculum": {"topics": ["intent", "ambiguous_requests", "class_balance"], "max_improvement_cycles": 3, "stop_on_regression": true},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "checkpoints": {"keep_last": 3},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-001", "format": "safetensors"}
}

Choose Automatic or Advanced training

Automatic mode resolves compatible settings and records them in the plan. Advanced mode accepts explicit training settings and only compatible architecture, method, precision and hardware combinations. Defaults are not universal memory or performance guarantees. An unsupported combination fails compatibility checks before weight updates.

Training methods are SFT, LoRA and QLoRA; Automatic mode can also resolve the method value auto.
For distributed DDP, the approved launcher supplies node ranks and rendezvous settings; multi-node execution requires an explicit trusted torchrun environment.
Model architecture, tokenizer and context limits remain binding. The adapter does not support every model family.

Runtime and distribution
Field or interface	Type or result	Default or exit code	Behavior and validation
`runtime.target`	`enum`	Required / no default	Required: fusionpointai_hosting, customer_datacenter or colab. Selects an existing runtime; does not purchase hardware.
`runtime.devices`	`"auto" \| integer[]`	`"auto"`	auto selects compatible approved devices; an explicit list contains unique nonnegative visible GPU indices.
`runtime.distributed.backend`	`enum`	`"none"`	none for one process, or ddp with a supported adapter and approved multi-worker launcher.
`runtime.distributed.nodes`	`integer`	`1`	Positive integer. More than one requires DDP, agreed node access, ranks and secure rendezvous; no capacity is provisioned by this value.

Training settings
Field or interface	Type or result	Default or exit code	Behavior and validation
`training.method`	`enum`	`"auto"`	One of auto, SFT, LoRA or QLoRA. Automatic mode resolves auto; Advanced mode uses an explicit supported method.
`training.epochs`	`number \| "auto"`	`"auto"`	Positive finite number or Automatic-only auto; the effective step count is also bounded by approved time and resources.
`training.learning_rate`	`number \| "auto"`	`"auto"`	Positive finite number less than 1 or Automatic-only auto. Adapter and commercial policies may impose narrower limits.
`training.batch_size`	`integer \| "auto"`	`"auto"`	Positive per-device integer or Automatic-only auto; memory suitability is checked before execution.
`training.gradient_accumulation_steps`	`integer \| "auto"`	`"auto"`	Positive integer or Automatic-only auto. Effective batch size includes worker count and accumulation.
`training.max_sequence_length`	`integer \| "auto"`	`"auto"`	Positive integer within tokenizer and model limits, or Automatic-only auto; never silently extend model context.
`training.precision`	`enum`	`"auto"`	auto, fp32, fp16 or bf16 as supported by the hardware and backend; explicit in Advanced mode.
`training.lora.rank`	`integer`	`16`	Positive adapter rank. Used only for LoRA/QLoRA with eligible target modules.
`training.lora.alpha`	`number`	`32`	Positive finite adapter scaling value. Used only for LoRA/QLoRA.
`training.lora.dropout`	`number`	`0.05`	Finite value from 0 inclusive to 1 exclusive. Used only for LoRA/QLoRA.
`training.lora.target_modules`	`"auto" \| string[]`	`"auto"`	auto resolves supported module names into the plan, or supply a nonempty list of eligible names.

Curriculum controls
Field or interface	Type or result	Default or exit code	Behavior and validation
`curriculum.topics`	`string[]`	`[]`	Ordered topic names. Empty lets Automatic propose prerequisites; Advanced requires an explicit reviewed sequence.
`curriculum.max_improvement_cycles`	`integer`	`3`	Positive integer, maximum 10. Stop earlier when budgets, no-progress or regression conditions apply.
`curriculum.stop_on_regression`	`boolean`	`true`	When true, halt improvement at a rubric-defined regression. When false, a regression still fails final acceptance.

{
  "schema_version": "1.0",
  "mode": "advanced",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "data": {"sources": ["./data/train.jsonl"], "teacher_sharing": "none", "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl"},
  "runtime": {"target": "customer_datacenter", "devices": [0, 1], "distributed": {"backend": "ddp", "nodes": 1}},
  "training": {
    "method": "LoRA",
    "epochs": 3,
    "learning_rate": 0.0002,
    "batch_size": 1,
    "gradient_accumulation_steps": 16,
    "max_sequence_length": 2048,
    "precision": "bf16",
    "lora": {"rank": 16, "alpha": 32, "dropout": 0.05}
  },
  "curriculum": {
    "topics": ["intent", "ambiguous_requests", "class_balance"],
    "max_improvement_cycles": 3,
    "stop_on_regression": true
  },
  "checkpoints": {"every_steps": 100, "keep_last": 3, "resume_validation": "strict"},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-advanced-001", "format": "safetensors"}
}

Set finite budgets and measurable acceptance

Every project has explicit time, teacher-request and storage budgets. Stop at the first exhausted budget, failed integrity check, regression or no-progress condition. Save valid recovery state and explain unmet criteria. A rubric defines independent acceptance tasks; it does not turn an example score into an achieved result.

The example rubric uses a normalized 0–1 scale and separate required criteria. All required criteria must pass.
Changing data, model, evaluation, topology or budgets requires a new reviewed plan rather than forcing a mismatched resume.
Exports contain validated model or adapter files, the tokenizer and manifests, not credentials, unrelated cache data or unreviewed model code.

Budgets, recovery and output
Field or interface	Type or result	Default or exit code	Behavior and validation
`budgets.max_training_minutes`	`number`	Required / no default	Required positive finite execution budget in minutes, including preparation and evaluation wall time after run begins.
`budgets.max_teacher_requests`	`integer`	Required / no default	Required positive integer; count preparation, review and retry attempts. Fail closed before exceeding it.
`budgets.max_storage_gib`	`number`	Required / no default	Required positive finite owned-storage budget in GiB, covering data, checkpoints and artifacts; never delete unrelated files.
`checkpoints.every_steps`	`integer`	`100`	Positive integer checkpoint interval. Also save a valid atomic checkpoint on a successful pause.
`checkpoints.keep_last`	`integer`	`3`	Integer from 1 to 5. Remove only obsolete owned checkpoints after a newer one is validated.
`checkpoints.resume_validation`	`enum`	`"strict"`	strict only. Reject changed model, data, configuration, evaluator or distributed-topology fingerprints.
`evaluation.rubric`	`string`	Required / no default	Required path to a valid rubric with pinned evaluators and measurable required criteria.
`evaluation.baseline_required`	`boolean`	`true`	true only for this contract. Evaluate the untouched baseline before weight updates.
`output.directory`	`string`	Required / no default	Required new owned run directory. Existing runs may be inspected or resumed but never overwritten by run.
`output.format`	`enum`	`"safetensors"`	safetensors or adapters, only when supported. Adapter exports require the pinned base model and tokenizer.

Evaluation rubric fields
Field or interface	Type or result	Default or exit code	Behavior and validation
`schema_version`	`string`	`"1.0"`	Rubric schema 1.0; distinct from the package release version.
`name`	`string`	Required / no default	Required nonempty rubric name used in reports.
`scale.minimum`	`number`	`0`	Lower normalized score bound: 0 for this schema.
`scale.maximum`	`number`	`1`	Upper normalized score bound: 1 for this schema.
`criteria`	`object[]`	Required / no default	Nonempty list. Every required criterion must pass; IDs must be unique.
`criteria[].id`	`string`	Required / no default	Required stable criterion identifier, preserved in reports.
`criteria[].description`	`string \| null`	`null`	Optional explanatory text. A description is not a semantic grader.
`criteria[].metric`	`string`	Required / no default	Required registered metric: exact_match, macro_f1, text_similarity, chrf or a custom registered scorer.
`criteria[].minimum_score`	`number`	Required / no default	Required finite threshold between 0 and 1. An example threshold is not a promised result.
`regression.maximum_score_drop`	`number`	`0.02`	Allowed absolute normalized drop from the untouched baseline, from 0 to 1; assessed per retained criterion.
`final_test.path`	`string`	Required / no default	Required; must identify the same independent file as data.test_path.
`final_test.allow_training_use`	`boolean`	`false`	false only. Reject configurations that permit held-out test answers to enter training or teacher input.

SDK 0.2.0 CONFIGURATION RULES
Unknown fields, duplicate IDs, nonfinite numbers and unsafe paths are rejected.
All model, data, rubric and output paths must resolve inside the project root.
Automatic mode resolves "auto" once; save all resolved values in the plan manifest.
Advanced mode requires explicit method, epochs, learning_rate, batch_size,
gradient_accumulation_steps, max_sequence_length and precision.
SFT does not consume LoRA options. LoRA/QLoRA require a compatible adapter.
Model files and pinned revisions are verified within the project root.
Use the CLI for explicit GPU indexes; Python callers can set CUDA_VISIBLE_DEVICES
before starting Python and keep runtime.devices set to auto.
No automatic execution of untrusted model code, shell commands or plugins.
All three budgets must be finite, positive and explicitly supplied.
Storage includes owned checkpoints, datasets and artifacts, not unrelated files.
Held-out test data must not be sent to the teacher or used for weight updates.
CLI overrides are limited to the documented flags; never silently override a plan.
RUBRIC RULES
Every criterion requires a registered metric and minimum_score; descriptions are not semantic evaluators.
Built-in metrics: exact_match, macro_f1, text_similarity and chrf.
Custom deterministic scorers use register_evaluator(name, scorer, version="...").
Evaluator versions and scoring configuration are pinned in the plan.
0 <= minimum_score <= 1 for the example's normalized scale.
All required criteria must pass; do not average away a failed criterion.
The final_test.path must match data.test_path; allow_training_use must be false.
Scores and budgets in examples are requested settings, not measured results.

From configuration to a reproducible run

Define a project and protect its data

Choose Automatic or Advanced training

Set finite budgets and measurable acceptance

Continue your workflow