aksharamd

AksharaMD is a Python CLI and library for assessing how well a document parser converted a source file into Markdown suitable for LLM ingestion. Rather than advertising an average accuracy figure, it produces a per-document readiness verdict for the specific parser output you supply. The core flow takes two inputs: the original source document (for example a PDF or DOCX) and the Markdown your parser produced from it. It then returns an AI Readiness Score from 0 to 100 with quality bands (HIGH at 85 or above, OK at 70, RISKY at 50, POOR below 50), per-block extraction confidence tags (EXTRACTED, INFERRED, AMBIGUOUS), named warning codes such as OCR_REQUIRED, LOW_TEXT_DENSITY, GLYPH_ARTIFACTS, REPEATED_CONTENT, W_MULTICOLUMN_ORDER, W_TABLE_MISSING, W_ENCODING_ARTIFACTS and OCR_HALLUCINATION, and an optional source-grounded assessment gate that checks whether declared literals (dates, IDs, currency amounts, named entities) survive into the Markdown, yielding an ACCEPT or REJECT verdict. The project is explicitly parser-agnostic and lists MarkItDown, Docling, marker, MinerU, LlamaParse and PyMuPDF4LLM as parsers whose output can be graded, along with any in-house parser that emits Markdown. A bundled reference parser is also included for teams without a preferred parser, reachable through the compile subcommand; the README stresses that this reference parser is a fallback convenience rather than the product itself. The README is unusually candid about limits. It states that readiness is an uncalibrated heuristic, not a probability of correctness, and that a high score only means few modeled penalties were applied. It explicitly disclaims guarantees about retrieval accuracy, final answer correctness, citation correctness, optimal chunking for a given embedding model, and embedding dilution. Historical benchmark figures (output-token comparisons, noise reduction, throughput versus MarkItDown and Docling) are attributed to the bundled reference parser at version 0.3.3, not to the readiness score, and the README notes they are not automatically transferable to later releases. Processing runs locally. The base install makes no network calls for local files; network access occurs only for remote sources such as HTTP/HTTPS URLs or S3, or when optional ML backends download model weights on first use. Documents are not sent to an AksharaMD-operated service. Installation is via pip and requires Python 3.11 or later. The base install covers native PDFs, DOCX, XLSX, PPTX, HTML, EPUB, email, archives, images and code across 40+ document categories and 118 registered extensions. Optional extras add OCR (Tesseract), vision-based table reconstruction (Marker), math extraction (pix2tex), audio transcription (Whisper) and S3 input. A full extra installs everything, at the cost of roughly 5-6 GB of model weights on first run. Without the relevant extras, scanned pages emit an OCR_REQUIRED warning and a low readiness score instead of silently producing poor output. The CLI includes subcommands for compile, assess, validate, benchmark, stats, show-manifest, corpus, mcp-config and formats. The assess command is the primary grading flow; compile runs the bundled parser end-to-end and writes document.md, document.json, manifest.json, validation.json and chunk files. A --min-readiness-score option allows use as a CI/CD ingestion gate, and --json produces machine-readable output. The corpus command compiles a directory into token-budget-bounded chunks with near-duplicate detection. The Python API exposes a Compiler class with compile_to_string, compile, compile_to_multimodal (returning an Anthropic-compatible content array with inline base64 images) and a stream method that yields blocks incrementally for feeding a RAG index or vector store. A compilation context object exposes manifest fields such as token counts, token reduction percentage, readiness score, elapsed time, table and chunk counts, plus validation errors and warnings. An MCP server is included for MCP-compatible hosts such as Claude Desktop and Cursor, configured through the mcp-config subcommand. The project is licensed under PolyForm Noncommercial.