SDK Python: métodos, resultados y errores

Los comandos y el código se mantienen en inglés en todos los idiomas. Sustituye los marcadores en mayúsculas por valores de tu cuenta y de tu tarea de pago; no pegues claves reales en cuadernos ni registros compartidos.

Una API de proyecto, un único motor subyacente

La CLI y Python deben coincidir en la configuración, el estado y los entregables.

from_file Cargar sin cambiar los pesos
plan Inspeccionar entradas resueltas
run / controls Gestionar procesos y recuperación
evaluate / export Inspeccionar resultados locales aceptados

Usar el mismo motor desde Python

TrainingProject complementa TrainingClient, no lo sustituye. Carga la configuración y una clave de API con el alcance adecuado, revisa el plan e inicia la ejecución. El objeto del proyecto permite consultar y controlar su ejecución; run no sobrescribe una ejecución existente y resume requiere un estado recuperable válido.

Las rutas aceptan cadenas u objetos os.PathLike. Las opciones de los métodos son solo por palabra clave y se rechazan argumentos desconocidos.
from_file valida la configuración local; no actualiza los pesos ni solicita contenido al modelo de referencia.
Python y la CLI resuelven los mismos ajustes, huellas, presupuestos y resultados.

Referencia completa del proyecto Python
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`TrainingProject.from_file(path, *, api_key)`	`TrainingProject`	Obligatorio / sin valor predeterminado	Carga y valida la ruta de configuración y una cadena secreta no vacía. Devuelve un objeto de proyecto; no actualiza los pesos ni solicita contenido al modelo de referencia.
`plan(*, dry_run=True)`	`dict`	`true`	Solo True. Devuelve resolved_configuration, compatibility, data_sharing, budgets, topics, artifacts y fingerprints.
`run()`	`dict`	Obligatorio / sin valor predeterminado	Bloquea hasta llegar a un estado final o pausado; solo devuelve el resultado común de la ejecución si tiene éxito; de lo contrario genera el error correspondiente.
`status()`	`dict`	Obligatorio / sin valor predeterminado	Lee run_id, status, stop_reason, report_path y unmet_criteria sin iniciar un proceso.
`pause()`	`dict`	Obligatorio / sin valor predeterminado	Espera la confirmación del proceso y un punto de control válido; devuelve el resultado común de la ejecución. Un estado no válido genera un error de configuración.
`resume()`	`dict`	Obligatorio / sin valor predeterminado	Valida todas las huellas y reanuda los procesos propios; devuelve el resultado común cuando la operación se completa correctamente.
`cancel()`	`dict`	Obligatorio / sin valor predeterminado	Espera a que se detengan los procesos propios y devuelve el estado cancelled; genera CancellationError si no se puede confirmar una parada segura.
`evaluate(*, split="test")`	`dict`	`"test"`	Acepta validation o test. Devuelve run_id, split, accepted, criteria, regressions y report_path; si falla la aceptación, genera EvaluationFailedError después de guardar el informe.
`export(*, format="safetensors")`	`dict`	`"safetensors"`	Devuelve run_id, format, artifact_path, manifest_path y sha256 para un artefacto compatible aceptado.
`register_evaluator(name, scorer, *, version)`	`None`	Obligatorio / sin valor predeterminado	Registra una función de puntuación de confianza antes de planificar o evaluar. Indica un nombre estable y una versión explícita. La función recibe prediction, target y row y debe devolver una puntuación finita entre 0 y 1. No se pueden sustituir las métricas integradas.

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"])

Inspeccionar resultados estructurados

El contrato de retorno siguiente describe la estructura, no mediciones de ejemplo. Revisa status, stop_reason y unmet_criteria antes del despliegue. Los resultados de evaluación identifican cada criterio y regresión. La exportación devuelve rutas locales y metadatos de integridad; no carga el modelo automáticamente ni sustituye la inferencia en producción.

Los datos de estado y del manifiesto deben poder consultarse sin generar otra solicitud al docente.
La evaluación con el conjunto de prueba final es independiente de la validación usada durante las mejoras.
El manifiesto de artefactos debe coincidir con los archivos reales, las rutas relativas seguras, los tamaños en bytes y los valores SHA-256.

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.

Gestionar los errores sin ocultarlos

Los errores de proyecto heredan de TrainingError y se corresponden con los códigos CLI documentados. Los errores de configuración y compatibilidad se producen antes del entrenamiento. Los errores de presupuesto o aceptación conservan sus informes y criterios incumplidos. Un error al detener procesos o guardar un punto de control sigue siendo un fallo hasta que se confirme una limpieza segura.

Un método que termina con éxito devuelve el diccionario documentado. Si no se alcanza el objetivo, se genera el error correspondiente después de guardar el informe.
No registres la clave API, las cabeceras de autorización, todo el entorno ni ejemplos privados de entrenamiento.
No conviertas todas las excepciones en reintentos automáticos. Comprueba primero el estado de la ejecución y del servicio.

Errores Python y correspondencia de códigos de salida CLI
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`ConfigurationError`	`TrainingError`	`2`	Esquema, argumento, ruta o estado no válido, o anulación no compatible. Corrige las entradas antes de volver a intentarlo.
`CompatibilityError`	`TrainingError`	`3`	Adaptador, modelo, hardware, precisión, distribución o formato no compatible.
`AuthenticationError`	`TrainingError`	`4`	Clave ausente o caducada, permisos denegados o uso compartido prohibido con el docente; nunca incluyas secretos en el mensaje.
`BudgetExceededError`	`TrainingError`	`5`	Se agotó un presupuesto finito antes de la aceptación. Conserva un punto de control válido y los criterios incumplidos.
`EvaluationFailedError`	`TrainingError`	`6`	Fallaron criterios obligatorios, se estancó la mejora o persistió una regresión. Conserva el informe de evaluación.
`CheckpointError`	`TrainingError`	`7`	Estado de recuperación no válido, incompleto o incompatible. Nunca fuerces la reanudación.
`CancellationError`	`TrainingError`	`7`	No se pudo confirmar la parada segura de los procesos propios; mantén abierta la limpieza.
`ExportError`	`TrainingError`	`7`	Artefacto no compatible o no válido, ruta insegura o error de suma de comprobación; no lo entregues.
`TrainingError`	`Exception`	`7`	Fallo general de entrenamiento. Los errores documentados del proyecto heredan de esta clase; conserva los diagnósticos depurados.

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.

Una API de proyecto, un único motor subyacente

Usar el mismo motor desde Python

Inspeccionar resultados estructurados

Gestionar los errores sin ocultarlos

Continuar el flujo de trabajo