Skip to content

Language Reference

This document describes the core constructs of the Tuned Variables Language (TVL).

Tunable Variables (tvars)

Variables are the inputs to your system that you want to optimize.

Types

Type Description Example
enum[str] A set of string choices. ["gpt-4", "claude-3"]
float Continuous numerical value. range: [0.0, 1.0]
int Discrete numerical value. range: [1, 10]
bool Boolean value. [true, false]

Example

tvars:
  - name: chunk_size
    type: int
    domain:
      range: [128, 1024]
      step: 128

Constraints

Constraints define the valid configuration space.

Structural Constraints

These are hard rules that must always be true. They are checked before any trial is run.

Syntax: * when <condition> then <consequence> * require <condition>

Operators: * Comparison: =, !=, <, <=, >, >= * Logic: and, or, not * Set: in

Example:

constraints:
  structural:
    - when: model = "gpt-4"
      then: max_tokens <= 8192
    - require: temperature > 0.0

Derived Constraints

These constraints apply to the outputs (metrics) of your system. They are used to filter out bad results during optimization.

Example:

constraints:
  derived:
    - require: latency_p95 <= 500

Objectives

Objectives define what you want to optimize.

Directions: * maximize: Higher is better (e.g., Quality, Accuracy). * minimize: Lower is better (e.g., Latency, Cost).

Example:

objectives:
  - name: quality
    direction: maximize
  - name: cost
    direction: minimize

Promotion Policy

Defines the criteria for promoting a configuration to production.

  • dominance: The algorithm used (e.g., epsilon_pareto).
  • alpha: The risk tolerance or significance level.
  • min_effect: The minimum improvement required to consider a change significant.

Example:

promotion_policy:
  dominance: epsilon_pareto
  alpha: 0.05
  min_effect:
    quality: 0.01

tvl-check-structural path/to/module.yml --json

Exploration Budgets

When running optimization experiments, you often need to limit resource consumption. The exploration.budgets section defines these guardrails:

exploration:
  strategy:
    type: grid
  budgets:
    max_trials: 100        # Stop after 100 configuration trials
    max_spend_usd: 50.0    # Stop if estimated API costs exceed $50
    max_wallclock_s: 3600  # Stop after 1 hour of wall-clock time
Budget Description When Enforced
max_trials Maximum number of configuration trials to run Before each new trial starts
max_spend_usd Maximum estimated spend on LLM API calls After each trial (cumulative)
max_wallclock_s Maximum elapsed time in seconds Continuously during optimization

Enforcement: Budgets are enforced by the optimizer runtime (e.g., Traigent, TVO), not by the TVL CLI itself. The CLI only validates that budget values are positive and well-formed.

Example: If you set max_trials: 50 and max_spend_usd: 100, the optimizer will stop when either limit is reached—whichever comes first.

Validation Tooling

tvl-check-structural

Validates structural constraints (the when/then and require rules) to ensure they are syntactically correct and logically consistent.

tvl-check-structural path/to/module.yml --json

tvl-check-operational (Phase 3)

Validates derived constraints and budget definitions. Checks that:

  • Budget values are positive numbers
  • Derived constraint expressions reference valid metric names
  • Cost estimation is available (when required)

Validation Options (in the TVL file):

tvl:
  module: my.module
  validation:
    skip_budget_checks: true      # Bypass budget validation
    skip_cost_estimation: true    # Skip cost estimation requirements
Option Use Case
skip_budget_checks Early prototyping when you don't yet know budget limits
skip_cost_estimation When cost estimation isn't available for your model provider