everalgo-parser 0.2.1__tar.gz → 0.3.0rc2__tar.gz

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/.gitignore

@@ -58,5 +58,8 @@ local/
 .claude/
 benchmarks/claudecode
 
+# Subagent-driven-development scratch (ledgers, task briefs, review packages)
+.superpowers/
+
 # Git worktrees (isolated workspaces)
 .worktrees/

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/CHANGELOG.md

@@ -7,8 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- git-cliff-unreleased-start -->
 ## [Unreleased]
+
 <!-- git-cliff-unreleased-end -->
 
+## [0.3.0rc2] - 2026-10-13
+
+### Changed
+
+- Invalid caller input now raises `everalgo.utils.InvalidInputError` (a `ValueError` subclass, so existing handlers keep working) instead of a bare `ValueError`: a `RawFile` with neither content nor uri, with empty content, with an unsupported extension or modality, a uri that returns an empty body or a content type the parser cannot read. Each message names the field and what to set instead; a uri it quotes is cut to `scheme://host[:port]/path`, so a signed URL's query string, fragment and credentials never reach the message.
+- Requires `everalgo-core>=0.6.0rc2` (the floor was `0.6.0rc1`): the package imports `everalgo.utils.InvalidInputError`, which `0.6.0rc1` does not define.
+
+## [0.3.0rc1] - 2026-10-13
+
+### Changed
+
+- **BREAKING:** every LLM call follows the new `LLMClient` contract: it passes `response_format=_TextReply`, a strict pydantic model of one field, `{"text": "..."}`, reads the `str` `achat` returns and validates it with `everalgo.llm.parse_reply`. A reply that is not that object — plain text, a missing or extra key, a non-string `text` — raises `everalgo.llm.LLMOutputError` from the image, PDF, HTML, Office and audio parsers. Two algorithm-level fallbacks keep their behaviour and now also cover an invalid reply: a tall-image merge that fails or comes back empty joins the slices' OCR (`metadata["merge_fallback"] = "deterministic_join"`), and an inline email image whose OCR fails gets the `[image: <name>, OCR failed]` placeholder. A custom client passed as `llm` must accept the mandatory keyword and return the reply text. See `everalgo-core` for the contract.
+- **BREAKING:** every call sends a system message and a user message instead of one user message. The system message is the prompt's rules, unchanged, followed by a `<reply_format>` block asking for `{"text": "..."}` (shared by the English and Chinese sets, `prompts/_reply_format.py`); `PROMPT_FOR_PICTURE`, `PROMPT_FOR_MERGE`, `PROMPT_FOR_FILE`, `PROMPT_FOR_HTML` and `PROMPT_FOR_AUDIO` are now these system messages. The user message is the input alone: the image, PDF or audio part with no text beside it; for HTML the cleaned page in `<html_content>` (new `HTML_USER_PROMPT`, slot `{{html}}`) instead of after a `---` line; for the tall-image merge the OCR texts, each in a `<part number="N">`, in `<ocr_parts count="N">` (new `MERGE_USER_PROMPT`, slots `{{count}}` and `{{parts}}`) instead of `=== Part N ===` sections in `PROMPT_FOR_MERGE`'s removed `{{parts_text}}` slot.
+- **BREAKING:** `ParsedContent.metadata` no longer carries `model` or `finish_reason`: `achat` returns only the reply text, and the model actually served is the host's to record. The image, audio, PDF, HTML and Office results keep their other keys.
+- **BREAKING:** operators call `LLMClient.achat`, the new name of the protocol method; a custom client passed as `llm` must implement `achat` instead of `chat`. See `everalgo-core` for the contract.
+- The URL parser fetches through `everalgo.utils.fetch_uri`, which moved to `everalgo-core`; the `ValueError` for a scheme other than `http` / `https` now reads `fetch_uri: only http and https are supported, got scheme 'file'` instead of `fetch_uri: only http/https supported, got scheme='file'. file:// and other local-filesystem URIs are rejected by design (...)`, so match on the exception type, not the text.
+- `everalgo-parser` no longer declares `httpx` itself: it makes no HTTP call of its own any more, and `everalgo-core` declares `httpx>=0.27` for the fetch.
+
 ## [0.2.1] - 2026-06-15
 
 ### Changed
