Python SDK: methods, results and errors

Commands and code stay in English in every language. Replace uppercase placeholders with values from your own account and paid job; do not paste real keys into shared notebooks or logs.

One project API, one underlying engine

CLI and Python must agree on configuration, state and deliverables.

from_file Load without weight changes
plan Inspect resolved inputs
run / controls Own workers and recovery
evaluate / export Inspect accepted local outputs

Use the same engine from Python

TrainingProject complements rather than replaces TrainingClient. Load a configuration and scoped API key, inspect the plan, and then start the run. The project object exposes its owned run for inspection and controls; run refuses to overwrite an existing run, while resume requires valid recovery state.

Paths accept strings or os.PathLike objects. Method options are keyword-only.
Calling from_file validates local configuration; it does not update weights or make teacher requests.
Python and CLI workflows use the same settings, fingerprints, budgets and outputs.

Complete Python project reference
Field or interface	Type or result	Default or exit code	Behavior and validation
`TrainingProject.from_file(path, *, api_key)`	`TrainingProject`	Required / no default	Load and validate a configuration path and nonempty secret string. Returns a project object; no weight updates or teacher calls.
`plan(*, dry_run=True)`	`dict`	`true`	True only. Returns resolved_configuration, compatibility, data_sharing, budgets, topics, artifacts and fingerprints.
`run()`	`dict`	Required / no default	Block until terminal or paused state; return the common run result only for a successful operation, otherwise raise the matching error.
`status()`	`dict`	Required / no default	Read run_id, status, stop_reason, report_path and unmet_criteria without starting a worker.
`pause()`	`dict`	Required / no default	Wait for worker acknowledgement and valid checkpoint; return the common run result. Invalid state is a configuration error.
`resume()`	`dict`	Required / no default	Validate all fingerprints and resume owned workers; return the common run result when the operation succeeds.
`cancel()`	`dict`	Required / no default	Wait for owned workers to stop and return cancelled state; raise CancellationError if safe termination cannot be confirmed.
`evaluate(*, split="test")`	`dict`	`"test"`	Accept validation or test. Return run_id, split, accepted, criteria, regressions and report_path; failed acceptance raises EvaluationFailedError after saving the report.
`export(*, format="safetensors")`	`dict`	`"safetensors"`	Return run_id, format, artifact_path, manifest_path and sha256 for an accepted compatible artifact.
`register_evaluator(name, scorer, *, version)`	`None`	Required / no default	Register a trusted scoring function before planning or evaluation. Supply a stable name and explicit version; the function receives prediction, target and row and must return a finite score from 0 to 1. Built-in metrics cannot be replaced.

import os
from fusionpointai_training import TrainingProject

project = TrainingProject.from_file(
    "./german-project/training.json",
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
)
plan = project.plan(dry_run=True)
print(plan["resolved_configuration"], plan["data_sharing"], plan["budgets"])
# Confirm the reviewed plan before starting real work.
result = project.run()
if result["status"] != "completed" or result["stop_reason"] != "accepted":
    raise RuntimeError("Training was not accepted; inspect the retained report.")
evaluation = project.evaluate(split="test")
# A failed required criterion raises EvaluationFailedError after saving its report.
artifact = project.export(format="safetensors")
print(artifact["manifest_path"])

Inspect structured results

The return contract below describes shapes, not sample measurements. Inspect status, stop_reason and unmet_criteria before deployment. Evaluation results identify each criterion and regression. Export returns local paths and integrity metadata; it does not automatically upload the model or replace production inference.

Status and manifest data must be readable without generating a new teacher request.
Evaluation on the final test set is separate from validation used during improvement.
An artifact manifest must match real files, safe relative paths, byte sizes and SHA-256 values.

TrainingProject return contract (dictionary shapes)
from_file: validates configuration, attaches its owned run; no weight updates.
plan: {schema_version, resolved_configuration, compatibility, data_sharing,
       budgets, topics, artifacts, fingerprints}; dry_run must be true.
