Skip to content

Knowledge Converter

Cluster: Uncategorised | Type: component | MCP Tools: None

Overview

Routes a RawRecord through MIME-type dispatch to one of seven conversion paths (markdown, plain text, HTML, PDF, image, audio, video) and returns a ConvertedDoc containing markdown text, embeddings, transcripts, and outcome metadata. Outcome is surfaced via the status, warnings, and selected_backend fields on ConvertedDoc so a downstream caller can distinguish a successful empty document from a failed conversion.

When to use:

  • Normalising heterogeneous source content (papers, web pages, audio, video) to a common markdown+embeddings shape before indexing.
  • Driving the knowledge-corpus crawler pipeline (see development/corpus_crawler.py).

Example:

from mvp.knowledge_converter.converter_block import convert
from mvp.knowledge_converter.schema import RawRecord

doc = convert(RawRecord(
    url="https://example.com/paper.pdf",
    raw_bytes=open("paper.pdf", "rb").read(),
    mime_type="application/pdf",
    pub_date="2026-05-25",
    metadata={},
    domain="science",
))
if doc.status != "ok":
    log.warning("conversion %s: %s", doc.status, doc.warnings)

Launch Readiness Caveat

Optional dependencies and external services

The PDF, image, audio, and video routes all depend on either optional Python modules (pdf2image, faster_whisper, transformers, sentence-transformers, soundfile) or external services (ffmpeg binary on PATH, an Ollama HTTP endpoint at localhost:11434). When any of these is missing or unreachable, the route now sets doc.status to one of degraded / failed and adds a named warning to doc.warnings (e.g. optional_dep_missing:pdf2image, ocr_ollama_unreachable:..., transcription_unavailable:...). Operators should reject any ConvertedDoc with status != "ok" rather than treating empty content as a valid empty document.

Clean-environment dep tests live at tests/mvp/knowledge_converter/test_missing_deps.py and cover pdf2image, ffmpeg, and Ollama unreachability per CF-4.

Public API

RawRecord

Field Type Default
url str required
raw_bytes bytes required
mime_type str required
pub_date str required
metadata dict required
domain str required

ConvertedDoc

Field Type Default
text_markdown str required
clip_embeddings list field(default_factory=list)
clip_frame_refs list field(default_factory=list)
clip_frame_timestamps list field(default_factory=list)
audio_embeddings list field(default_factory=list)
audio_timestamps list field(default_factory=list)
transcript str ''
word_timestamps list field(default_factory=list)
domain str ''
source_url str ''
pub_date str ''
status str STATUS_OK
warnings list field(default_factory=list)
selected_backend str ''
content_provenance str 'external'
injection_scan dict field(default_factory=dict)

Functions

convert(raw: RawRecord) -> ConvertedDoc

Route RawRecord to the correct conversion path by mime_type.