CLI API¶

Run the complete data generation pipeline.

Executes both data preparation stages in order: preprocess, then one complete supervision bundle build. This is the recommended way to prepare data for training from scratch.

$ uv run naics-embedder data all

Deprecated: builds nothing; data supervision builds the complete bundle.

Download and preprocess all raw NAICS data files.

Downloads the official 2022 NAICS taxonomy files from the U.S. Census Bureau and processes them into a unified descriptions parquet file.

The output file contains columns for code, title, description, examples, and exclusions for each NAICS code at all hierarchy levels (2-6 digit). Each code's examples channel holds its examples-role index entries only, per the committed role table (data roles).

$ uv run naics-embedder data preprocess

Draw the regressor panel's held-out four-digit groups, once.

Holds out a fifth of each sector's four-digit groups (largest remainder, seeded) from the six-digit population Stage 1's finding names. The table is committed, and the regressor panel reads it from then on (roadmap Stage 3).

$ uv run naics-embedder data regressor-groups --codebook PATH/naics_codebook.parquet

Deprecated: builds nothing; data supervision builds the complete bundle.

Draw the frozen index-entry role table, once.

Gives every Census index entry exactly one role, per code and stratified: examples-channel text, or a training, validation or test query for the outcome panel (roadmap D4). No validation or test query matches any training text. The table is committed, and preprocess applies it from then on.

$ uv run naics-embedder data roles --source-dir ~/Downloads/Data

Build the window-fitting summaries of over-long channel texts, once per backbone.

Every channel text whose marked form is over the backbone's trained window is summarized by the whole units (sentences, clauses or examples entries) whose pooled vectors best approximate the text's (roadmap Stage 6b). The backbone is read from the local Hugging Face cache. The artifact is checked as every reader checks it before it is moved into place; commit it with the pin this prints, in WINDOW_SUMMARIES (panels/window_summaries.py).

$ HF_HUB_OFFLINE=1 uv run naics-embedder data summaries

Build one immutable, validated Stage-3 supervision bundle.

Computes structural distances (D*) and relations in canonical pair orientation, attaches both directional exclusion flags, and derives the codebook, pair facts, compatibility distance/relation artifacts and matrices, training pairs, and curriculum difficulty thresholds from those facts. The index roles and the redirection table become members, and the manifest records the backbone's input window. Every artifact carries the bundle ID and schema version; the manifest is written only after all artifacts validate, and an existing bundle is never overwritten.

$ uv run naics-embedder data supervision

Deprecated: builds nothing; data supervision builds the complete bundle.

Construct the two-stream datamodule of the validated bundle (spec 4.3).

It reads the token cache the export and the reads load (code_token_config), so an arm is exported from the token rows it trained on, and it draws each epoch's permutations from the run's seed, data_loader.queries_per_step queries a step.

Construct a fresh model under the validated bundle (P15).

The model takes supervision only from the bundle, and every setting from the config: Req 11's three terms and their two logit scales, the radius bound, and the optimizer's AdamW, warmup and plateau (spec 4.5). run_settings (utils/training.run_settings) is saved in its hyperparameters, which the exact-resume guard compares (P19); the monitor reads each epoch and is not saved.

The run's D6 monitor (spec 4.4): the bundle's outcome panel, its reads logged to selection_log and kept in monitor_reads.jsonl in the run's checkpoint directory.

It tokenizes queries with the token cache's tokenizer and window (code_token_config), as an arm's reads do. Building it writes nothing: the first read writes the log, and the first epoch's end the records file.

Parameters:

The configured run's encoder record.

It comes from the same helper the model builds its own record with, so the two cannot drift (spec 4.4).

Generate hyperbolic embeddings parquet file from a trained checkpoint.

Loads a trained model checkpoint, runs inference on all NAICS codes, and writes the resulting embeddings to a parquet file compatible with HGCN training. HGCN refines Lorentz points, which only the hyperbolic arm has, so a configured flat arm is refused before anything is read (Req 12). The checkpoint must carry the supervision contract of the configured run, the contract of its validated bundle, its geometry included; a checkpoint without one, or with another, is refused before its model loads. One trained under another objective, as every checkpoint saved before Stage 7 was, is refused first, and nothing migrates it (spec 4.5, D2).

