mthds-inputs

name	mthds-inputs
description	Prepare inputs for MTHDS methods. Use when user says "prepare inputs", "create inputs", "use my files", "generate test data", "template", "synthesize inputs", "mock inputs", "I have a PDF/image/document to use", "make sample data", or wants to create inputs.json for running a .mthds pipeline. Handles user-provided files, synthetic data generation, placeholder templates, and mixed approaches. Defaults to automatic mode.
min_mthds_version	0.12.1

Prepare Inputs for MTHDS methods

Prepare input data for running MTHDS method bundles. This skill is the single entry point for all input preparation needs: extracting a placeholder template, generating synthetic test data, integrating user-provided files, or any combination.

Mode Selection

How mode is determined

1. Explicit override: If the user states a preference, always honor it:

   • Automatic signals: "just do it", "go ahead", "automatic", "quick", "don't ask"
   • Interactive signals: "walk me through", "help me", "guide me", "step by step", "let me decide"

2. Skill default: Each skill defines its own default based on the nature of the task.

3. Request analysis: If no explicit signal and no strong skill default, assess the request:

   • Detailed, specific requirements → automatic
   • Brief, ambiguous, or subjective → interactive

Mode behavior

Automatic mode:

• State assumptions briefly before proceeding
• Make reasonable decisions at each step
• Present the result when done
• Pause only if a critical ambiguity could lead to wasted work

Interactive mode:

• Ask clarifying questions at the start
• Present options at decision points
• Confirm before proceeding at checkpoints
• Allow the user to steer direction

Mode switching

• If in automatic mode and the user asks a question or gives feedback → switch to interactive for the current phase
• If in interactive mode and the user says "looks good, go ahead" or similar → switch to automatic for remaining phases

Default: Automatic.

Input strategy detection heuristics (evaluated in order):

Signal	Strategy
User provides file paths, folder paths, or mentions "my data" / "this file" / "use these images" / "here's my PDF"	User Data (or Mixed if some inputs remain unfilled)
User says "test data" / "generate inputs" / "synthesize" / "fake data" / "sample data"	Synthetic
User says "template" / "schema" / "placeholder" / "what inputs does it need?"	Template
No clear signal (e.g., called after /mthds-build with no further context)	Template, then offer to populate

Interactive additions: Ask about:

• Which user files map to which inputs (when ambiguous)
• Domain/industry context for realistic synthetic data
• Whether to generate edge cases or happy-path data
• Specific values or constraints for certain fields

---

Step 0 — Environment Check (mandatory, do this FIRST)

Run this command to check toolchain status:

# Wrapped in `bash -c` so the bash array syntax below works even when the
# session shell is zsh (Codex runs blocks under the user's shell).
bash -c '
# Pick the cached env-check from the plugin version with the highest semver.
# Pad each numeric segment to fixed width so lex sort matches semver sort
# (avoids the 0.10 < 0.9 lex-order trap). Sort keys are digits-only by
# construction, so the [[ > ]] compare is locale-independent. Bash 3.2 OK.
_best_f=""; _best_k=""
for f in "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/mthds/*/bin/mthds-env-check; do
  [ -x "$f" ] || continue
  _v="${f%/bin/*}"; _v="${_v##*/}"
  _k=""; IFS=. read -ra _parts <<<"${_v%%[-+]*}"
  for _p in "${_parts[@]}"; do _p=${_p%%[!0-9]*}; _k="${_k}$(printf %06d "${_p:-0}")"; done
  [[ "$_k" > "$_best_k" ]] && { _best_f="$f"; _best_k="$_k"; }
done
[ -n "$_best_f" ] && exec "$_best_f" "0.12.1" --codex
echo "MTHDS_ENV_CHECK_MISSING"
'

Interpret the output:

• MTHDS_AGENT_MISSING → STOP. Do not proceed. Tell the user:

The mthds-agent CLI is required but not installed. Install it with:

npm install -g mthds

Then re-run this skill.

• MTHDS_AGENT_VERSION_UNKNOWN → STOP. The installed mthds-agent returned an unparseable version. Tell the user:

Could not parse the output of mthds-agent --version. Your installation may be corrupt. Reinstall with:

npm install -g mthds@latest

Then re-run this skill.

