Run MTHDS methods

Execute MTHDS method bundles and interpret their JSON output.

Process

Prerequisite: See CLI Prerequisites

Step 1: Identify the Target

Target Command

Pipeline directory (recommended) mthds-agent pipelex run pipe <bundle-dir>/

Specific pipe in a directory mthds-agent pipelex run pipe <bundle-dir>/ --pipe my_pipe

Bundle file directly mthds-agent pipelex run pipe bundle.mthds -L <bundle-dir>/

Pipe by code from library mthds-agent pipelex run pipe my_pipe

Directory mode (recommended): Pass the pipeline directory as target. The CLI auto-detects bundle.mthds , inputs.json , and sets -L automatically — no need to specify them explicitly. This also avoids namespace collisions with other bundles.

Step 2: Prepare Inputs and Check Readiness

Fast path — inputs just prepared

If inputs were already prepared during this conversation — via /inputs (user-data, synthetic, or mixed strategy), or by manually assembling inputs.json with real values earlier in this session — skip the schema fetch and readiness check. The inputs are ready. Proceed directly to Step 3 with a normal run.

This applies when you just wrote or saw inputs.json being written with real content values. It does NOT apply after /build (which saves a placeholder template) or after /inputs with the template strategy.

Full check — cold start

If /run is invoked without prior input preparation in this session, perform the full readiness check:

Get the input schema for the target:

mthds-agent pipelex inputs bundle.mthds

Output:

{ "success": true, "pipe_code": "process_document", "inputs": { "document": { "concept": "native.Document", "content": {"url": "url_value"} }, "context": { "concept": "native.Text", "content": {"text": "text_value"} } } }

Fill in the content fields with actual values. For complex inputs, use the /inputs skill.

Input Readiness Check

Before running, assess whether inputs are ready. This prevents runtime failures from placeholder values.

No inputs required: If mthds-agent pipelex inputs returns an empty inputs object ({} ), inputs are ready — skip to Step 3.

Inputs required: If inputs exist, check inputs.json for readiness:

• Does inputs.json exist in the bundle directory?

• If it exists, scan all content values for placeholder signals:

• Template defaults: "url_value" , "text_value" , "number_value" , "integer_value" , "boolean_value" , or any value matching the pattern *_value

• Angle-bracket placeholders: values containing <...> (e.g. <path-to-cv.pdf> , <your-text-here> )

• Non-existent file paths: url fields pointing to local files that don't exist on disk

Readiness result:

• Ready: inputs.json exists AND all content values are real (no placeholders, referenced files exist) → proceed to Step 3 with normal run

• Not ready: inputs.json is missing, OR contains any placeholder values → proceed to Step 3 with dry-run fallback

Step 3: Choose Run Mode

If inputs are not ready

Default to --dry-run --mock-inputs and inform the user:

"The inputs for this pipeline contain placeholder values (not real data). I'll do a dry run with mock inputs to validate the pipeline structure."

After the dry run, offer the user these options:

• Prepare real inputs — use /inputs to fill in actual values, then re-run

• Provide files — if the pipeline expects file inputs (documents, images), ask the user to supply file paths

• Keep dry run — accept the dry-run result as-is

Run modes reference

Mode Command Use When

Dry run + mock inputs mthds-agent pipelex run pipe <bundle-dir>/ --dry-run --mock-inputs

Quick structural validation, no real data needed, or inputs not ready

Dry run with real inputs mthds-agent pipelex run pipe <bundle-dir>/ --dry-run

Validate input shapes without making API calls (auto-detects inputs.json )

Full run mthds-agent pipelex run pipe <bundle-dir>/

Production execution (auto-detects inputs.json )

Full run inline mthds-agent pipelex run pipe <bundle-dir>/ --inputs '{"theme": ...}'

Quick execution with inline JSON inputs

Full run without graph mthds-agent pipelex run pipe <bundle-dir>/ --no-graph

Execute without generating graph visualization

Full run with memory mthds-agent pipelex run pipe <bundle-dir>/ --with-memory

When piping output to another method

Graph by default: Execution graphs (live_run.html / dry_run.html ) are now generated automatically. Use --no-graph to disable.

Inline JSON for Inputs

