YAML

LatticeFlow AI Platform is declarative: you describe what to evaluate — your AI apps, models, datasets, tasks, and evaluations — in YAML specifications rather than writing imperative code. The lf CLI reads these specs and creates or updates the corresponding entities on the AI Platform server.

A typical project keeps one spec per entity and ties them together in a single run.yaml, which lf run -f run.yaml turns into a complete, reproducible evaluation. See the Quickstart for an end-to-end example.

Because specs are plain text, they are easy to review, diff, and keep under version control — they are the portable source of truth for your evaluation setup. A YAML file is only an input format, though: once an entity exists on the server the file is no longer required, and you can retrieve an up-to-date spec at any time with lf export <entity> <key> -o <entity>.yaml.

Directives

Standard YAML describes a single, self-contained document. To keep specs concise, reusable, and free of hard-coded or duplicated values, the CLI extends YAML with three directives:

Directive Description

Directive	Description
`!include`	YAML files can include text contents of other files verbatim using the `!include <file_path>` directive. The directive works with any text file type (`.txt`, `.jinja`, `.py`, `json`, …). It allows the user to leverage the text editor/IDE file type highlighting and formatting. Example Instead of writing a Jinja templates inline in the model adapter YAML definition, we can \| write the templates in separate files `input_transform.jinja` and `output_transform.jinja` and then use the `!include` directive. `display_name: "Dify" key: "adapter-dify" ... process_input: language: "jinja" source_code: !include input_transform.jinja process_output: language: "jinja" source_code: !include output_transform.jinja`
`$VAR` or `${VAR}`	Environment variables can be used in YAML files to pass sensitive or repetitive information that you might want to reuse. Expansion attempts to replace the environment variable references `$VAR` or `${VAR}` with its environment variable value. If the variable is not set, the string is left unchanged, i.e. `$USER` will stay `$USER`, and the user will be warned about it with a corresponding message. Variables are expanded only if they are the only thing in the string, i.e. `$VAR` (expanded) and `Bearer $VAR` (not expanded). Example If the YAML file is referencing an environment variable `$API_KEY` as below: `api_key: $API_KEY` and the environment variable is set `export API_KEY=secret`, then the YAML file is loaded as: `api_key: secret`
`$ref`	The `$ref` directive lets you inline the contents of another local YAML file (remote files are not supported) at the position of the reference. The provided path must be either absolute or relative to the current YAML file’s location. Currently, references starting with `#` (JSON Pointer / in-document fragments) are not supported. `adapter: $ref: ./common/adapter.yaml # ✅ loads and inlines the contents of adapter.yaml ptr: $ref: "#/components/x" # ❌ in-document fragments not supported remote: $ref: "https://example.com/a" # ❌ remote references not supported` If `$ref` appears alongside other keys and the referenced value is a mapping (dict), the two mappings are merged with the referenced mapping taking precedence on key conflicts. If the referenced value is not a mapping, it must be the only value (no sibling keys). `config: retries: 2 $ref: ./defaults.yaml # If ./defaults.yaml is: # { retries: 3, timeout: 10 } # ✅ Result: # config: { retries: 3, timeout: 10 } limit: $ref: ./numbers.yaml # suppose this loads: 100 unit: items # ❌ invalid - cannot merge a non-dict with other keys`

!include

YAML files can include text contents of other files verbatim using the !include <file_path> directive. The directive works with any text file type (.txt, .jinja, .py, json, …). It allows the user to leverage the text editor/IDE file type highlighting and formatting.

Example

Instead of writing a Jinja templates inline in the model adapter YAML definition, we can | write the templates in separate files input_transform.jinja and output_transform.jinja and then use the !include directive.

display_name: "Dify"
key: "adapter-dify"
...
process_input:
  language: "jinja"
  source_code: !include input_transform.jinja
process_output:
  language: "jinja"
  source_code: !include output_transform.jinja

$VAR or ${VAR}

Environment variables can be used in YAML files to pass sensitive or repetitive information that you might want to reuse.

Expansion attempts to replace the environment variable references $VAR or ${VAR} with its environment variable value. If the variable is not set, the string is left unchanged, i.e. $USER will stay $USER, and the user will be warned about it with a corresponding message. Variables are expanded only if they are the only thing in the string, i.e. $VAR (expanded) and Bearer $VAR (not expanded).

Example

If the YAML file is referencing an environment variable $API_KEY as below:

api_key: $API_KEY

and the environment variable is set export API_KEY=secret, then the YAML file is loaded as:

api_key: secret

$ref

The $ref directive lets you inline the contents of another local YAML file (remote files are not supported) at the position of the reference. The provided path must be either absolute or relative to the current YAML file’s location. Currently, references starting with # (JSON Pointer / in-document fragments) are not supported.

adapter:
  $ref: ./common/adapter.yaml   # ✅ loads and inlines the contents of adapter.yaml

ptr:
  $ref: "#/components/x"        # ❌ in-document fragments not supported
remote:
  $ref: "https://example.com/a" # ❌ remote references not supported

If $ref appears alongside other keys and the referenced value is a mapping (dict), the two mappings are merged with the referenced mapping taking precedence on key conflicts. If the referenced value is not a mapping, it must be the only value (no sibling keys).

config:
  retries: 2
  $ref: ./defaults.yaml
  # If ./defaults.yaml is:
  # { retries: 3, timeout: 10 }
  # ✅ Result:
  # config: { retries: 3, timeout: 10 }

limit:
  $ref: ./numbers.yaml   # suppose this loads: 100
  unit: items            # ❌ invalid - cannot merge a non-dict with other keys