.mthds File Format

The .mthds file is a TOML document that defines typed data (concepts) and typed transformations (pipes) within a single domain. This page is the normative reference for every field, validation rule, and structural constraint of the format.

File Encoding and Syntax

A .mthds file MUST be a valid TOML document encoded in UTF-8. The file extension MUST be .mthds. Parsers MUST reject files that are not valid TOML before any MTHDS-specific validation occurs.

Top-Level Structure

A .mthds file is called a bundle. It consists of:

1. Header fields — top-level key-value pairs that identify the bundle.
2. Concept definitions — a [concept] table and/or [concept.<ConceptCode>] sub-tables.
3. Pipe definitions — [pipe.<pipe_code>] sub-tables.

All three sections are optional in the TOML sense (an empty .mthds file is valid TOML), but a useful bundle will contain at least one concept or one pipe.

Header Fields

Header fields appear at the top level of the TOML document, before any [concept] or [pipe] tables.

Validation rules:

• domain MUST be a valid domain code (see Domain Naming Rules).
• main_pipe, if present, MUST be a valid pipe code (snake_case) and MUST reference a pipe defined in this bundle.

Example:

domain      = "legal.contracts"
description = "Contract analysis methods for legal documents"
main_pipe   = "extract_clause"

Domain Naming Rules

Domain codes define the namespace for all concepts and pipes in a bundle.

Syntax:

• A domain code is one or more snake_case segments separated by . (dot).
• Each segment MUST match the pattern [a-z][a-z0-9_]*.
• Domains MAY be hierarchical: legal, legal.contracts, legal.contracts.shareholder.

Reserved domains:

The following domain names are reserved and MUST NOT be used as the first segment of any user-defined domain:

• native — built-in concept types
• mthds — reserved for the MTHDS standard
• pipelex — reserved for the reference implementation

A compliant implementation MUST reject bundles that declare a domain starting with a reserved segment (e.g., native.custom is invalid).

Recommendations:

• Depth SHOULD be 1–3 levels.
• Each segment SHOULD be 1–4 words.

Concept Definitions

Concepts are typed data declarations. They define the vocabulary of a domain — the kinds of data that pipes accept and produce.

Simple Concept Declarations

The simplest form of concept declaration uses a flat [concept] table where each key is a concept code and the value is a description string:

[concept]
ContractClause = "A clause extracted from a legal contract"
UserProfile    = "A user's profile information"

This form declares concepts with no structure and no refinement. They exist as named types.

Structured Concept Declarations

A concept with fields uses a [concept.<ConceptCode>] sub-table:

[concept.LineItem]
description = "A single line item in an invoice"

[concept.LineItem.structure]
product_name = { type = "text", description = "Name of the product", required = true }
quantity     = { type = "integer", description = "Quantity ordered", required = true }
unit_price   = { type = "number", description = "Price per unit", required = true }

Both forms MAY coexist in the same bundle. A bundle MAY mix simple declarations in [concept] with structured declarations as [concept.<Code>] sub-tables.

Concept Blueprint Fields

When using the structured form [concept.<ConceptCode>], the following fields are available:

Validation rules:

• refines and structure MUST NOT both be present on the same concept. A concept either refines another concept or defines its own structure, not both.
• refines, if present, MUST be a valid concept reference: either a bare concept code (PascalCase) or a domain-qualified reference (domain.ConceptCode). Cross-package references (alias->domain.ConceptCode) are also valid.
• Concept codes MUST be PascalCase, matching the pattern [A-Z][a-zA-Z0-9]*.
• Concept codes MUST NOT collide with native concept codes (see Native Concepts).

Concept Refinement

Refinement establishes a specialization relationship between concepts. A concept that refines another inherits its semantic meaning and can be used anywhere the parent concept is expected.

[concept.NonCompeteClause]
description = "A non-compete clause in an employment contract"
refines     = "ContractClause"

The refines field accepts:

• A bare concept code: "ContractClause" — resolved within the current bundle's domain.
• A domain-qualified reference: "legal.ContractClause" — resolved within the current package.
• A cross-package reference: "acme_legal->legal.contracts.NonDisclosureAgreement" — resolved from a dependency.

Concept Structure Fields

When structure is a table, each key is a field name and each value is a field blueprint. Field names MUST NOT start with an underscore (_), as these are reserved for internal use. Field names MUST NOT collide with reserved field names (Pydantic model attributes and internal metadata fields).

Field Blueprint

Each field in a concept structure is defined by a field blueprint:

Field Types

The type field accepts the following values:

