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.0rc2

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.0rc2
File Size Uploaded Provenance Actions
everalgo_parser-0.3.0rc2.tar.gz 696.4 kB Without provenance Details for everalgo_parser-0.3.0rc2.tar.gz

Built distribution (wheel)

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

Total release size: 730.7 kB

Release files / everalgo_parser-0.3.0rc2.tar.gz

Download URL everalgo_parser-0.3.0rc2.tar.gz
Size 696.4 kB
Tags Source
SHA-256 checksum
How to use checksums
47a39aee885917c0e7578fffbe8b07b43fdf6dab5d22cf3fcb3355fcfd29c6b7
BLAKE2b-256 checksum
How to use checksums
20fa3b1fed7c8be3d3e66dd02960ebcb45f59b9fac789920d6aa5fa8a70bc9b8
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.0rc2-py3-none-any.whl

Download URL everalgo_parser-0.3.0rc2-py3-none-any.whl
Size 34.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5143da560526c1259bbca10a79076db2080f38fac2346cc667e707c0d210f9ea
BLAKE2b-256 checksum
How to use checksums
b3dae95f5e8b637cc79c622f58924147afeda902809964b54f211a329e02ebdc
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.0rc2

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