ai-exchange/docs/training_console_public_surface_v1.md

Training Console Public Surface v1

This document defines the current public-facing Training module surface for ai-ict.

Product Position

• Training is a separate public module from the trading workbench.
• The public browser entry is /training.
• The trading workbench stays at /.
• Training assets live in src/web/training.html and src/web/training.js.

Dashboard Entry

• available cases
• user progress
• attempt start
• annotation note save
• attempt submit
• public case fields only

API Surface

Method	Path	Capability
GET	/training/cases	list cases with status, skill tag, instrument, and limit filters
GET	/training/cases/{case_id}	read one public case
GET	/training/cases/export	export a public package with the same case filters
POST	/training/cases/import	import a versioned public package with cases plus tasks
POST	/training/attempts	start an attempt for one case
POST	/training/attempts/{attempt_id}/annotations	save an annotation payload for one attempt
POST	/training/attempts/{attempt_id}/submit	submit an attempt with optional score data
GET	/training/progress	list progress with user, skill tag, and limit filters

Validation And Errors

Training public error catalog:

• deterministic public validation errors
• 400 with invalid_json_body
• 400 with missing_required_json_field:<field>
• 400 with invalid_json_field:<field>
• 400 with invalid_path_param:<field>
• 400 with invalid_limit_query_param:limit
• 404 with not_found
• 500 with internal_server_error
• masks raw internals

Package CLI public errors:

• one-line JSON
• input_file_not_found
• input_path_is_directory
• output_path_is_directory
• output_path_unwritable

Package Smoke

• public package
• public export
• public output
• internal solution details are excluded from exported public JSON
• fixture path: tests/fixtures/training_case_package_m6.json
• example command: .venv/bin/python scripts/run_training_case_package.py --input tests/fixtures/training_case_package_m6.json --output /tmp/training_case_public_export.json