When type is omitted and choices is provided, the field is an enumeration field. The value MUST be one of the strings in the choices array.

Validation rules for field types:

• type = "dict": key_type and value_type MUST both be non-empty.
• type = "concept": concept_ref MUST be set. default_value MUST NOT be set.
• type = "list" with item_type = "concept": item_concept_ref MUST be set.
• item_concept_ref MUST NOT be set unless item_type = "concept".
• concept_ref MUST NOT be set unless type = "concept".
• If choices is provided and type is omitted, default_value (if present) MUST be one of the values in choices.
• If both type and default_value are set, the runtime type of default_value MUST match the declared type.

Example — concept with all field types:

[concept.CandidateProfile]
description = "A candidate's profile for job matching"

[concept.CandidateProfile.structure]
full_name        = { type = "text", description = "Full name", required = true }
years_experience = { type = "integer", description = "Years of professional experience" }
gpa              = { type = "number", description = "Grade point average" }
is_active        = { type = "boolean", description = "Whether actively looking", default_value = true }
graduation_date  = { type = "date", description = "Date of graduation" }
skills           = { type = "list", item_type = "text", description = "List of skills" }
metadata         = { type = "dict", key_type = "text", value_type = "text", description = "Additional metadata" }
seniority_level  = { description = "Seniority level", choices = ["junior", "mid", "senior", "lead"] }
address          = { type = "concept", concept_ref = "Address", description = "Home address" }
references       = { type = "list", item_type = "concept", item_concept_ref = "ContactInfo", description = "Professional references" }

Native Concepts

Native concepts are built-in types that are always available in every bundle without declaration. They belong to the reserved native domain.

Native concepts MAY be referenced by bare code (Text, Image) or by qualified reference (native.Text, native.Image). Bare native concept codes always take priority during resolution.

A bundle MUST NOT declare a concept with the same code as a native concept. A compliant implementation MUST reject such declarations.

Pipe Definitions

Pipes are typed transformations. Each pipe has a typed signature: it declares what concepts it accepts as input and what concept it produces as output.

Common Pipe Fields

All pipe types share these base fields:

Pipe codes:

• Pipe codes are the keys in [pipe.<pipe_code>] tables.
• Pipe codes MUST be snake_case, matching the pattern [a-z][a-z0-9_]*.

Input names:

• Input names MUST be snake_case.
• Dotted input names are allowed for nested field access (e.g., my_input.field_name), where each segment MUST be snake_case.

Concept references in inputs and output:

Concept references in inputs and output support an optional multiplicity suffix:

Concept references MAY be bare codes (Text), domain-qualified (legal.ContractClause), or cross-package qualified (alias->domain.ConceptCode).

Example:

[pipe.analyze_contract]
type        = "PipeLLM"
description = "Analyze a legal contract and extract key clauses"
output      = "ContractClause[5]"

[pipe.analyze_contract.inputs]
contract_text = "Text"

Pipe Types

MTHDS defines pipe types in two categories:

Operators — pipes that perform a single transformation:

Controllers — pipes that orchestrate other pipes:

Operator: PipeLLM

Generates output by invoking a large language model with a prompt.

Prompt template syntax:

• {{ variable_name }} — standard Jinja2 variable substitution.
• @variable_name — shorthand, preprocessed to Jinja2 syntax.
• $variable_name — shorthand, preprocessed to Jinja2 syntax.
• Dotted paths are supported: {{ doc_request.document_type }}, @doc_request.priority.

Validation rules:

• Every variable referenced in prompt and system_prompt MUST correspond to a declared input (by root name). Internal variables starting with _ and the special names preliminary_text and place_holder are excluded from this check.
• Every declared input MUST be referenced by at least one variable in prompt or system_prompt. Unused inputs are rejected.

Example:

[pipe.analyze_cv]
type = "PipeLLM"
description = "Analyze a CV to extract key professional information"
output = "CVAnalysis"
model = "$writing-factual"
system_prompt = """
You are an expert HR analyst specializing in CV evaluation.
"""
prompt = """
Analyze the following CV and extract the candidate's key professional information.

@cv_pages
"""

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

Inline LLM Settings

When the model field is a table instead of a string, it defines inline model settings using the LLMSetting structure:

Validation rules:

• reasoning_effort and reasoning_budget MUST NOT both be set on the same inline LLM settings table.

Example — inline LLM 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"

Operator: PipeFunc

Calls a registered Python function.

Example:

[pipe.capitalize_text]
type          = "PipeFunc"
description   = "Capitalize the input text"
inputs        = { text = "Text" }
output        = "Text"
function_name = "my_package.text_utils.capitalize"

