Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

everalgo-parser

Multimodal parsing — image / audio / document / URL raw inputs into ParsedContent; video is deferred. Used by everalgo-knowledge for file ingestion and by EverOS step 1 for inline parsing.

See the umbrella project: EverAlgo monorepo and the architecture document at docs/concepts/architecture.md.

Quick start

from everalgo.llm.openai_compat import OpenAICompatClient
from everalgo.parser import aparse, RawFile

# Create an LLM client per call (or share one instance). The parser uses
# OpenAI-compatible clients; OpenRouter is the reference deployment
# (Gemini multimodal via OpenRouter passthrough).
client = OpenAICompatClient(
    model="google/gemini-3-flash-preview",
    api_key="sk-or-v1-...",
    base_url="https://openrouter.ai/api/v1",
)

# Bytes-in: caller already hydrated the file.
parsed = await aparse(RawFile(content=pdf_bytes, extension="pdf"), llm=client)
print(parsed.text)

# URL-in: parser fetches over HTTP, then delegates to the HTML handler.
parsed = await aparse(RawFile(uri="https://example.com/article"), llm=client)
print(parsed.metadata["title"], parsed.text[:500])

Supported formats

Modality Extensions Backend
PDF pdf Multimodal LLM (single call, full doc)
IMAGE png / jpg / jpeg / webp / bmp / tiff / tif / svg Multimodal LLM; BMP/TIFF transcoded to PNG via Pillow; SVG rasterised via cairosvg; tall screenshots split + merged
AUDIO mp3 / wav / m4a / amr / aiff / aac / ogg / flac Multimodal LLM ASR
HTML html / htm bs4 cleanup → LLM extraction
EMAIL eml stdlib email + inline-image OCR via the LLM
DOCUMENT docx / pptx / xlsx / doc / ppt / xls / pages / key / numbers / odt / ods / odp / rtf LibreOffice soffice --convert-to pdf → reuse PDF path
URL (any http/https URI) httpx fetch → HTML handler
DIRECT txt / md / csv / tsv / vtt UTF-8 decode, no LLM
VIDEO — Deferred (no upstream implementation; ADR pending)

Installation

pip install everalgo-parser            # core: pdf / image / audio / html / eml / direct / url
pip install 'everalgo-parser[svg]'     # adds SVG support (cairosvg)

System dependency for Office documents

Office document parsing (docx / xlsx / pptx / …) shells out to LibreOffice, which is a system package, not a pip wheel. Install before parsing Office files:

# Ubuntu / Debian
sudo apt-get install -y libreoffice

# macOS
brew install --cask libreoffice

The parser detects soffice via shutil.which("soffice") and the canonical macOS Applications path. Missing → RuntimeError with install instructions when an Office file is parsed; non-Office paths are unaffected.

Conventions

  • aparse(...) is async; parse(...) is the sync bridge via asgiref.async_to_sync.
  • Prompts live as module-level string constants under prompts/{en,zh}/<operator>.py (AGENTS.md §5). Swap languages by re-binding the constant at startup.
  • The parser owns no durable state and never reads caller-selected local paths. URL parsing performs HTTP(S) I/O, and Office conversion writes files only inside a parser-managed temporary directory that is removed before the call returns.
  • Every LLM call sends the prompt's rules as the system message and the input — the file part, or the cleaned HTML / the OCR texts in XML-style tags — as the user message, and asks for one {"text": "..."} object (the everalgo-core LLM contract has no free-text tier). ParsedContent.text is that text.
  • No retry / metrics inside operators — the client's errors propagate unchanged and an invalid reply raises everalgo.llm.LLMOutputError; let the caller wrap. The only fallbacks are algorithmic: a failed tall-image merge joins the slices' OCR, and a failed inline-image OCR leaves a placeholder in the email.

Security notes for callers

everalgo-parser is a stateless library; production safety properties belong to the calling service. The points below are easy to miss and worth wiring into your integration:

  • SSRF — url.aparse fetches arbitrary HTTP(S) URIs. everalgo.utils.fetch_uri rejects non-http(s) schemes (no file://, no gopher://) but does not block private / link-local / loopback IPs (e.g. 127.0.0.1, 10.0.0.0/8, 169.254.169.254 cloud metadata, IPv6 ULA). If callers may pass attacker-controlled URLs, resolve the hostname first and reject private ranges before invoking aparse, or front the parser with an egress proxy that does the filtering.
  • Decompression-bomb cap is set at import time. everalgo/parser/__init__.py pins PIL.Image.MAX_IMAGE_PIXELS = 100_000_000 (10000×10000) — Pillow will raise DecompressionBombError above that. Re-assign after import if your workload genuinely needs larger images.
  • Office conversion runs LibreOffice as a subprocess. document._convert_to_pdf_via_soffice validates the extension parameter (alphanumeric, ≤8 chars) before writing the temp file, but the LibreOffice attack surface itself is large. Run the host with a non-root user and treat untrusted office docs as you would any other complex binary input.
  • cairosvg (optional [svg] extra) is LGPL-3.0-or-later. EverAlgo itself is Apache-2.0. LGPLv3 is compatible with Apache-2.0 when cairosvg is consumed as an unmodified library through its public Python API (which is what the SVG path does); if you statically vendor or modify cairosvg, LGPLv3 §4 / §5 obligations apply to that derivative. Not installing the [svg] extra removes the dependency entirely.

Reference

  • Architecture (definitive): docs/concepts/architecture.md
  • Schema source for PDF / image / audio / document / html / email: upstream internal multimodal parser library (snapshot prod-20260306-0331-v1).
  • Schema source for URL metadata extraction: upstream internal URL extractor reference implementation.

Metadata

Release files for everalgo-parser 0.3.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for everalgo-parser 0.3.0rc1
File Size Uploaded Provenance Actions
everalgo_parser-0.3.0rc1.tar.gz 695.4 kB Without provenance Details for everalgo_parser-0.3.0rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for everalgo-parser 0.3.0rc1
File Interpreter ABI Platform Actions
everalgo_parser-0.3.0rc1-py3-none-any.whl Python 3 none any Details for everalgo_parser-0.3.0rc1-py3-none-any.whl

Total release size: 729.1 kB

Release files / everalgo_parser-0.3.0rc1.tar.gz

Download URL everalgo_parser-0.3.0rc1.tar.gz
Size 695.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0e2e02d1d1dd92df65599402d94fbb00e146680f5c2b1f7d331d1424ff72ae91
BLAKE2b-256 checksum
How to use checksums
a4bb867a4bb645fefe8bc248198100210dde216e91480bae62d46aa987521829
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.12

Release files / everalgo_parser-0.3.0rc1-py3-none-any.whl

Download URL everalgo_parser-0.3.0rc1-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07f434de0ad5f97f3abe3f4f46a48518965aa83ad4d5e2f3a85e7e75160b1f8a
BLAKE2b-256 checksum
How to use checksums
551a3acc39c2fb2911d93ae66ad22445fcb118cc0cc8d18feb7dd3b32f401922
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.12

Security for everalgo-parser 0.3.0rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page