Ctx Markitdown¶

Ctx MarkItDown — mvp.ctx_markitdown

Cluster: Context & Retrieval | Type: component | MCP Tools: 26

Overview¶

Document-to-Markdown converter backed by the MarkItDown library, supporting PDF, DOCX, HTML, image files, and URLs as input sources. The converted Markdown text is returned in MarkdownOutput.content alongside the source path and character count. If MarkItDown is not installed, infer() returns a clear error rather than silently producing empty output.

Outputs expose the canonical G6 degradation envelope: completion_state, warning_card, evidence, request_id, task_id, and run_id. Conversions that actually extract text are verified; missing MarkItDown, blocked sources, conversion exceptions, and conversions that ran without error but extracted no text (empty or whitespace-only) are surfaced as blocked-escalated with stable G6_E_* warning-card codes rather than cosmetic completion. Batch conversion can be qualified-draft when useful partial work exists but sources were skipped or degraded.

When to use:

• Converting diverse document formats to Markdown before feeding into an LLM or RAG pipeline
• Extracting readable text from PDFs or Office files without manual pre-processing
• Building a normalised text corpus from a mixed-format document collection

Example:

from mvp.ctx_markitdown import CtxMarkitdownBlock, DocumentInput

block = CtxMarkitdownBlock(name="md")
result = block.infer(DocumentInput(source="/reports/q1.pdf"))
# result.value.content → Markdown text of the PDF

Works well with: ctx_langextract, ctx_rag, ctx_scrapling

Launch Readiness Caveat¶

State Surface and Degradation Envelope¶

The MCP tier stores conversion history, source names, content previews, errors, templates, jobs, and pipelines in SQLite at $MARKITDOWN_DB_PATH (default ~/.markitdown/markitdown.db). Rows persist until explicit delete or purge operations, or until the database is removed. Adapter-level encryption and content sanitization are not enforced; callers handling sensitive documents should treat the database path as sensitive state.

info, list_formats, resource_check, convert, and batch_convert include capability evidence describing static format support versus live optional dependency availability (markitdown, OCR, transcription, and LLM rerank). This is the component's weakest-link disclosure: conversion usefulness is constrained by source policy, MarkItDown availability, and format-specific optional backends.

Public API¶

MarkitdownRerankDecision¶

Validated advisory rerank verdict over a returned search-record set.

LLMMarkitdownRerankRuntime¶

Provider-neutral search-result-rerank runtime backed by G6's LLM caller.

Constructor:

Methods:

rerank(query: str, records: list[Any]) -> MarkitdownRerankDecision¶

CtxMarkitdownRerankPatternRuntime¶

Stateless, load-bearing returned-set-ceiling enforcement.

Methods:

enforce_eligibility(decision: MarkitdownRerankDecision, records: list[Any]) -> tuple[list[Any], bool, bool]¶

CtxMarkitdownPlanner¶

Runtime-first advisory result-rerank facade with returned-order fallback.

Constructor:

Methods:

rerank(query: str, records: list[Any]) -> list[Any]¶

CtxMarkitdownBlock(AIBlock[DocumentInput, MarkdownOutput, None])¶

Converts documents (PDF, DOCX, HTML, URLs, images, …) to Markdown text

Methods:

infer(data: DocumentInput) -> Result[MarkdownOutput]¶

DocumentInput(BaseModel)¶

Input for CtxMarkitdownBlock — a path or URL to convert.

MarkdownOutput(BaseModel)¶

Markdown text produced from a document.

Methods:

model_post_init(__context: Any) -> None¶

CtxMarkitdownMCPBlock(AIBlock[MCPMarkitdownInput, MCPMarkitdownOutput, dict])¶

Full-featured markitdown block with SQLite persistence.

Methods:

infer(data: MCPMarkitdownInput) -> Result[MCPMarkitdownOutput]¶

MCPMarkitdownRecord(BaseModel)¶

MCPMarkitdownInput(BaseModel)¶

MCPMarkitdownOutput(BaseModel)¶

Methods:

model_post_init(__context: Any) -> None¶

MarkitdownStore¶

Sync SQLite markitdown store with 5 tables.

Constructor:

Methods:

add_conversion(source: str, source_type: str, detected_type: str, content_preview: str, char_count: int, success: bool, error_message: str, engine: str, llm_model: str, duration_ms: int, tags: list[str], metadata_json: str) -> str¶

query_conversions(source_type: str = '', success: bool | None = None, limit: int = 50) -> list[dict[str, Any]]¶

get_conversion_stats() -> dict[str, Any]¶

delete_conversion(conversion_id: str) -> bool¶

export_history(limit: int = 1000) -> list[dict[str, Any]]¶

purge_old(days: int = 30) -> int¶

add_error(conversion_id: str, source: str, source_type: str, error_type: str, error_message: str, engine: str) -> str¶

upsert_template(name: str, description: str, source_type_filter: str, engine: str, llm_model: str, llm_prompt: str, max_execution_seconds: int, extra_options_json: str, tags: list[str]) -> str¶

get_template(name: str) -> dict[str, Any] | None¶

list_templates(tag: str = '', limit: int = 50) -> list[dict[str, Any]]¶

delete_template(name: str) -> bool¶

increment_template_use(name: str) -> None¶

create_job(input_sources_json: str, engine: str, total_files: int) -> str¶

get_job(job_id: str) -> dict[str, Any] | None¶

update_job(job_id: str, **kwargs: Any) -> bool¶

list_jobs(status: str = '', limit: int = 50) -> list[dict[str, Any]]¶

upsert_pipeline(name: str, description: str, steps_json: str, tags: list[str]) -> str¶

get_pipeline(name: str) -> dict[str, Any] | None¶

list_pipelines(limit: int = 50) -> list[dict[str, Any]]¶

delete_pipeline(name: str) -> bool¶

increment_pipeline_use(name: str) -> None¶

text_search(query: str, top_k: int = 5) -> list[dict[str, Any]]¶

TF-IDF search across conversions, templates, pipelines, and errors.

count_all() -> dict[str, int]¶

Functions¶

agentic_planner_enabled(default_enabled: bool) -> bool¶

Decide whether the agentic search-result-rerank planner should be used.

eligible_fingerprint(records: list[Any]) -> str¶

sha256 over the returned record texts (order-sensitive).

validate_markitdown_rerank_decision(decision: MarkitdownRerankDecision, n_eligible: int, expected_fingerprint: str) -> None¶

Returned-set / anti-injection guard for a search-result-rerank decision.

planner_is_llm_trusted(planner: Any) -> bool¶

Whether the BLOCK may report llm_used=True for planner.

MCP Tools¶