Operator: PipeImgGen

Generates images using an image generation model.

Validation rules:

• Every variable referenced in prompt MUST correspond to a declared input.

Example:

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

Inline Image Generation Settings

When the model field is a table instead of a string, it defines inline model settings using the ImgGenSetting structure:

Validation rules:

• quality and nb_steps MUST NOT both be set on the same inline image generation settings table.

Example — inline image generation settings:

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

Operator: PipeExtract

Extracts structured content from documents (e.g., PDF pages).

Validation rules:

• inputs MUST contain exactly one entry. The input concept SHOULD be Document or a concept that refines Document or Image.
• output MUST be "Page[]" (a variable-length list of Page).

Example:

[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"

Inline Extract Settings

When the model field is a table instead of a string, it defines inline model settings using the ExtractSetting structure:

Example — inline extract settings:

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

Operator: PipeSearch

Searches the web using a search provider and returns structured results.

Validation rules:

• Every variable referenced in prompt MUST correspond to a declared input.
• output MUST be SearchResult or a concept that refines SearchResult.

Example:

[pipe.search_topic]
type        = "PipeSearch"
description = "Search the web for information about a topic"
inputs      = { topic = "Text" }
output      = "SearchResult"
model       = "$standard"
prompt      = "What is $topic?"

Example — with date and domain filters:

[pipe.search_recent_from_sources]
type            = "PipeSearch"
description     = "Search specific sources for recent news"
inputs          = { topic = "Text" }
output          = "SearchResult"
model           = "$standard"
prompt          = "What are the latest developments about $topic?"
from_date       = "2026-01-01"
include_domains = ["reuters.com", "apnews.com", "bbc.com"]

Inline Search Settings

When the model field is a table instead of a string, it defines inline model settings using the SearchSetting structure:

Example — inline search 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 }

Operator: PipeCompose

Composes output by assembling data from working memory using either a template or a construct. Exactly one of template or construct MUST be provided.

Template Mode

When template is a string, it is a Jinja2 template rendered with the input variables. When template is a table, it MUST contain a template field (string) and a category field, and MAY contain templating_style and extra_context.

Template shorthand syntax:

MTHDS defines three shorthand patterns that a compliant preprocessor MUST expand before Jinja2 rendering:

Rules:

• A shorthand pattern MUST NOT match when the character immediately following $, @, or @? is a digit (0–9). This prevents dollar amounts (e.g., $100) and version-like strings (e.g., @2.0) from being treated as variables.
• Dotted paths are supported: $user.name, @doc.summary, @?extra.notes. Each segment of the dotted path MUST be a valid identifier.
• When a matched name ends with a . (dot), the preprocessor MUST strip the trailing dot from the variable name and place it after the expanded expression (treating it as sentence punctuation).
• Raw Jinja2 syntax ({{ }}, {% %}) MUST always be accepted alongside the shorthands.

These shorthands apply to the template field of PipeCompose, the prompt and system_prompt fields of PipeLLM, and the prompt field of PipeImgGen and PipeSearch. See Pipes — Operators: Template Mode for the full reference on categories and filters.

Template blueprint fields (table form):

Templating Style

The templating_style field controls how template output is formatted, particularly useful for templates that produce prompts for different LLM providers.

Validation rules (template mode):

• Every variable referenced in the template MUST correspond to a declared input.
• output MUST NOT use multiplicity brackets ([] or [N]).

Construct Mode

The construct table defines how each field of the output concept is composed. Each key is a field name, and the value defines the composition method:

Validation rules (construct mode):

• The root variable of every from path and every template variable MUST correspond to a declared input.
• from and template are mutually exclusive within a single field definition.

Example — construct mode:

[pipe.compose_interview_sheet]
type        = "PipeCompose"
description = "Compose the final interview sheet"
inputs      = { match_analysis = "MatchAnalysis", interview_questions = "InterviewQuestion[]" }
output      = "InterviewSheet"

[pipe.compose_interview_sheet.construct]
overall_match_score  = { from = "match_analysis.overall_match_score" }
matching_skills      = { from = "match_analysis.matching_skills" }
missing_skills       = { from = "match_analysis.missing_skills" }
questions            = { from = "interview_questions" }

Controller: PipeSequence

Executes a series of sub-pipes in order. The output of each step is added to working memory and can be consumed by subsequent steps.

Each step is a sub-pipe blueprint:

Validation rules:

• steps MUST contain at least one entry.
• nb_output and multiple_output MUST NOT both be set on the same step.
• batch_over and batch_as MUST either both be present or both be absent.
• batch_over and batch_as MUST NOT be the same value.

