z-parser (Node SDK)

Node client for the z-parser document-extraction service: bytes in, RAG-ready Markdown out. Scanned PDFs (SOTA OCR + vision escalation), Office, spreadsheets, images, charts, manuscripts, EPUB, e-mail, audio/video transcription.

Zero dependencies — Node ≥ 18 (built-in fetch).

npm install z-parser
# no service running yet? one container, one key:
docker run -d -p 4056:4056 -e MISTRAL_API_KEY=xxx yatchiyax/z-parser

import { ZParser } from "z-parser";

const zp = new ZParser("http://localhost:4056");   // or $Z_PARSER_URL
const doc = await zp.parse("rapport.pdf");         // path, or bytes + {filename}
console.log(doc.parser, doc.numChars);             // "mistral-ocr+figures(2)" 48213
console.log(doc.text);

const pdf = await zp.renderPdf("deck.pptx");                  // Office → viewable PDF
const figs = await zp.images("catalogue.pdf", { mode: "artwork" });

CLI: npx z-parser contract.pdf -o contract.md

Pick your provider from the client — Mistral, Ollama (100 % local), vLLM, Hugging Face or any OpenAI-compatible vision endpoint, per client or per call:

const zp = new ZParser(undefined, {
  visionProvider: "openai",
  visionBaseUrl: "http://host.docker.internal:11434/v1",  // Ollama, seen FROM the server
  visionModel: "llama3.2-vision",
  docVision: true,          // PDFs through local vision too → fully offline
});
await zp.parse("scan.pdf", { visionModel: "qwen2.5-vl" });  // per-call override wins

// Shorthand + quality levers (mirror the server's .env):
await new ZParser().parse("dossier.pdf", {
  visionProvider: "mistral",   // openai dialect on api.mistral.ai, server key applies
  ocrEscalate: true,           // weak OCR pages re-read by vision (manuscripts)
  describeFigures: true,       // embedded charts/diagrams described on their page
});

Safety contract: a caller-chosen visionBaseUrl never receives the server's own API keys — bring your own key (visionApiKey) or none. With no provider params, the server's configuration applies.

Errors are explicit: ZParserError carries the service's status (unsupported / error). Timeout defaults to 15 minutes (timeout option) — large OCR jobs are slow by nature.

The service itself (Docker, one container), its benchmark and the Python/Rust SDKs live in the main repository.