• MTHDS_AGENT_OUTDATED <installed> <required> → The installed mthds-agent is too old for this plugin. Do not hard-stop. Instead, tell the user their mthds-agent (v<installed>) is older than the required v<required>, then follow the upgrade flow to offer upgrading mthds-agent via npm install -g mthds@latest. After the upgrade flow completes (whether the user upgraded or declined), proceed to Step 1. The upgrade flow's "Not now" and "Never ask" options let users continue with current versions.

• MTHDS_UPDATE_CHECK_FAILED ... → WARN. The update check command failed. Show the error output to the user. Suggest checking network connectivity and mthds-agent installation. Proceed to Step 1 with current versions.

• UPGRADE_AVAILABLE ... → Read upgrade flow and follow the upgrade prompts before continuing to Step 1.

• JUST_UPGRADED ... → Announce what was upgraded to the user, then continue to Step 1.

• UP_TO_DATE ... → Proceed to Step 1. The line is a terse list of verified installed versions (e.g. UP_TO_DATE mthds-agent=0.10.0 plxt=0.4.0 plugin=0.12.0); if you mention the env-check in your preamble acknowledgement, relay the agent and plugin versions you saw. Two "explicit-quiet" variants share the same prefix and are also clean — proceed to Step 1 without warning, and do not relay the quiet state unless the user is troubleshooting:

  • UP_TO_DATE update-check=disabled — the user has turned update-check off via config.
  • UP_TO_DATE update-check=snoozed — the user has an active snooze on the current version key; an upgrade would otherwise be available, but they explicitly asked for quiet.

• No output → WARN. The env-check produced no output at all, which usually means mthds-agent itself is broken or the wrapper script bailed before printing. Tell the user the environment check could not be confirmed, then proceed cautiously to Step 1.

• MTHDS_ENV_CHECK_MISSING → WARN. The env-check script was not found at either expected path. Tell the user the environment check could not run, but proceed to Step 1.

• CODEX_CONFIG_NEEDS_SETUP → Codex's ~/.codex/ is not set up for the mthds plugin, so the bundled .mthds validation hook will not load. When this fires it is the only terminal status the env-check emits — update-check is skipped entirely (not run, not suppressed) because fixing the hook is the prerequisite and update-check's upgrade marker is one-shot; the user re-runs and gets fresh update info next time. The env-check may print one or more #-prefixed diagnostic lines after the status — relay them if present. Resolve this before Step 1:

  1. Preview — run mthds-agent codex apply-config --dry-run and show the user the output. WOULD_APPLY lists the keys it will add under applied; ALREADY_OK means no keys need adding. Either way, relay any warnings entries — those (e.g. read-only sandbox, hooks disabled) need a hand-fix apply-config will not perform. If ALREADY_OK with no warnings, treat as resolved and go to Step 1.
  2. Ask — use AskUserQuestion: "Apply Codex config now?" with options "Apply now" / "Skip".
  3. Apply now — run mthds-agent codex apply-config:
     • APPLIED / ALREADY_OK → tell the user the config is fixed and they must restart Codex for the validation hook to load (it will not load in this session). Relay any warnings — those still need a hand-fix.
     • Error about conflicting keys → show it verbatim; the user must hand-edit ~/.codex/config.toml, then re-run mthds-agent codex apply-config.
     • Error from the sandbox blocking the write to ~/.codex/config.toml → ask the user to run mthds-agent codex apply-config themselves in a terminal, then restart Codex.
  4. Skip — tell the user the validation hook stays off until they run mthds-agent codex apply-config and restart Codex.

  Then proceed to Step 1. This session has no PostToolUse hook. The mthds skills still run mthds-agent validate bundle explicitly, so .mthds files built or edited through a skill are still semantically validated — but the write-time plxt lint/fmt pass depends on the hook and will not run until Codex is restarted.

• Any other output → WARN. The preamble produced unexpected output. Show it to the user verbatim. Proceed to Step 1 cautiously.

Do not write .mthds files manually, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.

No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away. Backend configuration is only needed to run methods with live inference — use /mthds-runner-setup when you're ready.

---

Process

Step 1: Identify the Target Method

Determine the .mthds bundle and its output directory (<output_dir>). This is usually the directory containing bundle.mthds (e.g., mthds-wip/pipeline_01/).

The inputs.json file is saved directly in this directory (next to bundle.mthds):

• <output_dir>/inputs.json

If data files need to be generated or copied (images, PDFs, etc.), they go in a subdirectory:

