Skip to content

Getting Started with TVL

This guide will walk you through creating your first TVL module to optimize a simple AI agent.

Installation

TVL is available as a Python package. Install it via pip:

pip install tvl-spec

This installs the CLI tools: tvl-validate, tvl-lint, and tvl-parse.

Your First Module

Let's imagine we are building a Customer Support Bot. We want to tune: 1. The Model (GPT-4 vs Llama 3). 2. The Temperature (Creativity). 3. The Retriever Top-K (How many documents to fetch).

Create a file named support-bot.tvl.yml:

support-bot.tvl.yml
tvl:
  module: corp.support.bot
tvl_version: "0.9"

# 1. Define Tunable Variables (tvars)
tvars:
  - name: model
    type: enum[str]
    domain: ["gpt-4o", "llama-3-70b"]

  - name: temperature
    type: float
    domain:
      range: [0.0, 1.0]
      resolution: 0.1

  - name: retriever_k
    type: int
    domain:
      range: [1, 10]

# 2. Define Constraints
constraints:
  structural:
    # If we use the open-source model, we must keep temperature low to avoid hallucinations
    - when: model = "llama-3-70b"
      then: temperature <= 0.5

# 3. Define Objectives
objectives:
  - name: quality_score
    direction: maximize
  - name: latency_ms
    direction: minimize

Validating Your Module

Run the validator to ensure your module is syntactically correct and logically consistent:

tvl-validate support-bot.tvl.yml

If everything is correct, you'll see: 

Schema + lint checks passed.

Try breaking it! Change temperature <= 0.5 to temperature <= 2.0 (which is out of the domain range [0.0, 1.0]). Run validation again:

tvl-validate support-bot.tvl.yml

You should see an error: 

[constraint_value_out_of_domain] constraints.structural[0]: Value 2.0 is not in domain of 'temperature'

Next Steps