run/resume: {run_id, status, stop_reason, report_path, unmet_criteria}.
status/pause/cancel: {run_id, status, stop_reason, report_path, unmet_criteria}.
stop_reason is null until terminal; run/resume block until terminal or paused.
pause blocks until owned workers acknowledge an atomic checkpoint.
cancel blocks until owned workers stop; a failed stop raises CancellationError.
evaluate: {run_id, split, accepted, criteria, regressions, report_path}.
export: {run_id, format, artifact_path, manifest_path, sha256}.
Returned paths are local, resolved paths; no model upload is implied.
Status output is redacted and may be read without opening an API connection.
from_file requires path: str | os.PathLike and a nonempty api_key: str.
plan accepts dry_run=True only; False is ConfigurationError, not execution.
evaluate accepts split="validation" or "test"; defaults to test.
export accepts safetensors or adapters when supported by the selected adapter.
All method keyword options are keyword-only. Unlisted arguments are rejected.

Handle failures without hiding them

The project error classes inherit TrainingError and map to CLI exit codes. Configuration and compatibility failures occur before training. Budget and evaluation failures retain reports and unmet criteria. A worker-stop or checkpoint error remains a failure until safe cleanup is confirmed.

Successful methods return documented dictionaries. Failed criteria raise EvaluationFailedError after saving the evaluation report.
Never log API keys, authorization headers, the full environment or private training examples.
Do not wrap exceptions in automatic retries. Read run and service state first.

Python errors and CLI exit mapping
Field or interface	Type or result	Default or exit code	Behavior and validation
`ConfigurationError`	`TrainingError`	`2`	Invalid schema, argument, path, state or unsupported override. Correct inputs before retrying.
`CompatibilityError`	`TrainingError`	`3`	Unsupported adapter, model, hardware, precision, distribution or format.
`AuthenticationError`	`TrainingError`	`4`	Missing/expired key, denied entitlement or prohibited teacher sharing; never include secrets in the message.
`BudgetExceededError`	`TrainingError`	`5`	A finite budget ended before acceptance. Retain a valid checkpoint and unmet criteria.
`EvaluationFailedError`	`TrainingError`	`6`	Required criteria failed, improvement stalled or regression persisted. Retain the evaluation report.
`CheckpointError`	`TrainingError`	`7`	Invalid, incomplete or mismatched recovery state. Never force resume.
`CancellationError`	`TrainingError`	`7`	Safe termination of owned workers could not be confirmed; keep cleanup open.
`ExportError`	`TrainingError`	`7`	Unsupported or invalid artifact, unsafe path or checksum failure; do not deliver it.
`TrainingError`	`Exception`	`7`	Base training failure. All listed target errors inherit it; preserve redacted diagnostics.

import os
from fusionpointai_training import TrainingProject
from fusionpointai_training.errors import (
    AuthenticationError, BudgetExceededError, CompatibilityError,
    ConfigurationError, EvaluationFailedError, TrainingError,
)

try:
    project = TrainingProject.from_file(
        "./german-project/training.json",
        api_key=os.environ.get("FUSIONPOINTAI_API_KEY", ""),
    )
    project.plan(dry_run=True)
    project.run()
    result = project.evaluate(split="test")
except (ConfigurationError, CompatibilityError):
    print("Correct the configuration before starting a new run.")
except AuthenticationError:
    print("Check access without logging the key.")
except BudgetExceededError:
    print("Preserve the checkpoint. A larger approved budget requires a new plan.")
except EvaluationFailedError:
    print("Preserve failed criteria; do not publish this model as accepted.")
except TrainingError:
    print("Inspect redacted diagnostics; do not blindly repeat a write.")
# CancellationError, CheckpointError and ExportError also inherit TrainingError.

from fusionpointai_training import register_evaluator

def category_match(prediction, target, row):
    return float(prediction.strip().casefold() == target.strip().casefold())

register_evaluator("category_match", category_match, version="1")
# Register before project.plan() in the same Python process.
# In rubric.json: "metric": "category_match", "minimum_score": 0.85
# This scorer measures category equality, not open-ended semantic correctness.

One project API, one underlying engine

Use the same engine from Python

Inspect structured results

Handle failures without hiding them

Continue your workflow