• <output_dir>/inputs/

The /inputs subdirectory is only created when there are actual data files to store. Paths to these files are referenced from within inputs.json.

Path resolution rule: All url values in inputs.json are resolved relative to the inputs.json file itself (i.e., relative to the bundle directory), NOT relative to the current working directory. When referencing local files, you MUST either:

1. Copy files into <output_dir>/inputs/ and reference with a path relative to the inputs.json file, e.g., inputs/the_doc.pdf (preferred — keeps the bundle self-contained), or
2. Use a URL or absolute path, e.g., https://example.com/doc.pdf or /Users/alice/data/invoice.pdf

Step 2: Get Input Schema

Extract the input template from the method:

mthds-agent inputs bundle <bundle.mthds> -L <bundle-dir>/ [--pipe specific_pipe]

Output format:

{
  "success": true,
  "pipe_code": "process_document",
  "inputs": {
    "document": {
      "concept": "native.Document",
      "content": {"url": "https://mock-xxxxxxxx.invalid/..."}
    },
    "context": {
      "concept": "native.Text",
      "content": {"text": "text_value"}
    }
  }
}

For error handling, see Error Handling Reference.

Step 3: Choose Input Strategy

Based on the heuristics above and what the user has provided, follow the appropriate strategy:

• Template Strategy — placeholder JSON, no real data
• Synthetic Strategy — AI-generated realistic test data
• User Data Strategy — integrate user-provided files
• Mixed Strategy — user files + synthetic for the rest

---

Template Strategy

The fastest path. Produces a placeholder inputs.json that the user can fill in manually.