@@ -80,6 +99,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Optional `cairosvg >= 2.7.0` via `[svg]` extra.
 - System: LibreOffice (`soffice` on PATH) for Office document parsing.
 
-[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/everalgo-parser/v0.2.1...HEAD
+[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/everalgo-parser/v0.3.0rc2...HEAD
+[0.3.0rc2]: https://github.com/EverMind-AI/EverAlgo/compare/everalgo-parser/v0.3.0rc1...everalgo-parser/v0.3.0rc2
+[0.3.0rc1]: https://github.com/EverMind-AI/EverAlgo/compare/everalgo-parser/v0.2.1...everalgo-parser/v0.3.0rc1
 [0.2.1]: https://github.com/EverMind-AI/EverAlgo/compare/everalgo-parser/v0.2.0...everalgo-parser/v0.2.1
 [0.2.0]: https://github.com/EverMind-AI/EverAlgo/releases/tag/everalgo-parser/v0.2.0

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: everalgo-parser
-Version: 0.2.1
-Summary: EverAlgo parser: multimodal raw-file parsing (image / audio / document / video / url) into ParsedContent.
+Version: 0.3.0rc2
+Summary: EverAlgo parser: image, audio, document, and URL parsing into ParsedContent.
 Project-URL: Homepage, https://github.com/EverMind-AI/EverAlgo
 Project-URL: Repository, https://github.com/EverMind-AI/EverAlgo
 Project-URL: Issues, https://github.com/EverMind-AI/EverAlgo/issues
@@ -20,8 +20,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.12
 Requires-Dist: asgiref>=3.8.0
 Requires-Dist: beautifulsoup4>=4.12.0
-Requires-Dist: everalgo-core<2.0.0,>=0.2.0
-Requires-Dist: httpx>=0.27.0
+Requires-Dist: everalgo-core<2.0.0,>=0.6.0rc2
 Requires-Dist: pillow>=10.0.0
 Provides-Extra: svg
 Requires-Dist: cairosvg>=2.7.0; extra == 'svg'
@@ -29,25 +28,24 @@ Description-Content-Type: text/markdown
 
 # everalgo-parser
 
-Multimodal parsing — image / audio / document / video / url raw inputs into `ParsedContent`. Used by `everalgo-knowledge` for file ingestion and by EverOS step 1 for inline parsing.
+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](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
 
 ## Quick start
 
 ```python
-from everalgo.llm.config import LLMConfig
-from everalgo.llm.providers.openai_compat import OpenAICompatClient
+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(LLMConfig(
+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)
@@ -97,14 +95,15 @@ The parser detects `soffice` via `shutil.which("soffice")` and the canonical mac
 
 - `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](../../AGENTS.md#5-code-style)). Swap languages by re-binding the constant at startup.
-- The library is **stateless**: it never reads the filesystem and never owns business state. HTTP I/O (LLM calls, URL fetching) is explicitly allowed.
-- No retry / fallback / metrics inside operators — surface failures via `LLMError`, let the caller wrap.
+- 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.** `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.
+- **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.

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/README.md

@@ -1,24 +1,23 @@
 # everalgo-parser
 
-Multimodal parsing — image / audio / document / video / url raw inputs into `ParsedContent`. Used by `everalgo-knowledge` for file ingestion and by EverOS step 1 for inline parsing.
+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](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
 
 ## Quick start
 
 ```python
-from everalgo.llm.config import LLMConfig
-from everalgo.llm.providers.openai_compat import OpenAICompatClient
+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(LLMConfig(
+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)
@@ -68,14 +67,15 @@ The parser detects `soffice` via `shutil.which("soffice")` and the canonical mac
 
 - `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](../../AGENTS.md#5-code-style)). Swap languages by re-binding the constant at startup.
-- The library is **stateless**: it never reads the filesystem and never owns business state. HTTP I/O (LLM calls, URL fetching) is explicitly allowed.
-- No retry / fallback / metrics inside operators — surface failures via `LLMError`, let the caller wrap.
+- 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.** `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.
+- **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.

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/docs/architecture.md

@@ -12,7 +12,8 @@ GitHub 默认渲染下面的 Mermaid 图。
 packages/everalgo-parser/
 ├── src/everalgo/parser/
 │   ├── __init__.py        ← 顶层 facade:dispatch + re-export 公开类型
-│   ├── _utils.py          ← 私有助手:fetch_uri / decode_bytes / aspect-ratio / html-clean
+│   ├── _utils.py          ← 私有助手:aspect-ratio / html-clean
+│   ├── _replies.py        ← 回复模型 `_TextReply{text}` + 唯一 LLM 调用点 `_call_llm_for_text`
 │   ├── image.py           ← IMAGE modality 算子(含长图分块 + BMP/TIFF 转码 + SVG 栅格化)
 │   ├── audio.py           ← AUDIO modality 算子
 │   ├── document.py        ← PDF / HTML / EMAIL / Office(LibreOffice)四合一
@@ -20,8 +21,9 @@ packages/everalgo-parser/
 │   ├── video.py           ← stub,等 ADR
 │   └── prompts/
 │       ├── __init__.py
-│       ├── en/{image,audio,document}.py    ← PROMPT_FOR_{PICTURE,MERGE,AUDIO,FILE,HTML}
-│       └── zh/{image,audio,document}.py    ← 中文对偶
+│       ├── _reply_format.py                ← 所有 system prompt 末尾共用的 `<reply_format>` 块
+│       ├── en/{image,audio,document}.py    ← system:PROMPT_FOR_{PICTURE,MERGE,AUDIO,FILE,HTML};user:MERGE_USER_PROMPT / HTML_USER_PROMPT
+│       └── zh/{image,audio,document}.py    ← 中文对偶(同名常量、同样拆分)
 ├── tests/
 │   ├── fixtures/          ← 17 个真实 sample.* 文件
 │   └── parser/
@@ -31,6 +33,8 @@ packages/everalgo-parser/
 │       ├── test_e2e_all_formats.py
 │       ├── test_e2e_pdf_openrouter.py
 │       ├── test_image.py
+│       ├── test_prompt_rendering.py
+│       ├── test_prompt_split.py
 │       ├── test_public_api.py
 │       ├── test_url.py
 │       ├── test_utils.py
@@ -86,7 +90,7 @@ flowchart TD
 - `uri=http(s)://` + `content=b""` → 走 `url.aparse`(内部抓取 + 按 Content-Type 再分派)。
 - 已经有 `content`:**extension 优先**,extension 解析不到时**用 mime 兜底**(`get_modality_from_mime`)。这样 design.md §2.1 的 `RawFile(uri=..., mime="application/pdf")` 走 URL 抓取后能再走到 PDF handler。
 - 子模块内部派发用 extension(`_MIME_MAP[ext]` 查 mime)。当顶层用 mime 解出 modality 时,自动 `model_copy(extension=get_extension_from_mime(mime))` 给子模块。
-- `file://` 在 `_utils.fetch_uri` 里直接拒绝(AGENTS.md §1)。
+- `file://` 在 `everalgo.utils.fetch_uri` 里直接拒绝(AGENTS.md §1)。
 - `Modality.URL` 是顶层 dispatch 产生的"来源标签",不出现在 extension 派发表里。
 
 ---
@@ -149,7 +153,7 @@ graph LR
 | `text` | `str` | 提取后的主文本(Markdown / 纯文本) |
 | `modality` | `Modality` | 来源分类 |
 | `mime` | `str` | 源 MIME(无则空串) |
-| `metadata` | `dict[str, Any]` | 按模态填:`model` / `finish_reason` / `tall_image_parts` / `inline_image_ocr` / `og_tags` / `intermediate_pdf_bytes` 等 |
+| `metadata` | `dict[str, Any]` | 按模态填:`tall_image_parts` / `merge_fallback` / `inline_image_ocr` / `og_tags` / `intermediate_pdf_bytes` 等。不含 `model` / `finish_reason`:`achat` 只返回文本,实际服务的模型由宿主记录(core `docs/concepts/llm-contract.md` §6.4) |
 
 ### `Modality` 枚举(StrEnum,9 值)
 
@@ -163,6 +167,8 @@ IMAGE  PDF  AUDIO  DOCUMENT  HTML  EMAIL  URL  DIRECT  UNKNOWN
 
 ## 6. 各 modality 调用链
 
+所有 LLM 调用同一形态:system = 规则 + `<reply_format>`(要求回复 `{"text": "..."}`),user = 文件 part(图片 / PDF / 音频)或带标签的文本(`<html_content>` / `<ocr_parts>`);回复经 `parse_reply(_TextReply, ...)` 校验后取 `text`,坏回复抛 `LLMOutputError`。例外:长图 merge 与邮件内嵌图 OCR 失败(含坏回复)走算法层兜底(拼接 / 占位符),不抛。
+
 ### 6.1 IMAGE(`image.aparse`)
 
 ```mermaid
@@ -181,7 +187,7 @@ flowchart LR
   J --> K[per-part OCR<br/>N x LLM calls]
   K --> L{N > 1?}
   L -- no --> M[return part]
-  L -- yes --> N[LLM merge<br/>PROMPT_FOR_MERGE]
+  L -- yes --> N[LLM merge<br/>PROMPT_FOR_MERGE + ocr_parts<br/>失败 / 空 → 确定性拼接]
   I --> R[ParsedContent]
   M --> R
   N --> R
@@ -193,7 +199,7 @@ flowchart LR
 flowchart TD
   A[bytes + ext] --> M{Modality from ext}
   M -- PDF --> P[image_url part + PROMPT_FOR_FILE → 1 LLM call]
-  M -- HTML --> H[decode_bytes → clean_html_for_llm bs4 → text part + PROMPT_FOR_HTML → 1 LLM call]
+  M -- HTML --> H[decode_bytes → clean_html_for_llm bs4 → html_content + PROMPT_FOR_HTML → 1 LLM call]
   M -- EMAIL --> E[stdlib email parse → headers + body]
   E --> EI{inline images?}
   EI -- yes --> EOCR[per-image OCR via LLM<br/>PROMPT_FOR_PICTURE]

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "everalgo-parser"
-version = "0.2.1"
-description = "EverAlgo parser: multimodal raw-file parsing (image / audio / document / video / url) into ParsedContent."
+version = "0.3.0rc2"
+description = "EverAlgo parser: image, audio, document, and URL parsing into ParsedContent."
 requires-python = ">=3.12"
 license = "Apache-2.0"
 readme = "README.md"
@@ -20,13 +20,10 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-  "everalgo-core>=0.2.0,<2.0.0",
+  "everalgo-core>=0.6.0rc2,<2.0.0",
   "asgiref>=3.8.0",
   "pillow>=10.0.0",
   "beautifulsoup4>=4.12.0",
-  # The URL parser uses httpx directly for ``http``/``https`` fetches; declare
-  # explicitly rather than relying on the transitive pull-in via openai SDK.
-  "httpx>=0.27.0",
 ]
 
 [project.urls]

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/src/everalgo/parser/__init__.py

@@ -25,6 +25,7 @@ from everalgo.types import (
     get_modality,
     get_modality_from_mime,
 )
+from everalgo.utils import InvalidInputError
 
 if TYPE_CHECKING:
     from everalgo.llm import LLMClient
@@ -63,7 +64,7 @@ async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
        - ``AUDIO`` → ``audio.aparse``
        - ``PDF`` / ``DOCUMENT`` / ``HTML`` / ``EMAIL`` → ``document.aparse``
        - ``DIRECT`` → no LLM; bytes are UTF-8-decoded inline.
-       - Anything else → ``ValueError``.
+       - Anything else → ``InvalidInputError``.
 
     When dispatch resolves a modality via ``mime`` but the submodule
     internally requires ``extension`` (image / audio / document all do for
@@ -87,10 +88,9 @@ async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
         return await url.aparse(raw_file, llm=llm)
 
     if not raw_file.content:
-        raise ValueError(
-            "Cannot dispatch: RawFile has no content. "
-            "Provide either an http(s) uri (the URL parser fetches) or "
-            "hydrated bytes."
+        raise InvalidInputError(
+            "RawFile has neither content nor an http(s) uri, so there is nothing to parse: "
+            "pass the file bytes in content, or an http(s) uri for the URL parser to fetch"
         )
 
     # Resolve modality: extension wins; fall back to mime.
@@ -98,8 +98,9 @@ async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
     if modality is Modality.UNKNOWN and raw_file.mime:
         modality = get_modality_from_mime(raw_file.mime)
     if modality is Modality.UNKNOWN:
-        raise ValueError(
-            f"Cannot dispatch: extension={raw_file.extension!r} mime={raw_file.mime!r} do not map to a known Modality."
+        raise InvalidInputError(
+            f"RawFile extension={raw_file.extension!r} mime={raw_file.mime!r} map to no known modality: "
+            "set a supported extension or a matching mime before calling"
         )
 
     # Ensure ``extension`` is populated for downstream submodules that key
@@ -118,8 +119,9 @@ async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
             modality=Modality.DIRECT,
             mime=routed.mime,
         )
-    raise ValueError(
-        f"Unsupported modality {modality.value!r} (extension={raw_file.extension!r}, mime={raw_file.mime!r})"
+    raise InvalidInputError(
+        f"RawFile modality {modality.value!r} (extension={raw_file.extension!r}, mime={raw_file.mime!r}) "
+        "is not parseable: this parser handles image, audio, document and plain-text files only"
     )
 
 

everalgo_parser-0.3.0rc2/src/everalgo/parser/_replies.py

@@ -0,0 +1,51 @@
+"""The reply model every parser prompt asks for, and the one LLM callsite every parser call goes through.
+
+Each parser output is free text (an OCR, a transcription, a merged OCR text). The contract has no free-text tier, so
+every prompt asks for the ``{"text": "..."}`` object instead (``docs/concepts/llm-contract.md`` §6.1). One call, one
+validation, no retry: the host decides (§4, §5).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from everalgo.llm import LLMMessage, StrictOutputModel, parse_reply
+
+if TYPE_CHECKING:
+    from everalgo.llm import ContentPart, LLMClient
+
+
+class _TextReply(StrictOutputModel):
+    """The ``{"text": "..."}`` skeleton every parser prompt's ``<reply_format>`` shows."""
+
+    text: str
+
+
+async def _call_llm_for_text(
+    llm: LLMClient,
+    *,
+    system: str,
+    user: str | list[ContentPart],
+    operator: str,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+) -> str:
+    """Send the rules as the system message and the input as the user message; return the reply's ``text``.
+
+    Args:
+        llm: The client to call.
+        system: The prompt's rules, ending with its ``<reply_format>``.
+        user: The input: the tagged text, or the file's content parts.
+        operator: Names the call in a parse error, e.g. ``"parser pdf"``.
+        temperature: Passed through; None leaves it to the host.
+        max_tokens: Passed through; None leaves it to the host.
+
+    Returns:
+        The reply's ``text``, verbatim; empty when the model returned an empty string.
+
+    Raises:
+        LLMOutputError: If the reply is not a valid ``{"text": "..."}`` object.
+    """
+    messages = [LLMMessage(role="system", content=system), LLMMessage(role="user", content=user)]
+    reply = await llm.achat(messages, response_format=_TextReply, temperature=temperature, max_tokens=max_tokens)
+    return parse_reply(_TextReply, reply, operator=operator).text

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/src/everalgo/parser/_utils.py

@@ -1,101 +1,30 @@
 """Internal parser helpers.
 
-- ``decode_bytes`` — multi-encoding decoder for unknown-charset bytes.
 - ``check_aspect_ratio`` / ``split_image_with_overlap`` — long-image (tall
   screenshot) handling for the image parser.
 - ``clean_html_content`` — strict text extraction (drops all tags).
 - ``clean_html_for_llm`` — preserves structural tags inside ``<body>``,
   strips known-noise tags and useless attributes, returns HTML.
-- ``fetch_uri`` — HTTP(S) fetch for the URL parser. Adapted from an
-  upstream internal URL extractor reference implementation.
 """
 
 from __future__ import annotations
 
-import logging
-import math
-import re
-from io import BytesIO
-from urllib.parse import urlparse
-
-import httpx
-from bs4 import BeautifulSoup, Comment
-from PIL import Image
-
-logger = logging.getLogger(__name__)
-
 __all__ = [
     "check_aspect_ratio",
     "clean_html_content",
     "clean_html_for_llm",
-    "decode_bytes",
-    "fetch_uri",
     "split_image_with_overlap",
 ]
 
+import logging
+import math
+import re
+from io import BytesIO
 
-_DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; everalgo-parser/0.1; +https://evermind.ai)"
-
-
-async def fetch_uri(uri: str, *, timeout: float = 30.0) -> tuple[bytes, str]:
-    """Fetch ``http``/``https`` URI and return ``(content_bytes, content_type)``.
-
-    Adapted from an upstream internal URL extractor reference implementation;
-    rejects non-http(s) schemes per AGENTS.md §1 (no filesystem access).
-
-    Parameters
-    ----------
-    uri : str
-        Origin URI. Must be ``http://`` or ``https://``.
-    timeout : float, optional
-        Per-request timeout in seconds (default 30s).
-
-    Returns:
-    -------
-    tuple[bytes, str]
-        Response body and the upstream ``Content-Type`` (lower-cased,
-        param-stripped, e.g. ``text/html``). Empty string when the upstream
-        omits the header.
+from bs4 import BeautifulSoup, Comment
+from PIL import Image
 
-    Raises:
-    ------
-    ValueError
-        URI is missing or uses a non-http(s) scheme (``file:`` / ``data:``
-        / ...).
-    httpx.HTTPError
-        Network failure surfaces unchanged so callers can apply their own
-        retry / fallback policy (the library does not retry — see ADR-012).
-    """
-    if not uri:
-        raise ValueError("fetch_uri: empty uri")
-    parsed = urlparse(uri)
-    if parsed.scheme not in ("http", "https"):
-        raise ValueError(
-            f"fetch_uri: only http/https supported, got scheme={parsed.scheme!r}. "
-            f"file:// and other local-filesystem URIs are rejected by design "
-            f"(AGENTS.md §1: stateless library, no filesystem access)."
-        )
-
-    headers = {"User-Agent": _DEFAULT_USER_AGENT}
-    async with httpx.AsyncClient(timeout=timeout, follow_redirects=True, headers=headers) as client:
-        response = await client.get(uri)
-        response.raise_for_status()
-        # Strip the charset/boundary parameters: ``text/html; charset=utf-8`` → ``text/html``.
-        content_type = response.headers.get("content-type", "").split(";")[0].strip().lower()
-        logger.debug(
-            "fetched uri=%s status=%d bytes=%d type=%s", uri, response.status_code, len(response.content), content_type
-        )
-        return response.content, content_type
-
-
-def decode_bytes(content: bytes) -> str:
-    """Try several encodings before falling back to lossy UTF-8."""
-    for encoding in ("utf-8", "gbk", "gb2312", "latin-1"):
-        try:
-            return content.decode(encoding)
-        except (UnicodeDecodeError, LookupError):
-            continue
-    return content.decode("utf-8", errors="ignore")
+logger = logging.getLogger(__name__)
 
 
 def check_aspect_ratio(image_bytes: bytes, max_ratio: float = 10.0) -> tuple[bool, float]:

{everalgo_parser-0.2.1 → everalgo_parser-0.3.0rc2}/src/everalgo/parser/audio.py

@@ -1,7 +1,8 @@
 """Audio parser — ASR via multimodal LLM.
 
 Sends the audio bytes as a single ``image_url`` data URI (OpenRouter / Gemini accepts
-audio MIMEs through the same content-part shape) and the LLM transcribes.
+audio MIMEs through the same content-part shape) as the user message, the rules as
+the system message, and reads the transcription from the reply's ``text``.
 """
 
 from __future__ import annotations
@@ -11,11 +12,14 @@ from typing import TYPE_CHECKING
 
 from asgiref.sync import async_to_sync
 
-from everalgo.llm import ChatMessage, LLMClient, TextPart, image_url_part_from_bytes
+from everalgo.llm import image_url_part_from_bytes
+from everalgo.parser._replies import _call_llm_for_text
 from everalgo.parser.prompts.en import PROMPT_FOR_AUDIO
 from everalgo.types import Modality, ParsedContent
+from everalgo.utils import InvalidInputError
 
 if TYPE_CHECKING:
+    from everalgo.llm import LLMClient
     from everalgo.types import RawFile
 
 __all__ = ["aparse", "parse"]
@@ -36,35 +40,33 @@ _MIME_MAP: dict[str, str] = {
 
 
 async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
-    """Parse an audio ``RawFile`` into ``ParsedContent`` (transcription)."""
+    """Parse an audio ``RawFile`` into ``ParsedContent`` (transcription).
+
+    Raises:
+        InvalidInputError: If ``raw_file`` has no content or an unsupported extension.
+        LLMOutputError: If the reply is not a valid ``{"text": "..."}`` object.
+    """
     if not raw_file.content:
-        raise ValueError("RawFile.content is empty; cannot parse audio")
+        raise InvalidInputError(
+            "RawFile.content is empty, there is nothing to transcribe: pass the audio bytes in content"
+        )
 
     extension = raw_file.extension.lower().lstrip(".")
     mime = _MIME_MAP.get(extension)
     if mime is None:
-        raise ValueError(
-            f"audio.aparse: unsupported audio extension {raw_file.extension!r}. Supported: {sorted(_MIME_MAP)}"
+        raise InvalidInputError(
+            f"RawFile.extension {raw_file.extension!r} is not a supported audio extension: "
+            f"set it to one of {sorted(_MIME_MAP)}"
         )
 
-    message = ChatMessage(
-        role="user",
-        content=[
-            TextPart(text=PROMPT_FOR_AUDIO),
-            image_url_part_from_bytes(raw_file.content, mime),
-        ],
-    )
     logger.debug("parsing audio extension=%s bytes=%d", extension, len(raw_file.content))
-    response = await llm.chat([message])
-    return ParsedContent(
-        text=response.content,
-        modality=Modality.AUDIO,
-        mime=raw_file.mime or mime,
-        metadata={
-            "model": response.model,
-            "finish_reason": response.finish_reason,
-        },
+    text = await _call_llm_for_text(
+        llm,
+        system=PROMPT_FOR_AUDIO,
+        user=[image_url_part_from_bytes(raw_file.content, mime)],
+        operator="parser audio",
     )
+    return ParsedContent(text=text, modality=Modality.AUDIO, mime=raw_file.mime or mime)
 
 
 parse = async_to_sync(aparse)