everalgo-parser 0.1.0__tar.gz

everalgo_parser-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage / cache
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+
+# Project local artifacts (placed under local/ per project convention)
+local/
+
+# Claude Code session-local state (scheduled tasks, agent caches, locks)
+.claude/

everalgo_parser-0.1.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog — everalgo-parser
+
+All notable changes to this distribution will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Entries are generated by [git-cliff](https://git-cliff.org/) from Conventional
+Commit messages on `main`. See the repository root [`README.md` § Cutting a release](../../README.md#cutting-a-release)
+for the full workflow.
+
+<!-- git-cliff-unreleased-start -->
+## [Unreleased]
+
+### Added
+
+- **PDF parser** — single multimodal LLM call, mirrors
+  `evermemos-multimodal/src/parser/pdf/gemini_parser.py`.
+- **Image parser** — single LLM call for normal-ratio images; tall
+  screenshots (height/width > 10) are split into overlapping vertical
+  slices, OCR'd per slice, and merged with a second LLM call using
+  `PROMPT_FOR_MERGE`. BMP / TIFF are transcoded to PNG via Pillow before
+  upload (Gemini does not accept those MIMEs natively); SVG is rasterised
+  via the optional `cairosvg` extra (`everalgo-parser[svg]`).
+- **Audio parser** — ASR via multimodal LLM; covers
+  mp3 / wav / m4a / amr / aiff / aac / ogg / flac.
+- **HTML / `htm` handler** (in `document.aparse`) — bs4 noise cleanup
+  (`clean_html_for_llm` drops `<script>` / `<style>` / `<nav>` / `<footer>`
+  / `<iframe>` and bloat attributes) then LLM extraction.
+- **Email (`.eml`) handler** (in `document.aparse`) — stdlib `email`
+  parsing for headers + body, with inline-image OCR via `cid:` placeholder
+  substitution.
+- **Office document handler** (in `document.aparse`) — covers docx / xlsx
+  / pptx / doc / xls / ppt / pages / key / numbers / odt / ods / odp /
+  rtf via a LibreOffice subprocess (`soffice --convert-to pdf` → reuse PDF
+  path). `soffice` must be installed on the host (see README).
+- **URL parser** — fetches `http`/`https` URIs via httpx, then **dispatches
+  by the fetched `Content-Type`**: `application/pdf` → PDF handler,
+  `image/*` → image handler, `audio/*` → audio handler, `text/html` (or
+  unknown) → HTML handler with Open Graph / Twitter Card / `<meta>` tag
+  extraction into `ParsedContent.metadata`. `file://` and other local-
+  filesystem URIs are rejected (AGENTS.md §1). Inner modality recorded in
+  `metadata["inner_modality"]`. Metadata-extractor schema lifted from
+  `evermemos-opensource/src/common_utils/url_extractor.py`.
+- **MIME-aware top-level dispatch** — `parser.aparse` now falls back to
+  `mime` when `extension` is missing or `UNKNOWN`, so the canonical
+  `RawFile(uri=..., mime="application/pdf")` example actually routes to
+  the PDF handler. Added `Modality` helpers in `everalgo-core/types/
+  modality.py`: `MIME_TO_MODALITY` / `MIME_TO_EXTENSION` /
+  `get_modality_from_mime(mime)` / `get_extension_from_mime(mime)`.
+- **Chinese prompts** at `prompts/zh/{image,audio,document}.py`
+  (`PROMPT_FOR_PICTURE` / `PROMPT_FOR_MERGE` / `PROMPT_FOR_FILE` /
+  `PROMPT_FOR_HTML` / `PROMPT_FOR_AUDIO`), mirroring the English set.
+- **Optional `[svg]` extra** pulling in `cairosvg` for SVG rasterisation.
+- **Re-exports** of `ParsedContent` / `Modality` / `RawFile` from
+  `everalgo.parser` so callers can `from everalgo.parser import aparse,
+  RawFile, ParsedContent`.
+
+### Notes
+
+- `video` submodule remains a stub — upstream evermemos-multimodal has no
+  video implementation to port; backend selection pending an ADR.
+- The parser layer deliberately omits retry / fallback / multi-key
+  rotation / Prometheus metrics. Those are deployment concerns
+  (ADR-012); algorithm-layer operators surface failures via `LLMError`
+  and callers wrap as needed.
+
+### Dependencies
+
+- `pillow >= 10.0.0` — image transcode + aspect-ratio check.
+- `beautifulsoup4 >= 4.12.0` — HTML cleanup + OG metadata extraction.
+- `asgiref >= 3.8.0` — sync bridge (ADR-010).
+- Optional `cairosvg >= 2.7.0` via `[svg]` extra.
+- System: LibreOffice (`soffice` on PATH) for Office document parsing.
+
+<!-- git-cliff-unreleased-end -->

everalgo_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EverMind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everalgo_parser-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: everalgo-parser
+Version: 0.1.0
+Summary: EverAlgo parser: multimodal raw-file parsing (image / audio / document / video / url) 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
+Project-URL: Documentation, https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-parser
+Project-URL: Changelog, https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-parser/CHANGELOG.md
+Author: EverMind
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: asgiref>=3.8.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: everalgo-core<2.0.0,>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7.0; extra == 'svg'
+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 evermem 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
+import everalgo
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.providers.openai_compat import OpenAICompatClient
+from everalgo.parser import aparse, RawFile
+
+# Configure an LLM once (process-wide). The parser uses OpenAI-compatible
+# clients; OpenRouter is the reference deployment (Gemini multimodal via
+# OpenRouter passthrough).
+everalgo.configure(OpenAICompatClient(LLMConfig(
+    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"))
+print(parsed.text)
+
+# URL-in: parser fetches over HTTP, then delegates to the HTML handler.
+parsed = await aparse(RawFile(uri="https://example.com/article"))
+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
+
+```bash
+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:
+
+```bash
+# 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](../../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.
+
+## Reference
+
+- Architecture (definitive): [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md)
+- Schema source for PDF / image / audio / document / html / email: `evermemos-multimodal` (tag `prod-20260306-0331-v1`).
+- Schema source for URL metadata extraction: `evermemos-opensource/src/common_utils/url_extractor.py`.

everalgo_parser-0.1.0/README.md

@@ -0,0 +1,79 @@
+# everalgo-parser
+
+Multimodal parsing — image / audio / document / video / url raw inputs into `ParsedContent`. Used by `everalgo-knowledge` for file ingestion and by evermem 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
+import everalgo
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.providers.openai_compat import OpenAICompatClient
+from everalgo.parser import aparse, RawFile
+
+# Configure an LLM once (process-wide). The parser uses OpenAI-compatible
+# clients; OpenRouter is the reference deployment (Gemini multimodal via
+# OpenRouter passthrough).
+everalgo.configure(OpenAICompatClient(LLMConfig(
+    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"))
+print(parsed.text)
+
+# URL-in: parser fetches over HTTP, then delegates to the HTML handler.
+parsed = await aparse(RawFile(uri="https://example.com/article"))
+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
+
+```bash
+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:
+
+```bash
+# 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](../../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.
+
+## Reference
+
+- Architecture (definitive): [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md)
+- Schema source for PDF / image / audio / document / html / email: `evermemos-multimodal` (tag `prod-20260306-0331-v1`).
+- Schema source for URL metadata extraction: `evermemos-opensource/src/common_utils/url_extractor.py`.

everalgo_parser-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everalgo-parser"
+version = "0.1.0"
+description = "EverAlgo parser: multimodal raw-file parsing (image / audio / document / video / url) into ParsedContent."
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "EverMind" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "everalgo-core>=0.1.0,<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]
+Homepage = "https://github.com/EverMind-AI/EverAlgo"
+Repository = "https://github.com/EverMind-AI/EverAlgo"
+Issues = "https://github.com/EverMind-AI/EverAlgo/issues"
+Documentation = "https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-parser"
+Changelog = "https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-parser/CHANGELOG.md"
+
+[project.optional-dependencies]
+# SVG rasterisation; pulled in only when callers parse .svg files.
+svg = ["cairosvg>=2.7.0"]
+# Office document conversion (docx / xlsx / pptx / ...) requires LibreOffice
+# (``soffice``) as a SYSTEM dependency, not a pip package. Install via:
+#   Linux: apt install libreoffice
+#   macOS: brew install --cask libreoffice
+# There is no pip extra for it — the parser shells out at runtime.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everalgo"]

everalgo_parser-0.1.0/src/everalgo/parser/__init__.py

@@ -0,0 +1,148 @@
+"""Multimodal parser — top-level dispatch by modality.
+
+Public surface (re-exports for ergonomic ``from everalgo.parser import ...``):
+
+- Functions: ``aparse`` / ``parse`` — dispatch entry points.
+- Submodules: ``image`` / ``audio`` / ``document`` / ``url`` / ``video``.
+- Types: ``ParsedContent`` / ``Modality`` / ``RawFile`` (re-exported from
+  ``everalgo.types`` for one-stop import).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+from asgiref.sync import async_to_sync
+
+from everalgo.parser import audio, document, image, url, video
+from everalgo.types import (
+    Modality,
+    ParsedContent,
+    RawFile,
+    get_extension_from_mime,
+    get_modality,
+    get_modality_from_mime,
+)
+
+if TYPE_CHECKING:
+    from everalgo.llm import LLMClient
+
+__all__ = [
+    "Modality",
+    "ParsedContent",
+    "RawFile",
+    "aparse",
+    "audio",
+    "document",
+    "image",
+    "parse",
+    "url",
+    "video",
+]
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+async def aparse(raw_file: RawFile, *, llm: LLMClient) -> ParsedContent:
+    """Top-level dispatch: classify the input and route to a submodule.
+
+    Dispatch precedence:
+
+    1. ``content`` empty + ``uri`` is ``http``/``https`` → ``url.aparse``
+       (the URL parser fetches and re-dispatches by the response Content-Type).
+    2. ``content`` non-empty → resolve a ``Modality`` from
+       ``extension`` first, falling back to ``mime`` when extension is
+       missing or ``UNKNOWN``.
+    3. Submodule routing by resolved ``Modality``:
+       - ``IMAGE`` → ``image.aparse``
+       - ``AUDIO`` → ``audio.aparse``
+       - ``PDF`` / ``DOCUMENT`` / ``HTML`` / ``EMAIL`` → ``document.aparse``
+       - ``DIRECT`` → no LLM; bytes are UTF-8-decoded inline.
+       - Anything else → ``ValueError``.
+
+    When dispatch resolves a modality via ``mime`` but the submodule
+    internally requires ``extension`` (image / audio / document all do for
+    their ``_MIME_MAP`` lookups), this function fills ``extension`` in
+    from the canonical extension table before forwarding.
+
+    Parameters
+    ----------
+    raw_file : RawFile
+        Hydrated ``content`` or ``uri`` (at least one is required).
+    llm : LLMClient
+        Per-call LLM client. Required for all LLM-backed modalities (IMAGE, AUDIO, PDF, etc.).
+
+    Returns:
+    -------
+    ParsedContent
+        Normalized parser output.
+    """
+    # URL path: only when caller did not pre-hydrate content.
+    if not raw_file.content and raw_file.uri and _is_http_uri(raw_file.uri):
+        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."
+        )
+
+    # Resolve modality: extension wins; fall back to mime.
+    modality = get_modality(raw_file.extension) if raw_file.extension else Modality.UNKNOWN
+    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."
+        )
+
+    # Ensure ``extension`` is populated for downstream submodules that key
+    # their internal MIME tables off it (image / audio / document do).
+    routed = _ensure_extension(raw_file)
+
+    if modality is Modality.IMAGE:
+        return await image.aparse(routed, llm=llm)
+    if modality is Modality.AUDIO:
+        return await audio.aparse(routed, llm=llm)
+    if modality in (Modality.PDF, Modality.DOCUMENT, Modality.HTML, Modality.EMAIL):
+        return await document.aparse(routed, llm=llm)
+    if modality is Modality.DIRECT:
+        return ParsedContent(
+            text=routed.content.decode("utf-8", errors="replace"),
+            modality=Modality.DIRECT,
+            mime=routed.mime,
+        )
+    raise ValueError(
+        f"Unsupported modality {modality.value!r} (extension={raw_file.extension!r}, mime={raw_file.mime!r})"
+    )
+
+
+parse = async_to_sync(aparse)
+"""Sync bridge for non-event-loop callers. See ``document.parse`` for details."""
+
+
+# ---- helpers ----
+
+
+def _is_http_uri(uri: str) -> bool:
+    """Return True for ``http`` / ``https`` schemes only."""
+    return urlparse(uri).scheme in ("http", "https")
+
+
+def _ensure_extension(raw_file: RawFile) -> RawFile:
+    """Return a ``RawFile`` whose ``extension`` is populated.
+
+    If ``extension`` is missing but ``mime`` resolves via ``MIME_TO_EXTENSION``,
+    we hand the submodule a copy carrying the canonical extension. Returns
+    the original when ``extension`` is already set or no mime fallback exists.
+    """
+    if raw_file.extension:
+        return raw_file
+    derived = get_extension_from_mime(raw_file.mime)
+    if not derived:
+        return raw_file
+    return raw_file.model_copy(update={"extension": derived})