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 viaasgiref.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 (theeveralgo-coreLLM contract has no free-text tier).ParsedContent.textis thattext. - 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.aparsefetches arbitrary HTTP(S) URIs.everalgo.utils.fetch_urirejects non-http(s) schemes (nofile://, nogopher://) but does not block private / link-local / loopback IPs (e.g.127.0.0.1,10.0.0.0/8,169.254.169.254cloud metadata, IPv6 ULA). If callers may pass attacker-controlled URLs, resolve the hostname first and reject private ranges before invokingaparse, or front the parser with an egress proxy that does the filtering. - Decompression-bomb cap is set at import time.
everalgo/parser/__init__.pypinsPIL.Image.MAX_IMAGE_PIXELS = 100_000_000(10000×10000) — Pillow will raiseDecompressionBombErrorabove that. Re-assign after import if your workload genuinely needs larger images. - Office conversion runs LibreOffice as a subprocess.
document._convert_to_pdf_via_sofficevalidates theextensionparameter (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 whencairosvgis consumed as an unmodified library through its public Python API (which is what the SVG path does); if you statically vendor or modifycairosvg, 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| everalgo_parser-0.3.0.tar.gz | 696.5 kB | Without provenance | Details for everalgo_parser-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| everalgo_parser-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for everalgo_parser-0.3.0-py3-none-any.whl |
Total release size: 730.8 kB
Release files / everalgo_parser-0.3.0.tar.gz
| Download URL | everalgo_parser-0.3.0.tar.gz |
|---|---|
| Size | 696.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cac8d920c171d94a410d0120330d7804942e9d79a8720389d99e16ed66137904
|
|
BLAKE2b-256 checksum How to use checksums |
8cd41d4b16786b865f158e962a802e00f3992fc31ad81ff86173f9cdbc8143a0
|
| 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.0-py3-none-any.whl
| Download URL | everalgo_parser-0.3.0-py3-none-any.whl |
|---|---|
| Size | 34.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0855618754e701f08ae8afb21abac359cb71d4233e681f0397df23caac076e3a
|
|
BLAKE2b-256 checksum How to use checksums |
133573f78957fd2e53ad3a58d7707605708796f43689ec6a31123f6e426141de
|
| 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.0
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.