docs: fix training-job metrics shape across fine-tuning guides

[kfastino]

Summary

End-to-end live testing against api.pioneer.ai (synthetic dataset gen → 32-second LoRA training run on fastino/gliner2-base-v1 → inference + evaluation) uncovered that the metrics shape documented across the fine-tuning guides doesn't match what the API actually returns.

The guides all claimed metrics: {f1, precision, recall} on the training-job response. The real contract (per brain/services/training/metrics.py):

Field	Where it lives	When it's populated
final_training_loss, final_validation_loss, best_validation_loss	GET /felix/training-jobs/{id} → metrics	As soon as training completes
f1_score, precision_score, recall_score, accuracy	GET /felix/evaluations/{id}	After an evaluation runs
eval_f1_score, eval_precision, eval_recall, eval_accuracy	GET /felix/training-jobs/{id} → metrics (merged in)	After an evaluation runs against the model

Files updated

• guides/fine-tune-ner.mdx
• guides/fine-tune-classification.mdx
• guides/fine-tune-extraction.mdx
• guides/agent-skills.mdx

Verification

Verified live against api.pioneer.ai:

curl -X POST https://api.pioneer.ai/felix/training-jobs ...
# 200, status: "requested" → "running" → "complete" in ~32s

curl https://api.pioneer.ai/felix/training-jobs/$JOB_ID
# metrics: { "final_training_loss": 1.4, "final_validation_loss": 0.00002, "best_validation_loss": 0.00002 }

curl -X POST https://api.pioneer.ai/felix/evaluations ...
# 200, evaluations[0].f1_score / precision_score / recall_score (snake_case + _score suffix)

Test plan

• Verified by training a real classification LoRA model end-to-end on api.pioneer.ai
• Confirmed metrics field names against brain/services/training/metrics.py
• No other API claims in the guides drift from the live OpenAPI spec

Made with Cursor