The --inputs flag accepts both file paths and inline JSON. The CLI auto-detects: if the value starts with { , it is parsed as JSON directly. This is the fastest path — no file creation needed for simple inputs.

Inline JSON

mthds-agent pipelex run pipe <bundle-dir>/ --inputs '{"theme": {"concept": "native.Text", "content": {"text": "nature"}}}'

File path (auto-detected in directory mode)

mthds-agent pipelex run pipe <bundle-dir>/

Step 4: Present Results

After a successful run, always show the actual output to the user — never just summarize what fields exist.

Output format modes

The CLI has two output modes:

• Compact (default): stdout is the concept's structured JSON directly — no envelope, no success wrapper. This is the primary output of the method's main concept. Parse the JSON directly for field access.

• With memory (--with-memory ): stdout has main_stuff (with json , markdown , html renderings) + working_memory (all named stuffs and aliases). Use this when piping output to another method.

The output_file and graph_files are written to disk as side effects (paths appear in logs/stderr), not in compact stdout.

4a. Determine what to show

In compact mode (default), the output is the concept JSON directly. Show the fields to the user:

{ "clauses": [...], "overall_risk": "high" }

In --with-memory mode, the output structure depends on the pipe architecture:

if main_stuff is non-empty (not {} or null): → main_stuff is the primary output (single unified result) else: → working_memory.root holds the primary output (multiple named results)

Pipe Type main_stuff present? What to show

PipeLLM, PipeCompose, PipeExtract, PipeImgGen Always main_stuff

PipeSequence Always (last step) main_stuff

PipeBatch Always (list) main_stuff

PipeCondition Always main_stuff

PipeParallel with combined_output

Yes main_stuff

PipeParallel without combined_output

No ({} ) working_memory.root entries

4b. Show the output content

In compact mode: show the JSON fields directly. For structured concepts, format for readability.

In --with-memory mode when main_stuff is present (most pipe types):

• Show main_stuff.markdown directly — this is the human-readable rendering. Display it as-is so the user sees the full output.

• For structured concepts with fields, also show main_stuff.json formatted for readability.

In --with-memory mode when main_stuff is empty (PipeParallel without combined_output ):

• Iterate working_memory.root and present each named result.

• For each entry, show the content field with its key as a label.

• Example: "french_translation: Bonjour le monde" / "spanish_translation: Hola mundo"

For dry runs: Show the same output but clearly label it as mock/simulated data.

4c. Output file

• The CLI automatically saves the full JSON output next to the bundle (live_run.json or dry_run.json ).

• The output file path appears in runtime logs (stderr), not in compact stdout.

4d. Present graph files

• Graph visualizations are generated by default (live_run.html / dry_run.html ). Use --no-graph to disable.

• The graph file path appears in runtime logs (stderr), not in compact stdout.

4e. Mention intermediate results

• If the pipeline has multiple steps, briefly note key intermediate values from working_memory (e.g., "The match analysis intermediate step scored 82/100").

• Offer: "I can show the full working memory if you want to inspect any intermediate step."

4f. Suggest next steps

• Re-run with different inputs

• Adjust prompts or pipe configurations if output quality needs improvement

Step 5: Handle Errors

When encountering runtime errors, re-run with --log-level debug for additional context:

mthds-agent --log-level debug pipelex run pipe <bundle-dir>/ --inputs data.json

For all error types and recovery strategies, see Error Handling Reference.

Execution Graphs

Execution graph visualizations are generated by default alongside the run output. Use --no-graph to disable.

mthds-agent pipelex run pipe <bundle-dir>/

Graph files (live_run.html / dry_run.html ) are written to disk next to the bundle. Their paths appear in runtime logs on stderr, not in compact stdout. When using --with-memory , graph_files is included in the returned JSON envelope.

Piping Methods

The run command accepts piped JSON on stdin when --inputs is not provided. This enables chaining methods:

mthds-agent pipelex run method extract-terms --inputs data.json --with-memory
| mthds-agent pipelex run method assess-risk --with-memory
| mthds-agent pipelex run method generate-report

When methods are installed as CLI shims, the same chain is:

extract-terms --inputs data.json --with-memory
| assess-risk --with-memory
| generate-report

• Use --with-memory on intermediate steps to pass the full working memory envelope.

• The final step omits --with-memory to produce compact output.

• --inputs always overrides stdin when both are present.

• Upstream stuff names are matched against downstream input names. Method authors should name their outputs to match the downstream's expected input names.

Reference

• CLI Prerequisites — read at skill start to check CLI availability

• Error Handling — read when CLI returns an error to determine recovery

• MTHDS Agent Guide — read for CLI command syntax or output format details

• MTHDS Language Reference — read for .mthds syntax documentation

• Native Content Types — read when interpreting pipeline outputs or preparing input JSON, to understand the attributes of each content type