Parameters:

Returns:

Raises:

The checkpoint contract of the configured run, its encoder record and summaries included.

Training's exact resume and the HGCN feeder compare this whole contract with a checkpoint's; export and reads take the encoder record from the checkpoint instead (spec 4.4).

Train the NAICS text encoder: Req 11's three terms, selected on the validation MRR (D6).

Loads the configuration, gates the supervision bundle, and builds the two-stream datamodule, the outcome monitor (the bundle's panel, logging to conf/data/outcome_panel.yaml's selection_log, its records in the checkpoint directory) and the model, which records the run's settings. create_trainer's trainer keeps the earliest epoch with the highest val/outcome_mrr and last.ckpt, and stops early on the same MRR.

Before anything is built, P19's guards refuse a fresh start into a checkpoint directory that is not empty, and an exact resume from a checkpoint saved in another directory, under other run settings or another seed, or of a run that early stopping ended. Each refusal exits 1. A run that spent its epoch budget without an early stop is not refused: its resume trains nothing.

Parameters:

$ uv run naics-embedder train

$ uv run naics-embedder train --ckpt-path last

$ uv run naics-embedder train experiment_name=lr-1e-5 training.learning_rate=1e-5

Display the training configuration a run would use.

Validates the configuration file over the defaults and displays the run's name, seed and inputs, then the settings every run records. A file that sets a key the configuration no longer has is refused (spec 4.5). A missing file, or one the configuration refuses, prints the error and exits 1.

Parameters:

$ uv run naics-embedder tools config

$ uv run naics-embedder tools config --config conf/custom.yaml

Decide among arms under Req 5's rule: over D8's three panels with margins from tools margins, or over the two growth panels (Req 24) with margins from tools growth-margins.

Each A-against-B comparison reads Δ on paired resamples of each panel's units, seeds nested. A is adopted over B when it is non-inferior on every panel (the 95 % interval's lower bound above −δ) and superior on at least one (the 1 − 0.05/n interval above zero: 98⅓ % over three panels, 97.5 % over two). The survivors are the arms no other arm is adopted over, and the tie order picks among them. The record carries the arms with their selection-log records and artifact references, the margins, every comparison, the non-dominated set, the tie order and the chosen arm.

The economic decision reads economic arm records, one or more, and compares each candidate with the reference covariates+ancestors. Only a candidate adopted over the reference is eligible for the rule among candidates; with none, the reference stands.

$ uv run naics-embedder tools decide --arm candidate.json --arm reference.json \
    --margins margins.json --name dimension-8 --question "Is dimension 8 enough?" \
    --store ~/naics-artifacts --output decision.json

Report Req 6's structural diagnostics over every codebook code.

Sector separation (an AUC), within-sector rank correlation (over queries and over sectors), MAP over ancestors, NDCG@5/10/20 with integer lowest-common-ancestor grades, the Pearson correlation of distance with D*, and parent retrieval@1/5 without the 522 unary pairs. The report describes an arm: nothing selects on it, and no statistic in it has a threshold.

--geometry must be the table's own arm: a table whose export provenance names another geometry is refused, and so is one whose provenance file exists but cannot be read as JSON. A table with no provenance file, or whose provenance names no geometry, is read as given.

$ uv run naics-embedder tools diagnostics --table arm.parquet --geometry hyperbolic \
    --codebook PATH/naics_codebook.parquet

Export an arm's code table in Req 2's form, with its provenance (roadmap Stage 6).

Every code goes through the checkpoint's model in eval mode. The table holds code, index, level and e0 … e{d-1}: each code's tangent vector at the origin, in the bundle's codebook order. The checkpoint's supervision contract must match the configured bundle. Its encoder record is its own, so a d = 8 checkpoint exports under a d = 16 config.

$ uv run naics-embedder tools export-table \
    --checkpoint checkpoints/reference/epoch=001.ckpt \
    --output data/reference/arm_table.parquet supervision.manifest_path=PATH

Read the reference alone on both growth panels and fix each one's margin δ (Req 24).

