markitdown-file-intake

MarkItDown File Intake

Purpose

Convert supported files or URLs into Markdown before inspection. This reduces token cost and makes binary or structured inputs easier to analyze.

When to Use

• User provides a local file in a format Microsoft MarkItDown supports.
• User provides a supported URL and Markdown conversion will improve inspection.
• Source is binary or structurally noisy enough that direct inspection is inefficient.

Do not use when:

• File is already clean text.
• User explicitly wants raw binary or metadata-only handling.
• Another tool is clearly better for the task.

Requirements

Required tool:

• Microsoft MarkItDown

Check:

Get-Command markitdown -ErrorAction SilentlyContinue
python -m markitdown --help

Install:

python -m pip install markitdown

Rules:

• Do not assume MarkItDown is installed.
• Do not install it without user approval.
• Show the install command before running it.
• Prefer user-local or project-local installation when practical.

Inputs

• File path or URL to convert.
• Optional output path for the generated Markdown.

Workflow

1. Check whether MarkItDown is available.
2. If missing, tell the user before attempting conversion.
3. Convert with Microsoft MarkItDown or the helper script in references/.

markitdown <path-or-url> -o output.md

powershell -ExecutionPolicy Bypass -File "references\convert_with_markitdown.ps1" -Source "<path-or-url>"

4. Confirm output path exists and file is non-empty.
5. Inspect the generated Markdown with narrow reads first.
6. Tell the user MarkItDown was used.

Output

• Path to the generated Markdown file
• Inspection results based on that Markdown

Verification

• MarkItDown availability was checked first
• No conversion was claimed if the tool was missing
• Generated Markdown file exists and is non-empty
• Inspection used the generated Markdown, not the original binary

Failure Modes

• Unsupported or weak conversion output
• Audio formats needing extra tooling such as ffmpeg
• Remote URL access failure
• Empty or garbled Markdown output

Missing Dependency Behavior

If MarkItDown is missing:

1. Say conversion did not happen.
2. Tell the user Microsoft MarkItDown is required.
3. Ask before installing it.
4. Show the install command.
5. Fall back to manual inspection when practical.