Skip to content

History

Revisions

  • 📝 docs(markitdown): correct OCR architecture — LLM vision is the engine, PyMuPDF only renders The page conflated PyMuPDF/fitz with the OCR capability, implying the library itself does the OCR. Per the markitdown-ocr source at v0.1.7, PyMuPDF is only a page-rendering dependency (and only a fallback after pdfplumber); the actual OCR engine is the OpenAI-compatible vision LLM configured at runtime via MARKITDOWN_LLM_*. The package's own description is "Extracts text from images in PDF, DOCX, PPTX, and XLSX via LLM Vision," and its OCR service class is LLMVisionOCRService, which base64-encodes a page image and sends it to a chat.completions.create vision call. Practical consequence: building with INSTALL_OCR_PLUGIN=true but leaving MARKITDOWN_LLM_* unset produces no OCR — there is no engine to call. The plugin needs both the build arg and the runtime LLM config to function. - Size-table note: reworded from "pulls PyMuPDF" to "adds the markitdown-ocr plugin, including its PyMuPDF rendering dependency." - Component table OCR row: "the LLM vision model is the OCR engine, PyMuPDF only renders pages." - Dockerfile comment: same correction inside the code block. - Build-time only section: state explicitly that the plugin needs BOTH the build arg and runtime MARKITDOWN_LLM_*, and that standalone image captioning works via MARKITDOWN_LLM_* alone (no plugin needed). - Plugin probe: import markitdown_ocr, not pymupdf — PyMuPDF is a transitive rendering dep and is the wrong thing to test for plugin presence. Verified the probe against an image built without the plugin: the import traceback is the expected "not baked in" signal.

    @lqdflying lqdflying committed Aug 7, 2026
    abf33c7
  • 📝 docs(markitdown): reframe OCR/picture handling as optional, not a gap The page framed scanned-PDF / picture OCR as a "caveat" and a "gap" of alternative images, which reads as a deficiency. It is an optional feature: off by default on every recipe (Debian ARG default, Compose args default), and the only input class any default build does not handle. Deployments that never ingest scanned or picture-only input — the common case — can ignore it entirely and the sidecar is complete as built. - Reframe the size-table paragraph: the OCR plugin is "an optional feature, not something any default build ships," with a forward link instead of warning about a shared gap. - Rename "What's not in alternative images (and the default Debian build)" to "Alternative images (Chainguard Wolfi, multi-stage, prebuilt, CVE-pinned)". Drop the caveat/gap language; keep the component-presence table but reword the OCR row as "optional — off by default on every recipe" and mark the runtime opt-in rows (image captioning, Azure OCR) accordingly. - Rename "Scanned documents" to "OCR for scanned documents and pictures" (matches the two intro link anchors) and lead with "this is an optional capability: if your deployment never ingests scanned or picture-only input, you can ignore this section entirely and the sidecar is complete as built." - Reword "Build-time only" to consistent optional framing.

    @lqdflying lqdflying committed Aug 7, 2026
    c104c71
  • 📝 docs(markitdown): correct OCR-plugin attribution — it is opt-in everywhere The previous round implied the OCR plugin (markitdown-ocr / PyMuPDF) ships in the documented Debian build but is absent from alternative recipes. The Dockerfile ARG default and the Compose args value are both INSTALL_OCR_PLUGIN=false, so the wiki's own `docker compose up -d --build` omits the plugin too. A default-args alternative image (e.g. img.aksg.net/markitdown/markitdown:0.1.7) is missing nothing the default Debian build has — only an explicit INSTALL_OCR_PLUGIN=true rebuild adds the plugin on either side. - Fix the size table: ~1.07 GB is the default-args Debian build, the INSTALL_OCR_PLUGIN=true variant is ~80 MB heavier (~1.15 GB), and state explicitly that the plugin is off by default in both the ARG and the Compose. - Reword "What's not in alternative images" to "What's not in alternative images (and the default Debian build)" so the gap is correctly attributed to the opt-in plugin across all recipes, not to the choice of base image. Same recovery paths (AZURE_DOC_INTEL_ENDPOINT, or INSTALL_OCR_PLUGIN=true rebuild).

    @lqdflying lqdflying committed Aug 7, 2026
    e5897db
  • 📝 docs(markitdown): cover alternative recipes and the OCR-plugin caveat The page documented one Debian build and one 1.07 GB size, so readers using a prebuilt / Chainguard-Wolfi / multi-stage image (e.g. img.aksg.net/markitdown/markitdown:0.1.7, 732 MB, 0 CVE) had no guidance for what to expect and no explanation for the size gap. Recipes that pin deps to patched versions for CVE hygiene were also left implicit. - Replace the single-row size table with a range across recipes, and a sentence attributing the gap to base image and INSTALL_OCR_PLUGIN. - Note on requirements.txt that the pins are for reproducibility, not correctness — the HTTP wire format is stable across these minor versions, so unpinning for CVE hygiene produces a working image. Verified against an image that resolved fastapi to 0.141.1, openai to 1.68.2: every markitdown[all] converter imports, multipart upload semantics are unchanged. - Add a "What's not in alternative images" subsection under Run a prebuilt image, listing what a Chainguard-Wolfi / multi-stage build leaves out: only the markitdown-ocr plugin (PyMuPDF). Native-text converters, audio, image captioning and Azure OCR are all present. Scanned-PDF OCR is the sole gap, with two recovery paths (AZURE_DOC_INTEL_ENDPOINT, or rebuild with INSTALL_OCR_PLUGIN=true) and a one-line probe for the plugin.

    @lqdflying lqdflying committed Aug 7, 2026
    6111cea
  • 📝 docs(markitdown): split mandatory from optional, add prebuilt-image path Readers with a built image (e.g. img.aksg.net/markitdown/markitdown:0.1.7) had to translate the build-path Compose to remove `build:` themselves, and the env table did not separate the truly-required vars (an API key when the port is exposed past loopback) from overrides. Mirror ChatHub's component-scoped env convention: the sidecar's vars go in markitdown.env loaded with env_file:, ChatHub's own MARKITDOWN_* vars stay in its existing .env next to its compose, so each component owns its env and the compose carries no secrets. - Add a Run a prebuilt image section with the env file template split into Mandatory / Non-mandatory / Optional feature groups, the prebuilt Compose, network topology, ChatHub-side wiring and verification steps. - Restructure Configure it into Mandatory (only MARKITDOWN_API_KEY, gated on network exposure), Conditional feature groups (set each fully or not at all), Non-mandatory (built-in defaults), Build-time only (INSTALL_OCR_PLUGIN is a Docker arg, not an env), and a dedicated ChatHub-side vars table covering MARKITDOWN_SERVICE_URL/API_KEY/ MAX_FILE_SIZE/TIMEOUT. No code, runtime or test change; build path and HTTP contract unchanged.

    @lqdflying lqdflying committed Aug 7, 2026
    ff8b0e8
  • 📝 docs(markitdown): harden the sidecar and complete the Compose pass-through Review fixes for the page's embedded files, applied here since the page is the sidecar's only home: - server.py no longer reads the whole upload into memory before checking MARKITDOWN_MAX_FILE_SIZE. A middleware rejects a declared-oversize body before the form parser spools it, and /convert reads the spooled file in 1 MiB pieces, refusing once the cap is passed — so the cap now actually bounds memory, and a body with a lying or absent Content-Length is caught too. - The bearer-token check uses secrets.compare_digest over bytes: constant-time, and immune to the TypeError the str form raises on non-ASCII input. - docker-compose.yml now passes through MARKITDOWN_LOG_LEVEL, MARKITDOWN_LLM_PROMPT and AZURE_CU_ANALYZER_ID, which the Configure-it table documents but the container never received; the log level also survives an empty-string value now. - The HTTP-contract note no longer claims every error falls back to the built-in loaders: a FILE_TYPE_CHUNKING_RULES entry that pins a format to markitdown alone surfaces its errors directly, and the sidecar's reason reaches the surfaced error only when the fallback also fails. Wire contract unchanged: same endpoints, fields and status codes. Verified by extracting the four blocks, building the image and driving it live: csv converts with auth (200); wrong/missing/non-ASCII token all 401; a 500 KB upload over a 100 KB cap 413s from the bounded read; a 2 MB upload 413s from the middleware before parsing; empty upload 400; unknown format 415. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

    @lqdflying lqdflying committed Aug 7, 2026
    b390408
  • 📝 docs(markitdown): add the sidecar as a supplementary page The sidecar's build files were removed from the main repository, where they were Python clutter that no CI workflow built and no ChatHub image shipped. Carry them here instead, so the sidecar stays rebuildable without a checkout. MarkItDown-Sidecar.md holds the Dockerfile, requirements.txt, server.py and docker-compose.yml verbatim, plus how to build, run and update it, the format table, the configuration reference, the OCR guidance and the security notes. Two additions the old in-repo README did not have: - An HTTP contract section. src/libs/markitdown/index.ts depends on the wire format, and nothing in the ChatHub repository tests the server side — the client's suite mocks fetch and the chunking suite mocks the client — so either side can change and every test still passes. Documented as frozen, next to the code it constrains. - A note that the format table is the authority for MARKITDOWN_EXTENSIONS in packages/utils/src/isChunkableFile.ts, which drives the upload picker. Also re-point Knowledge-Base-and-RAG.md at this page in place of the deleted docker/markitdown/README.md, including the compose command that no longer resolves, and add the page to the sidebar after Knowledge Base and RAG. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

    @lqdflying lqdflying committed Aug 6, 2026
    d3ae081
  • 📝 docs(knowledge): document MarkItDown document-to-Markdown conversion Describe the optional MarkItDown sidecar: how to run it, the formats it adds to the Knowledge Base (xlsx/xls, msg, ipynb, zip, rss/atom, images, audio), that it converts everything to Markdown before chunking, and that the built-in loaders stay as the fallback. Update the two troubleshooting entries that previously said spreadsheets and scans could never be ingested.

    @lqdflying lqdflying committed Aug 6, 2026
    8c9e421
  • 📝 docs(zhipu): note tool_stream 400 + search/JSON thinking behavior Model-Providers: tool_stream is never sent (gateway 400s); tool calls arrive as one chunk. Built-in web search and JSON mode no longer disable thinking, keeping the body byte-stable for prefix caching. Debug-and-Diagnostics: extend the custom-gateway intermittent-400 note to include tool_stream in the rejected-field list.

    @lqdflying lqdflying committed Aug 6, 2026
    7b597c2
  • 📝 docs(zhipu): add custom-gateway intermittent-400 troubleshooting note Document that LiteLLM -> vLLM GLM gateways can reject GLM-native fields intermittently (path- and backend-dependent), list the four wire shapes ChatHub sends instead, and point at DEBUG_ZHIPU_CHAT_COMPLETION=1 for payload capture when a gateway still 400s.

    @lqdflying lqdflying committed Aug 6, 2026
    c36cddb
  • 📝 docs(zhipu): restore GLM gear toggles with gateway-safe wire forms Supersedes 413f842. The three GLM gear toggles are back: Deep Thinking (on = field omitted, off = type:"disabled"), Reasoning Effort (skip maps to API `none`, not `minimal`), and Preserved Thinking (type-less thinking:{clear_thinking:false}). All forms verified against the official API defaults and LiteLLM -> vLLM gateways that reject type:"enabled"/"minimal".

    @lqdflying lqdflying committed Aug 6, 2026
    a042854
  • 📝 docs(zhipu): drop GLM thinking/reasoning toggles, note gateway 400 fix ChatHub no longer sends thinking/reasoning_effort/clear_thinking to GLM — thinking is on by default (behavior-identical) and some LiteLLM -> vLLM gateways reject the thinking object with HTTP 400. Update the GLM section: remove the Deep Thinking / Reasoning Effort / Preserved Thinking toggle docs and explain that no thinking params are sent and historical reasoning_content is always stripped.

    @lqdflying lqdflying committed Aug 6, 2026
    413f842
  • 📝 docs(zhipu): document DEBUG_ZHIPU_CACHE and GLM implicit-cache troubleshooting Add Zhipu (GLM) to the cache-switch tables and a troubleshooting note covering implicit prefix caching, the byte-stable prefix requirement (volatile placeholders skipped for zhipu), the 512-token minimum, and requestHash-based diagnosis.

    @lqdflying lqdflying committed Aug 6, 2026
    8d5ce92
  • 📝 docs(zhipu): restore Preserved Thinking on glm-4.7, soften forced-thinking wording - Model-Providers: glm-4.7 now exposes Preserved Thinking (clear_thinking is a documented GLM-4.5+ capability orthogonal to forced thinking). Soften "sending disabled is a no-op" to "Zhipu forces thinking on it" (docs say forced thinking, not that disabled is ignored). Note the K3 distinction: K3 forces both thinking and preserved reasoning; Zhipu leaves clear_thinking caller-controlled. - Model-Extension-Options: glm-4.7 ships zhipuPreservedThinking (no enableReasoning); UI shows the switch without requiring a reasoning toggle; service uses a dedicated zhipu-only branch. Fetched glm-4.7 ids get zhipuPreservedThinking only.

    @lqdflying lqdflying committed Aug 6, 2026
    45d8ba7
  • 📝 docs(zhipu): drop glm-4.7 reasoning toggle, correct maxOutput to API-ref limits - Model-Providers: glm-4.7 no longer ships an enableReasoning toggle (Zhipu forces thinking on it; sending disabled is a no-op — Moonshot K3 precedent). - Model-Providers: replace "65K default / 128K max" with the documented per-family maxOutput (128K for 5.2/5.1/5/5-turbo/4.7/4.6, 96K for 4.5, 128K for 5v-turbo) so the shipped maxOutput values match the API ref. - Model-Extension-Options: note glm-4.7 has no toggle; fetched glm-4.7 ids are excluded from the aiInfra inference for the same reason.

    @lqdflying lqdflying committed Aug 6, 2026
    ebe579f
  • 📝 docs(zhipu): correct Preserved Thinking polarity, web_search reachability, tool_stream gating Update the Zhipu wiki sections to match the runtime fix commit: - Rename zhipuClearThinking -> zhipuPreservedThinking (ON = preserve, thinking.clear_thinking: false). Default is now off, not on. - Document that built-in web_search is reachable on the 7 text models via settings.searchImpl: 'params'; glm-5v-turbo omits it (Vision request schema has no web_search tool). - Clarify tool_stream gating: glm-4.6 / glm-4.7 / glm-5 text models only; vision models and glm-4.5/earlier text models omit it. - Correct the mustDisableThinking claim: the GLM-5.2 thinking + web_search/JSON exclusion is NOT documented by Zhipu; it is an empirical guard pending canary verification. Affects Model-Providers.md (Zhipu section) and Model-Extension-Options.md (provider table + UX conventions).

    @lqdflying lqdflying committed Aug 5, 2026
    91f746d
  • 📝 docs(zhipu): document Zhipu provider and GLM-5.2 model gear Add Zhipu (智谱) section to Model-Providers covering ZHIPU_API_KEY, default China endpoint, international endpoint override, the 8 shipped GLM cards, and the GLM-5.2 thinking/web-search/JSON mutual exclusion. Add ZhipuOptions row to the Model-Extension-Options provider panels table and a UX-conventions bullet describing the reasoning_effort and Preserved Thinking gating.

    @lqdflying lqdflying committed Aug 5, 2026
    519df9c
  • 📝 docs(rag): explain mobile prompt recovery

    @lqdflying lqdflying committed Aug 5, 2026
    8ab1117
  • 📝 docs(rag): document context accounting and diagnostics

    @lqdflying lqdflying committed Aug 4, 2026
    3c92e78
  • 📝 docs(rag): explain document visibility and recovery

    @lqdflying lqdflying committed Aug 4, 2026
    a7edfe2
  • 📝 docs(rag): clarify provider and index constraints

    @lqdflying lqdflying committed Aug 4, 2026
    bfc64e6
  • 📝 docs(rag): document knowledge vector setup

    @lqdflying lqdflying committed Aug 4, 2026
    6520524
  • 📝 docs(image): explain cleanup age presets

    @lqdflying lqdflying committed Aug 4, 2026
    467abca
  • 📝 docs(image): explain artifacts and history cleanup

    @lqdflying lqdflying committed Aug 4, 2026
    a124e55
  • 📝 docs(image): document plain-text topic titles

    @lqdflying lqdflying committed Aug 4, 2026
    ad9dc44
  • 📝 docs(image): document mobile topic activation

    @lqdflying lqdflying committed Aug 3, 2026
    aefe467
  • 📝 docs(image): document mobile topic polling

    @lqdflying lqdflying committed Aug 3, 2026
    ce2df11
  • 📝 docs(picbed): document responsive pagination

    @lqdflying lqdflying committed Aug 3, 2026
    d392a35
  • 📝 docs(image): document queued generation feedback

    @lqdflying lqdflying committed Aug 3, 2026
    1662c74
  • docs: document server-only runtime

    @lqdflying lqdflying committed Aug 3, 2026
    db35fbc