The read scores, on each growth regime's level-6 validation split, only the comparators that read no candidate: the covariates, one-hot (seen regime only) and ancestor indicators, each alone and with the covariates. δ is the decision config's relative_margin r (0.05, U13) times the MSE of the reference covariates+ancestors there. The panel reads growth whatever the regressor config's outcome says; it stays level for tools regressor-panel and tools sweep.

Fix the margins once, before any candidate is read on growth: a decision refuses a candidate read before its margins were fixed. The record names the platform, Python and uv.lock the read ran under, and every candidate read must run there too, since a decision pairs only bit-identical reference predictions.

$ uv run naics-embedder tools growth-margins --codebook PATH/naics_codebook.parquet \
    --name growth-margins --store ~/naics-artifacts --output growth_margins.json

Fix each panel's non-inferiority margin δ from a reference arm (Req 5).

δ is the multiple times the reference arm's across-seed standard deviation of the panel's decision statistic (D10). Fix the margins before any other arm of a decision reads a panel: a decision refuses every run that read before its margins were fixed.

$ uv run naics-embedder tools margins --reference reference.json --multiple 0.5 \
    --name reference-margins --store ~/naics-artifacts --output margins.json

Score the training-free lexical encoder on the outcome panel's validation split.

Decodes every validation query to the nearest six-digit code by hashed character trigrams under cosine distance, and reports top-1 accuracy, MRR, Hit@1/5/10 and the level of the lowest common ancestor. The read is logged in the selection log. The test split stays sealed: this command never opens it.

$ uv run naics-embedder tools outcome-baseline

Score an arm on the outcome panel's validation split under its own distance (Stage 6).

Queries go through the checkpoint's model; codes are decoded from the table exported from it. The read is logged with the table's matrix_fingerprint and the checkpoint's SHA-256. The test split stays sealed: this command never opens it.

$ uv run naics-embedder tools outcome-panel \
    --checkpoint checkpoints/reference/epoch=001.ckpt \
    --table data/reference/arm_table.parquet --purpose 'selected checkpoint validation' \
    supervision.manifest_path=PATH

Check radius variation, geometry and loss gradients for one selected checkpoint.

Gradients use epoch 0, step 0 of the saved seed and saved query chunk size. The checkpoint and its table must share an export provenance. The radius checks are the hyperbolic arm's: a flat arm (Req 12) has no radial term or live-radius head, so its report checks its terms and scales alone and records radius as null. The report names the arm's geometry and is written even when a measured criterion fails; a failure exits 1. No evaluation split is scored.

Score an arm on the regressor panel: out-of-sample predictions per row (roadmap Stage 3).

Every Req 2 comparator is fitted by ridge on standardized features, the penalty tuned inside the remainder. The validation split reads only the remainder; the test split opens each regime's sealed outer set first, and both the opening and the read are logged.

It reads level mode only. Every read scores the arm and the text-only table, and Req 24 records the economic margin before any candidate's growth error exists, so a config whose outcome is growth is refused before anything is read.

$ uv run naics-embedder tools regressor-panel --coordinates arm.parquet \
    --text-only text_only.parquet --codebook PATH/naics_codebook.parquet

Read each trained seed once on all three validation panels and save its arm record.

Every seed's checkpoints and monitor reads are checked before the first decision read. The record carries the monitor reads that selected each checkpoint. --accelerator describes training; the export and decision reads use this machine's device.

It reads the regressor panel in level mode only (D8): a regressor panel config whose outcome is growth is refused before any seed is checked or read (Req 24).

Embed every code's text with the arm's backbone, frozen (roadmap D9).

Each of the four channels is mean-pooled over its tokens, and a code's vector is the mean of its present channels. The backbone is read from the local Hugging Face cache. The regressor panel reduces the table to the arm's dimension by PCA.

$ uv run naics-embedder tools text-only-table \
    --descriptions data/naics_descriptions.parquet --output /tmp/text_only.parquet

Plot the run's monitor MRR, loss means, logit scales and radius mean and SD per level.

Read epoch_summary.jsonl beside the run's checkpoints. The figure is epoch_metrics.png in --output-dir, or visualizations beside the summary by default.