train-and-publish-models

Training and publishing models

The command

fastworkflow train <workflow_folderpath> [env_file_path] [passwords_file_path] [--regenerate-utterances]

The two env-file arguments are positional and optional; they default to files in the current directory, or to the bundled ones for a packaged example. --regenerate-utterances is the only training-policy override, and it is expensive — see Rule 2.

Training recurses into <workflow>/_workflows/* first, so a child workflow is trained before its parent, each with its own persona source and caches.

What one run does, in order

Knowing the order is what lets you read a failure: everything before the first paid call is a gate, and everything after publication is cleanup.

1. Build routing artifacts        command_directory.json, routing_definition.json
2. Duplicate-capability scan      lexical, seeds only          <- free, reports
3. Benchmark preflight            leak + defect checks         <- free, CAN FAIL THE RUN
4. Migrate legacy artifacts       into versions/ if unversioned
5. DSPy parameter examples        param_example_cache          <- costs money on a miss
6. Compute the training plan      selective or full
   -> if the plan is empty: republish, apply retention, stop ("already up to date")
7. Generate utterances + train    utterance_cache              <- costs money on a miss
8. Carry forward untrained contexts from the previous version
9. Router-confusion scan          needs every context present
10. Write signature + manifest
11. Safety gate on training data  CAN REFUSE TO PUBLISH
12. Publish + retain current and previous   <- the commit point
13. Prune orphaned artifacts

Steps 2 and 3 sit before every paid call deliberately: a leaked benchmark used to abort a run that had already spent money on every command with parameters.

Rule 1 — the seed is fixed, so a cache miss is the only source of drift

get_training_seed() returns 42, always. It is not configurable, and a TRAINING_SEED environment variable is not read — seed selection is part of the trainer, not workflow configuration.