📝 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.
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.
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).
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.
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.
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>
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>
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.
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.
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.
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".
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.
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.
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.
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.
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).
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.
519df9c
📝 docs(rag): explain mobile prompt recovery
8ab1117
📝 docs(rag): document context accounting and diagnostics
3c92e78
📝 docs(rag): explain document visibility and recovery
a7edfe2
📝 docs(rag): clarify provider and index constraints
bfc64e6
📝 docs(rag): document knowledge vector setup
6520524
📝 docs(image): explain cleanup age presets
467abca
📝 docs(image): explain artifacts and history cleanup
a124e55
📝 docs(image): document plain-text topic titles
ad9dc44
📝 docs(image): document mobile topic activation
aefe467
📝 docs(image): document mobile topic polling
ce2df11
📝 docs(picbed): document responsive pagination
d392a35
📝 docs(image): document queued generation feedback
1662c74
docs: document server-only runtime
db35fbc