1. Validate a Spec

CLI messages are translated into ko / en / zh / ja / es. Use eulerstack --lang en ... (or EULERSTACK_LANG=en) for English. Default is Korean. For deep mixer explanations see mixers/00_overview.md.

This tutorial covers the first step in any EulerStack workflow: validating a YAML spec. Before building any model, you want to confirm the YAML you wrote is structurally correct and free of internal contradictions. Skipping this step tends to turn into silent failures deep inside training loops, wasting GPU time.

Why Validation Matters

An LLM architecture spec is a tightly-coupled bundle of dozens of parameters. For example, d_model must be divisible by n_heads, and a layer using mixer.type: mamba cannot also enable state.kv_cache: true. There are dozens of such constraints, and they are impossible to check reliably by eye.

Feeding an unvalidated spec straight into training produces three typical failure modes:

• Immediate failure — the model constructor raises RuntimeError with a vague message, requiring long debugging.
• Silent failure — the model is built but the parameter counts or layer topology differ from expectations. Training is slow or does not converge, and you only find out after hours of GPU time.
• Suboptimal choices — the spec is technically valid but head_dim is unusually small or large, hurting efficiency at the same parameter budget. These cases surface as realism warnings.

EulerStack's validation catches all three before any GPU allocation.

Three Validation Layers

Validation runs in three independent stages. Each stage must pass before moving to the next.

1. Schema validation (structural) Checks that the YAML follows the defined key structure and that types / enums are correct. Typos, missing required fields, and invalid enum values are caught here. Example: modle.d_model (typo), mixer.type: "transformer" (not a real enum).

2. Cross-field validation (compatibility) Catches cases where individual fields are valid but their combination is contradictory. Example: n_heads=8 with n_kv_heads=3 fails because 8÷3 is not an integer, which would break GQA grouping.

3. Realism checks (empirical sanity) Warns about configurations that are mathematically possible but empirically poor. Example: head_dim=16 is unusually small, head_dim=512 is unusually large. Realism checks produce warnings only; they never block validation.

The reason for three layers is separation of concerns. Schema violations are bugs, cross-field violations are design errors, and realism warnings are judgment calls. Each has a different severity and a different fix path.

Basic Usage

The simplest validation command is:

eulerstack validate --preset my_model.yml

On success you get one line:

OK: my_model.yml is a valid spec.

On failure you get a three-line error format that tells you what went wrong, how to fix it, and where to read more:

ValidationError: model.d_model (65) must be divisible by model.n_heads (8)
Fix: Adjust d_model or n_heads so that d_model % n_heads == 0
See: docs/architectures/yaml_v1_spec.md

This format is shared across every CLI command. Whenever an error surfaces, the output always shows what, how to fix it, and where to look in one compact block.

Language Selection

All CLI messages are available in five languages. Use the --lang flag to switch:

eulerstack --lang en validate --preset my_model.yml   # English
eulerstack --lang zh validate --preset my_model.yml   # Chinese (Simplified)
eulerstack --lang ja validate --preset my_model.yml   # Japanese
eulerstack --lang es validate --preset my_model.yml   # Spanish

The default is Korean (ko). You can also set the environment variable EULERSTACK_LANG:

export EULERSTACK_LANG=en
eulerstack validate --preset my_model.yml   # now outputs in English

Precedence: --lang option > EULERSTACK_LANG env var > default (ko).

Detailed Report

Adding --report gives much more than OK/FAIL. The report includes results from all three validation layers plus an estimated parameter count and a layer-composition breakdown.

eulerstack validate --preset configs/presets/arch_advanced_jamba.yml --report

The report contains:

• Schema: OK or a specific error
• Estimated parameters: e.g. 1.20B (1,199,582,208)
• Total layers and breakdown: e.g. 32 (attention:8, mamba:24)
• Realism warnings: head_dim range, MoE ratio, seq_len/d_model ratio
• INFO: per-template layer composition

The report is also the most convenient way to visually confirm that the model is configured the way you intended before spending GPU time on it.

What Kinds of Errors Get Caught?

Below are representative errors caught by schema and cross-field validation. The leftmost column is the error type, middle is an example of invalid YAML, and rightmost is the internal rule ID.

Realism warnings (non-blocking) include:

• head_dim < 32 or head_dim > 256
• target_params differs from estimate by more than 30%
• Excessive experts > 64
• max_seq_len / d_model > 64 (unusual ratio)
• family_hint inconsistent with the actual mixer composition

Next Steps

Once validation passes, the next step is to inspect the model structure visually.

• Tutorial 2: Use Presets — explore the 39 validated presets
• Tutorial 4: Compile and Explain — explain in detail
• Mixer overview — what each mixer does