1. Take the inputs object from Step 2's output
2. For url fields, replace the mock URLs (e.g., https://mock-xxxxxxxx.invalid/...) with descriptive placeholders that explicitly tell the path resolution is relative to inputs.json, e.g: good: <VARNAME-url-or-path-relative-to-this-inputs-file> ✅ do this bad: <path-to-VARNAME> ❌ don't do that This placeholder means "replace with either a real URL, an absolute path, or a path relative to the saved inputs.json file itself," not relative to the current working directory. This placeholder means "replace with either a real URL, an absolute path, or a path relative to the saved inputs.json file itself," not relative to the current working directory.
3. Save it to <output_dir>/inputs.json (next to bundle.mthds)
4. Report the saved file path and show the template content
5. Offer: "To populate this with realistic test data, re-run /mthds-inputs and ask for synthetic data. Or provide your own files."

---

Synthetic Strategy

Generate realistic fake data tailored to the method's purpose.

Identify Input Types

Parse the schema to identify what types of synthetic data are needed:

Concept	Content Fields	Synthesis Method
native.Text	text	Generate realistic text matching the method context
native.Number	number	Generate appropriate numeric values
native.YesNo	yes_no	Generate a boolean true/false answer
native.Date	date, time?	Generate ISO 8601 date/time values; never use epoch numbers
native.Image	url, caption?, mime_type?	Use synthesize_image pipeline
native.Document	url, mime_type?	Use document generation skills or Python
native.Page	text_and_images, page_view?	Composite: text + optional images
native.TextAndImages	text?, images?	Composite: text + image list
native.JSON	json_obj	Generate structured JSON matching context
Custom structured	Per-field types	Recurse through structure fields

List types (Type[] or Type[N]): Generate multiple items. Variable lists typically need 2-5 items; fixed lists need exactly N items.

Generate Text Content

Create realistic text that matches the method's purpose:

• If the method processes invoices, generate invoice-like text
• If it analyzes reports, generate report-style content
• Match expected length (short prompts vs long documents)

Generate Numeric Content

Generate sensible values within expected ranges based on the method context.

Generate Structured Concepts

Fill each field according to its type and description.

Generate File Inputs

When inputs require actual files (Image, Document), use the appropriate generation method. See Image Generation and Document Generation below.

Assemble and Save

Create the complete inputs.json and save to <output_dir>/inputs.json (next to bundle.mthds). Any generated data files go in <output_dir>/inputs/.

---

User Data Strategy

Integrate the user's own files into the method's input schema.

Step A: Inventory User Files

Collect all files the user has provided (explicit paths, folders, or files mentioned earlier in conversation). For each file, determine its type:

Extension(s)	Detected Type	Maps To
.pdf	PDF document	native.Document (mime: application/pdf)
.docx, .doc	Word document	native.Document (mime: application/vnd.openxmlformats-officedocument.wordprocessingml.document)
.xlsx, .xls	Spreadsheet	native.Document (mime: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
.pptx, .ppt	Presentation	native.Document (mime: application/vnd.openxmlformats-officedocument.presentationml.presentation)
.jpg, .jpeg	JPEG image	native.Image (mime: image/jpeg)
.png	PNG image	native.Image (mime: image/png)
.webp	WebP image	native.Image (mime: image/webp)
.gif	GIF image	native.Image (mime: image/gif)
.svg	SVG image	native.Image (mime: image/svg+xml)
.tiff, .tif	TIFF image	native.Image (mime: image/tiff)
.bmp	BMP image	native.Image (mime: image/bmp)
.txt	Plain text	native.Text (read file content)
.md	Markdown text	native.Text (read file content)
.json	JSON data	native.JSON or custom structured concept
.csv	CSV data	native.Text (read as text) or native.JSON (parse to objects)
.html, .htm	HTML	native.Html
http://..., https://...	Web page URL	native.Document (mime: text/html)

Step B: Expand Folders

When the user provides a folder path:

1. List all files in the folder (non-recursive by default, recursive if user requests)
2. Filter to supported file types
3. Group files by detected type
4. Match to list-type inputs (Image[], Document[], etc.)

Example: User provides ./invoices/ containing 5 PDFs. The method expects documents: Document[]. Map all 5 PDFs to that list input.

Step C: Match Files to Inputs

For each input variable in the schema, attempt to match user-provided files:

Matching rules (applied in order):

1. Exact name match: Input variable invoice matches a file named invoice.pdf
2. Type match (single candidate): If only one input expects native.Image and the user provided exactly one image file, match them
3. Type match (multiple candidates): If multiple inputs of the same type exist:
   • In automatic mode: match by name similarity (variable name vs filename)
   • In interactive mode: ask the user which file goes where
4. Folder to list: If a folder contains files of a single type and an input expects a list of that type, map the folder contents to that input
5. Unmatched files: Report them and ask if they should be ignored or mapped to a specific input
6. Unfilled inputs: After matching, any inputs still without data can be left as placeholders or filled with synthetic data (see Mixed Strategy)

Step D: Copy Files to Output Directory

Copy (or symlink) user files into <output_dir>/inputs/ so inputs.json can reference them with paths relative to the inputs.json file itself (i.e., relative to the bundle directory where inputs.json lives). This keeps the pipeline directory self-contained. Only create the inputs/ subdirectory if there are actual files to copy.

Use descriptive filenames: if the input variable is invoice, copy to <output_dir>/inputs/invoice.pdf (preserving original extension).

Step E: Build Content Objects

For each matched file, construct the proper content object:

Document input:

{
  "concept": "native.Document",
  "content": {
    "url": "inputs/invoice.pdf",
    "mime_type": "application/pdf"
  }
}

Web page Document input:

{
  "concept": "native.Document",
  "content": {
    "url": "https://example.com/article",
    "mime_type": "text/html"
  }
}

Image input:

{
  "concept": "native.Image",
  "content": {
    "url": "inputs/photo.jpg",
    "mime_type": "image/jpeg"
  }
}

Text input (from .txt or .md file — read the file content):

{
  "concept": "native.Text",
  "content": {
    "text": "<actual file content read from the .txt/.md file>"
  }
}

Image list input (from folder):

{
  "concept": "native.Image",
  "content": [
    {"url": "inputs/img_001.jpg", "mime_type": "image/jpeg"},
    {"url": "inputs/img_002.jpg", "mime_type": "image/jpeg"},
    {"url": "inputs/img_003.png", "mime_type": "image/png"}
  ]
}

Step F: Assemble and Save

Combine all content objects into a single inputs.json and save to <output_dir>/inputs.json (next to bundle.mthds).

Step G: Report

Show the user:

• Which files were matched to which inputs
• Any unfilled inputs (offer synthetic or placeholder)
• The final inputs.json content
• Path to the saved file

---

Mixed Strategy

Combines user data with synthetic generation for any remaining gaps.

1. Follow User Data Strategy Steps A-E to match user files
2. For each unfilled input, apply Synthetic Strategy
3. Assemble the complete inputs.json combining both sources
4. Report which inputs came from user data and which were synthesized

---

Image Generation

Use the synthesize_image Pipelex pipeline to generate test images.

Command:

First, create an input file (e.g., <output_dir>/image_request.json):

{
  "request": {
    "concept": "synthetic_data.ImageRequest",
    "content": {
      "category": "<category>",
      "description": "<optional description>"
    }
  }
}

Then run:

mthds-agent run bundle pipelex/builder/synthetic_inputs/synthesize_image.mthds -L pipelex/builder/synthetic_inputs/ --inputs <output_dir>/image_request.json

Image Categories:

Category	Use For	Example Description
photograph	Real-world photos, product images, portraits	"A professional headshot of a business person"
screenshot	UI mockups, app screens, web pages	"A mobile banking app dashboard showing account balance"
chart	Data visualizations, graphs, plots	"A bar chart showing quarterly sales by region"
diagram	Technical diagrams, flowcharts, architecture	"A system architecture diagram with microservices"
document_scan	Scanned papers, receipts, forms	"A scanned invoice from a hardware store"
handwritten	Handwritten notes, signatures	"Handwritten meeting notes on lined paper"

Output: The pipeline saves the generated image to <output_dir>/inputs/ and returns the file path.

For image synthesis error handling, see Error Handling Reference.

---

Document Generation

Generate test documents based on the document type needed.

PDF Documents

reportlab is a dependency of pipelex — always available, no additional installation needed. For how to invoke Python, see Python Execution Reference.

Basic PDF (Canvas API)

"$(uv tool dir)/pipelex/bin/python" << 'PYEOF'
from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("<output_dir>/inputs/test_document.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()
PYEOF

Multi-Page PDF (Platypus)

"$(uv tool dir)/pipelex/bin/python" << 'PYEOF'
from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("<output_dir>/inputs/test_report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)
PYEOF

Professional Reports with Tables

"$(uv tool dir)/pipelex/bin/python" << 'PYEOF'
from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.lib import colors

# Sample data
data = [
    ['Product', 'Q1', 'Q2', 'Q3', 'Q4'],
    ['Widgets', '120', '135', '142', '158'],
    ['Gadgets', '85', '92', '98', '105']
]

# Create PDF with table
doc = SimpleDocTemplate("<output_dir>/inputs/test_report.pdf")
elements = []

# Add title
styles = getSampleStyleSheet()
title = Paragraph("Quarterly Sales Report", styles['Title'])
elements.append(title)

# Add table with advanced styling
table = Table(data)
table.setStyle(TableStyle([
    ('BACKGROUND', (0, 0), (-1, 0), colors.grey),
    ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
    ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
    ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
    ('FONTSIZE', (0, 0), (-1, 0), 14),
    ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
    ('BACKGROUND', (0, 1), (-1, -1), colors.beige),
    ('GRID', (0, 0), (-1, -1), 1, colors.black)
]))
elements.append(table)

doc.build(elements)
PYEOF

Last resort — use a public test PDF URL:

{
  "url": "https://www.w3.org/WAI/WCAG21/Techniques/pdf/img/table-word.pdf",
  "mime_type": "application/pdf"
}

Word Documents (DOCX)

If example-skills:docx skill is available:

Use the /docx skill to create a Word document with the following content:
[Describe the document content, structure, and formatting]
Save to: <output_dir>/inputs/<filename>.docx

If skill is NOT available, create using Python (see Python Execution Reference):

uv run --with python-docx python << 'PYEOF'
from docx import Document

doc = Document()
doc.add_heading('Test Document', 0)
doc.add_paragraph('This is synthetic test content for method testing.')
# Add more content as needed
doc.save('<output_dir>/inputs/test_document.docx')
PYEOF

Spreadsheets (XLSX)

If example-skills:xlsx skill is available:

Use the /xlsx skill to create a spreadsheet with the following data:
[Describe columns, rows, and sample data]
Save to: <output_dir>/inputs/<filename>.xlsx

If skill is NOT available, create using Python (see Python Execution Reference):

uv run --with openpyxl python << 'PYEOF'
from openpyxl import Workbook

wb = Workbook()
ws = wb.active
ws['A1'] = 'Column1'
ws['B1'] = 'Column2'
ws['A2'] = 'Value1'
ws['B2'] = 'Value2'
wb.save('<output_dir>/inputs/test_spreadsheet.xlsx')
PYEOF

---

Fallback Strategy:

1. For PDFs: use reportlab via pipelex's Python ("$(uv tool dir)/pipelex/bin/python")
2. For DOCX/XLSX: use the /docx or /xlsx skill, or uv run --with <package> python
3. For any format: use public test file URLs as fallback
4. As last resort, ask user to provide test files

---

Validate & Run

After assembling the inputs, confirm readiness:

Inputs are ready. inputs.json has been saved with real values — no placeholders remain.

Then offer to run:

# Dry run with the prepared inputs (directory mode auto-detects bundle, inputs, library dir)
mthds-agent run bundle <bundle-dir>/ --dry-run

# Full run (uses actual AI/extraction models)
mthds-agent run bundle <bundle-dir>/

---

Native Concept Content Structures

Text

{"text": "The actual text content"}

Number

{"number": 42}

YesNo

{"yes_no": true}

Date

{"date": "2026-07-08", "time": null}

Date with time

{"date": "2026-07-08", "time": "15:40:00+02:00"}

Image

{
  "url": "inputs/image.jpg",
  "caption": "Optional description",
  "mime_type": "image/jpeg"
}

Document

{
  "url": "inputs/document.pdf",
  "mime_type": "application/pdf"
}

Document (Web Page)

{
  "url": "https://example.com/article",
  "mime_type": "text/html"
}

TextAndImages

{
  "text": {"text": "Main text content"},
  "images": [
    {"url": "inputs/img1.png", "caption": "Figure 1"}
  ]
}

Page

{
  "text_and_images": {
    "text": {"text": "Page content..."},
    "images": []
  },
  "page_view": null
}

JSON

{"json_obj": {"key": "value", "nested": {"data": 123}}}

---

Complete Examples

Example 1: Template for a Haiku writer

Method: Haiku pipeline expecting theme: Text

mthds-agent inputs bundle mthds-wip/pipeline_01/bundle.mthds -L mthds-wip/pipeline_01/

Save the inputs from the output directly to mthds-wip/pipeline_01/inputs.json.

Example 2: Synthetic data for an image analysis pipeline

Method: Image analyzer expecting image: Image and analysis_prompt: Text

1. Get schema, identify needs: test photograph + instruction text
2. Generate image via synthesize_image.mthds with category photograph
3. Write analysis prompt text matching the method context
4. Assemble:

{
  "image": {
    "concept": "native.Image",
    "content": {
      "url": "inputs/city_street.jpg",
      "mime_type": "image/jpeg"
    }
  },
  "analysis_prompt": {
    "concept": "native.Text",
    "content": {
      "text": "Analyze this street scene. Count visible people and describe the atmosphere."
    }
  }
}

Example 3: User-provided invoice PDF

Method: Invoice processor expecting invoice: Document and instructions: Text

User says: "Use my file ~/documents/invoice_march.pdf"

1. Get schema: needs invoice (Document) + instructions (Text)
2. Inventory: user provided invoice_march.pdf (PDF = Document type)
3. Match: invoice_march.pdf maps to invoice input (name similarity + type match)
4. Copy: cp ~/documents/invoice_march.pdf <output_dir>/inputs/invoice.pdf
5. Unfilled: instructions has no user file. Generate synthetic text: "Extract all line items, totals, and vendor information from this invoice."
6. Assemble:

{
  "invoice": {
    "concept": "native.Document",
    "content": {
      "url": "inputs/invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "instructions": {
    "concept": "native.Text",
    "content": {
      "text": "Extract all line items, totals, and vendor information from this invoice."
    }
  }
}

Example 4: Folder of images for batch processing

Method: Batch image captioner expecting images: Image[]

User says: "Use the photos in ./product-photos/"

1. Get schema: needs images (Image[])
2. Expand folder: ./product-photos/ contains shoe.jpg, hat.png, bag.jpg
3. Copy all to <output_dir>/inputs/
4. Assemble:

{
  "images": {
    "concept": "native.Image",
    "content": [
      {"url": "inputs/shoe.jpg", "mime_type": "image/jpeg"},
      {"url": "inputs/hat.png", "mime_type": "image/png"},
      {"url": "inputs/bag.jpg", "mime_type": "image/jpeg"}
    ]
  }
}

---

Reference

• 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 concept definitions and syntax
• Native Content Types — read for the full attribute reference of each native content type when assembling input JSON