Example:

[pipe.process_document]
type        = "PipeSequence"
description = "Full document processing pipeline"
inputs      = { document = "Document" }
output      = "AnalysisResult"
steps = [
    { pipe = "extract_pages", result = "pages" },
    { pipe = "analyze_content", result = "analysis" },
    { pipe = "generate_summary", result = "summary" },
]

Controller: PipeParallel

Executes multiple sub-pipes concurrently. Each branch operates independently.

Validation rules:

• At least one of add_each_output or combined_output MUST be set (otherwise the pipe produces no output).
• combined_output, if present, MUST be a valid concept reference.
• Each branch follows the same sub-pipe blueprint format as PipeSequence steps.

Example:

[pipe.extract_documents]
type        = "PipeParallel"
description = "Extract text from both CV and job offer concurrently"
inputs      = { cv_pdf = "Document", job_offer_pdf = "Document" }
output      = "Page[]"
add_each_output = true
branches = [
    { pipe = "extract_cv", result = "cv_pages" },
    { pipe = "extract_job_offer", result = "job_offer_pages" },
]

Controller: PipeCondition

Routes execution to different pipes based on an evaluated condition.

Special outcomes:

Certain string values in outcomes values and default_outcome have special meaning and are not treated as pipe references:

Example:

[pipe.route_by_document_type]
type                = "PipeCondition"
description         = "Route processing based on document type"
inputs              = { doc_request = "DocumentRequest" }
output              = "Text"
expression_template = "{{ doc_request.document_type }}"
default_outcome     = "continue"

[pipe.route_by_document_type.outcomes]
technical = "process_technical"
business  = "process_business"
legal     = "process_legal"

Controller: PipeBatch

Maps a single pipe over each item in a list input, producing a list output.

Validation rules:

• input_list_name MUST exist as a key in inputs.
• input_item_name MUST NOT be empty.
• input_item_name MUST NOT equal input_list_name.
• input_item_name MUST NOT equal any key in inputs.

Example:

[pipe.batch_generate_jokes]
type             = "PipeBatch"
description      = "Generate a joke for each topic"
inputs           = { topics = "Topic[]" }
output           = "Joke[]"
branch_pipe_code = "generate_joke"
input_list_name  = "topics"
input_item_name  = "topic"

Pipe Reference Syntax

Every location in a .mthds file that references another pipe supports three forms:

Pipe references appear in:

• steps[].pipe (PipeSequence)
• branches[].pipe (PipeParallel)
• outcomes values (PipeCondition)
• default_outcome (PipeCondition)
• branch_pipe_code (PipeBatch)

Pipe definitions (the [pipe.<pipe_code>] table keys) are always bare snake_case names. Namespacing applies only to pipe references.

Concept Reference Syntax

Every location that references a concept supports three forms, symmetric with pipe references:

The disambiguation between concepts and pipes in a domain-qualified reference relies on casing:

• snake_case final segment → pipe code
• PascalCase final segment → concept code

Concept references appear in:

• inputs values
• output
• refines
• concept_ref and item_concept_ref in structure field blueprints
• combined_output (PipeParallel)

Complete Bundle Example

domain      = "joke_generation"
description = "Generating one-liner jokes from topics"
main_pipe   = "generate_jokes_from_topics"

[concept.Topic]
description = "A subject or theme that can be used as the basis for a joke."
refines     = "Text"

[concept.Joke]
description = "A humorous one-liner intended to make people laugh."
refines     = "Text"

[pipe.generate_jokes_from_topics]
type        = "PipeSequence"
description = "Generate 3 joke topics and create a joke for each"
output      = "Joke[]"
steps = [
    { pipe = "generate_topics", result = "topics" },
    { pipe = "batch_generate_jokes", result = "jokes" },
]

[pipe.generate_topics]
type   = "PipeLLM"
description = "Generate 3 distinct topics suitable for jokes"
output = "Topic[3]"
prompt = "Generate 3 distinct and varied topics for crafting one-liner jokes."

[pipe.batch_generate_jokes]
type             = "PipeBatch"
description      = "Generate a joke for each topic"
inputs           = { topics = "Topic[]" }
output           = "Joke[]"
branch_pipe_code = "generate_joke"
input_list_name  = "topics"
input_item_name  = "topic"

[pipe.generate_joke]
type        = "PipeLLM"
description = "Write a clever one-liner joke about the given topic"
inputs      = { topic = "Topic" }
output      = "Joke"
prompt      = "Write a clever one-liner joke about $topic. Be concise and witty."