Model References

Model references tell pipes which AI model to use. Every PipeLLM, PipeStructure, PipeImgGen, PipeExtract, PipeSearch, and PipeJudge accepts an optional model field — a string that identifies the model and, depending on its prefix, how that model is configured.

At a Glance

MTHDS defines the following forms of model reference, most distinguished by a single-character prefix:

All forms apply uniformly to all pipe types that accept a model field — there is no prefix reserved for a specific operator.

Aliases (@)

An alias maps a short, memorable name to a specific model handle.

[pipe.extract_cv]
type        = "PipeExtract"
description = "Extract text content from a CV PDF document"
inputs      = { cv_pdf = "Document" }
output      = "Page[]"
model       = "@default-text-from-pdf"

An alias is a pure name-to-handle mapping. Use aliases when you want a readable name but have no need to override model parameters.

Presets ($)

A preset bundles a model handle with extra parameters, letting method authors express how a model should behave without hardcoding provider-specific tuning. A preset can reference an alias as its underlying handle.

[pipe.analyze_cv]
type        = "PipeLLM"
description = "Analyze a CV to extract key professional information"
output      = "CVAnalysis"
model       = "$writing-factual"
prompt      = "Analyze the following CV: @cv_pages"

[pipe.analyze_cv.inputs]
cv_pages = "Page"

The $writing-factual preset might resolve to a specific model handle with a low temperature and deterministic sampling — but the bundle author does not need to know those details. Presets decouple intent ("factual writing") from implementation ("claude-4.6-opus at temperature 0.1"). A preset can also carry parameters like reasoning_effort — for instance, a $deep-analysis preset might set reasoning_effort = "high" to enable extended reasoning.

Waterfalls (~)

A waterfall defines an ordered fallback list of model handles. The runtime tries each model in sequence until one succeeds, providing resilience against model unavailability.

[pipe.generate_summary]
type        = "PipeLLM"
description = "Generate a summary with fallback models"
output      = "Text"
model       = "~summary-fallback"
prompt      = "Summarize the following: @document"

[pipe.generate_summary.inputs]
document = "Text"

The ~summary-fallback waterfall might try a primary model first, then fall back to a secondary model if the primary is unavailable. This is useful for production methods that must remain operational even when a specific model provider has an outage.

Handles (bare string)

A bare string — no prefix — is a direct model handle. The runtime resolves it to a concrete model without any indirection.

[pipe.generate_portrait]
type        = "PipeImgGen"
description = "Generate a portrait image from a description"
inputs      = { description = "Text" }
output      = "Image"
prompt      = "A professional portrait: $description"
model       = "nano-banana-pro"

Handles are the simplest form. They are convenient for quick experiments but couple the bundle to a specific model identifier.

Which Pipes Use Model References

The following operator pipe types accept the model field:

All four reference forms ($, @, ~, bare) work identically across these pipe types.

Choosing a Reference Type

• Use an alias (@) when you want a readable, stable name for a model handle but do not need to override parameters.
• Use a preset ($) when the model needs specific parameters (temperature, quality, token limits). Presets express intent without hardcoding provider details.
• Use a waterfall (~) when resilience matters — production methods that must survive model outages benefit from ordered fallbacks.
• Use a bare handle for quick prototyping or when the exact model identifier is known and no indirection is needed.

Inline Settings

The model field can also be a TOML table instead of a string, providing full model configuration directly in the pipe definition. This is useful when a pipe needs specific model parameters that do not warrant creating a named preset.

Each pipe type that accepts model has a corresponding inline settings structure:

• PipeLLM uses LLMSetting — includes model, temperature, max_tokens, image_detail, reasoning_effort, reasoning_budget.
• PipeStructure uses LLMSetting — the same shape as PipeLLM, because the typical implementation issues an LLM call for the structuring step.
• PipeImgGen uses ImgGenSetting — includes model, quality, nb_steps, guidance_scale, is_moderated, safety_tolerance.
• PipeExtract uses ExtractSetting — includes model, max_nb_images, image_min_size.
• PipeSearch uses SearchSetting — includes model, include_images, include_inline_citations, max_results.
• PipeJudge uses JudgmentSetting — model and description only.

All require a model field (the model handle) and accept an optional description.

Example — PipeLLM with inline settings:

[pipe.analyze_cv]
type = "PipeLLM"
description = "Analyze a CV"
output = "CVAnalysis"
prompt = "Analyze: @cv_pages"
model = { model = "claude-4.5-sonnet", temperature = 0.1, max_tokens = 4096 }

[pipe.analyze_cv.inputs]
cv_pages = "Page"

Example — PipeImgGen with inline settings:

[pipe.generate_portrait]
type        = "PipeImgGen"
description = "Generate a portrait"
inputs      = { description = "Text" }
output      = "Image"
prompt      = "A professional portrait: $description"
model       = { model = "flux-pro", quality = "high" }

Example — PipeExtract with inline settings:

[pipe.extract_cv]
type        = "PipeExtract"
description = "Extract text content from a CV PDF"
inputs      = { cv_pdf = "Document" }
output      = "Page[]"
model       = { model = "gpt-4.1", max_nb_images = 10 }

Example — PipeSearch with inline settings:

[pipe.deep_search]
type        = "PipeSearch"
description = "Deep research on a topic"
inputs      = { topic = "Text" }
output      = "SearchResult"
prompt      = "What are the main details about $topic?"
model       = { model = "linkup-deep", include_images = false }

Inline settings and string references are mutually exclusive — the model field is either a string or a table, never both.

For the full field reference of each settings structure, see the .mthds File Format specification.

See Also

• Pipes — Operators — the pipe types that use model references.
• Specification: Pipe Definitions — normative reference for all pipe fields.
• Building a Runtime: Model References — how runtimes resolve model reference strings.