quantized-lab 0.8.0__py3-none-any.whl

quantized/plugins/contract.py

@@ -0,0 +1,111 @@
+"""Plugin contract v1: the stable, versioned shape a quantized plugin declares.
+
+A plugin is a Python module (a drop-in ``.py`` file or an installed package
+exposing the ``quantized.plugins`` entry point) that defines a manifest and,
+optionally, any of three contribution lists. This module owns the *contract*
+(the manifest + its validation and the discovery-result record); the *loader*
+(:mod:`quantized.plugins.loader`) owns discovery and registration.
+
+Manifest — required::
+
+    QZ_PLUGIN = {"name": "My Plugin", "version": "1.2.0", "api_version": 1}
+
+Contributions — any subset, each a list of plain dicts (see docs/plugins.md):
+
+- ``PARSERS``    — ``{"extensions": [".ext"], "read": path -> DataStruct|dict,
+                      "sniff"?: bytes -> bool}``
+- ``FIT_MODELS`` — ``{"name": str, "params": [str, ...],
+                      "fn": (x, params) -> y, "guess"?: [float, ...]}``
+- ``STEPS``      — ``{"name": str, "fn": (DataStruct, params) -> DataStruct}``
+
+Pure ``plugins`` layer — no fastapi/pydantic imports (guarded by
+``test_repo_integrity``). Plugins can never reach ``quantized.routes``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "API_VERSION",
+    "InvalidManifest",
+    "PluginInfo",
+    "PluginManifest",
+    "validate_manifest",
+]
+
+# The contract version this quantized build speaks. A plugin declaring any other
+# ``api_version`` is skipped (logged) — never loaded against an incompatible host.
+API_VERSION = 1
+
+
+class InvalidManifest(ValueError):
+    """A module's ``QZ_PLUGIN`` manifest is missing or not v1-compatible."""
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """The validated ``QZ_PLUGIN`` metadata of one plugin."""
+
+    name: str
+    version: str
+    api_version: int
+
+
+@dataclass(frozen=True)
+class PluginInfo:
+    """What one discovered plugin is and what it contributed.
+
+    The record surfaced by ``qz plugin list`` and cached by the loader.
+    ``source`` is the stable identifier used for enable/disable (the module file
+    stem for a drop-in plugin, or the entry-point name for a packaged one); the
+    manifest ``name`` is human-facing and only known once the manifest validates.
+    """
+
+    source: str  # module stem (file plugin) | entry-point name — the identifier
+    origin: str  # "file" | "entry_point"
+    status: str  # "loaded" | "disabled" | "error"
+    name: str = ""  # manifest name (blank until the manifest validates)
+    version: str = ""
+    error: str = ""  # problem text: import/manifest failure, or rejected contributions
+    parsers: tuple[str, ...] = ()
+    fit_models: tuple[str, ...] = ()
+    steps: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "origin": self.origin,
+            "status": self.status,
+            "name": self.name,
+            "version": self.version,
+            "error": self.error,
+            "parsers": list(self.parsers),
+            "fit_models": list(self.fit_models),
+            "steps": list(self.steps),
+        }
+
+
+def validate_manifest(module: object) -> PluginManifest:
+    """Read and validate ``module.QZ_PLUGIN``.
+
+    Raises :class:`InvalidManifest` when the manifest is missing, malformed, or
+    declares an ``api_version`` this build does not speak. On success the
+    manifest is guaranteed to have a non-empty ``name`` and ``api_version`` equal
+    to :data:`API_VERSION`.
+    """
+    raw = getattr(module, "QZ_PLUGIN", None)
+    if not isinstance(raw, Mapping):
+        raise InvalidManifest("module defines no QZ_PLUGIN dict")
+    api = raw.get("api_version")
+    if api != API_VERSION:
+        raise InvalidManifest(
+            f"unsupported api_version {api!r} (this quantized speaks v{API_VERSION})"
+        )
+    name = raw.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise InvalidManifest("QZ_PLUGIN['name'] must be a non-empty string")
+    version = str(raw.get("version", "0"))
+    return PluginManifest(name=name.strip(), version=version, api_version=API_VERSION)

quantized/plugins/loader.py

@@ -0,0 +1,394 @@
+"""Plugin discovery + loading (gap #8).
+
+Discovers plugins from two sources and registers their contributions through the
+SAME chokepoints the built-ins use (so there is never a second dispatch path):
+
+- drop-in ``.py`` modules in ``<config_dir>/plugins/`` (``config_dir`` reused
+  from :mod:`quantized.io.import_filters` — the repo's one config-dir concept);
+- installed packages exposing the ``quantized.plugins`` entry-point group.
+
+Trust model: a plugin is arbitrary Python you chose to install — treated exactly
+like anything you ``pip install``. There is NO sandbox (sandboxing a Python
+interpreter is a losing game). Install only plugins you trust. See
+``docs/plugins.md``.
+
+Robustness: a plugin that raises on import, declares a missing/incompatible
+manifest, or tries to shadow a built-in extension is LOGGED and SKIPPED — it
+never takes down startup or the other plugins.
+
+Pure ``plugins`` layer — no fastapi/pydantic imports (guarded by
+``test_repo_integrity``).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+import sys
+from collections.abc import Callable, Iterator, Mapping
+from importlib import metadata
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from quantized.calc.fit_models import FIT_MODELS, register_model, unregister_model
+from quantized.datastruct import DataStruct
+from quantized.io.import_filters import config_dir
+from quantized.io.registry import (
+    Parser,
+    Sniffer,
+    register_parser,
+    unregister_plugin_parsers,
+)
+from quantized.plugins import steps as step_registry
+from quantized.plugins.contract import (
+    InvalidManifest,
+    PluginInfo,
+    PluginManifest,
+    validate_manifest,
+)
+
+__all__ = [
+    "disable_plugin",
+    "disabled_sources",
+    "enable_plugin",
+    "ENTRY_POINT_GROUP",
+    "load_plugins",
+    "loaded_plugins",
+    "plugins_dir",
+    "unload_plugins",
+]
+
+_log = logging.getLogger("quantized.plugins")
+
+ENTRY_POINT_GROUP = "quantized.plugins"
+_PLUGINS_SUBDIR = "plugins"
+_CONFIG_FILENAME = "plugins.json"
+_SNIFF_BYTES = 65536  # bytes handed to a plugin's optional bytes -> bool sniffer
+_INF = float("inf")
+
+# Cache of the most recent load, and the model names it registered (so an
+# idempotent reload / test teardown can pop exactly those from the shared
+# FIT_MODELS without touching a built-in model).
+_LOADED: list[PluginInfo] = []
+_PLUGIN_MODEL_NAMES: list[str] = []
+
+
+# ── Public directory / config helpers ───────────────────────────────────────
+def plugins_dir() -> Path:
+    """The drop-in plugins directory (``<config_dir>/plugins``), created on demand."""
+    directory = config_dir() / _PLUGINS_SUBDIR
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def disabled_sources() -> set[str]:
+    """Source identifiers the user has disabled (``<config_dir>/plugins.json``).
+
+    Shape: ``{"disabled": ["source-name", ...]}``. Missing/corrupt -> none
+    disabled. A disabled plugin is never imported (a broken plugin can be parked
+    without deleting it). Public read accessor; see :func:`enable_plugin` /
+    :func:`disable_plugin` for the mutating counterpart used by ``qz plugin
+    enable``/``disable`` (:mod:`quantized.cli`).
+    """
+    path = config_dir() / _CONFIG_FILENAME
+    if not path.is_file():
+        return set()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+        return set()
+    disabled = raw.get("disabled") if isinstance(raw, Mapping) else None
+    if not isinstance(disabled, list):
+        return set()
+    return {str(item) for item in disabled}
+
+
+def _write_disabled_sources(disabled: set[str]) -> None:
+    """Persist ``disabled`` as the ``disabled`` list in ``plugins.json``.
+
+    Preserves any other top-level keys already in the file (forward-
+    compatible with future ``plugins.json`` content) and creates the file if
+    it does not yet exist. A corrupt existing file is treated as empty rather
+    than raising, matching :func:`disabled_sources`'s own corrupt-file
+    handling.
+    """
+    path = config_dir() / _CONFIG_FILENAME
+    payload: dict[str, Any] = {}
+    if path.is_file():
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+            raw = None
+        if isinstance(raw, Mapping):
+            payload = dict(raw)
+    payload["disabled"] = sorted(disabled)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def enable_plugin(source: str) -> None:
+    """Remove ``source`` from the disabled list (idempotent — a no-op if it
+    was not disabled). Does not itself reload; call :func:`load_plugins`
+    afterwards to pick up the change."""
+    _write_disabled_sources(disabled_sources() - {source})
+
+
+def disable_plugin(source: str) -> None:
+    """Add ``source`` to the disabled list (idempotent; creates
+    ``plugins.json`` if absent). Does not itself reload; call
+    :func:`load_plugins` afterwards to pick up the change."""
+    _write_disabled_sources(disabled_sources() | {source})
+
+
+# ── Discovery ────────────────────────────────────────────────────────────────
+def _discover() -> Iterator[tuple[str, str, Callable[[], ModuleType]]]:
+    """Yield ``(source, origin, importer)`` for every discovered plugin.
+
+    File plugins first (sorted, deterministic), then entry points. ``importer``
+    is a thunk that imports and returns the module (and may raise — the caller
+    isolates it).
+    """
+    for path in sorted(plugins_dir().glob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        yield path.stem, "file", _file_importer(path.stem, path)
+    for entry in _entry_points():
+        yield entry.name, "entry_point", _ep_importer(entry)
+
+
+def _entry_points() -> list[Any]:
+    try:
+        found = metadata.entry_points(group=ENTRY_POINT_GROUP)
+    except Exception:  # pragma: no cover - importlib.metadata is robust
+        return []
+    return sorted(found, key=lambda e: e.name)
+
+
+def _file_importer(source: str, path: Path) -> Callable[[], ModuleType]:
+    def _load() -> ModuleType:
+        module_name = f"quantized_plugins.{source}"
+        spec = importlib.util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"cannot create an import spec for {path}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+        except Exception:
+            sys.modules.pop(module_name, None)
+            raise
+        return module
+
+    return _load
+
+
+def _ep_importer(entry: Any) -> Callable[[], ModuleType]:
+    def _load() -> ModuleType:
+        loaded: ModuleType = entry.load()
+        return loaded
+
+    return _load
+
+
+# ── Loading ──────────────────────────────────────────────────────────────────
+def load_plugins() -> list[PluginInfo]:
+    """Discover, validate, and register all plugins; return one info per plugin.
+
+    Idempotent: a prior load's registrations are removed first, so this can be
+    called again to reload. Called once at app startup (:func:`quantized.app.create_app`).
+    """
+    unload_plugins()
+    disabled = disabled_sources()
+    infos: list[PluginInfo] = []
+    for source, origin, importer in _discover():
+        if source in disabled:
+            infos.append(PluginInfo(source=source, origin=origin, status="disabled"))
+            continue
+        infos.append(_load_one(source, origin, importer))
+    _LOADED[:] = infos
+    return infos
+
+
+def loaded_plugins() -> list[PluginInfo]:
+    """The plugins from the most recent :func:`load_plugins` (empty if never run)."""
+    return list(_LOADED)
+
+
+def unload_plugins() -> None:
+    """Remove all plugin-registered contributions (idempotent reload / tests)."""
+    unregister_plugin_parsers()
+    for name in _PLUGIN_MODEL_NAMES:
+        unregister_model(name)
+    _PLUGIN_MODEL_NAMES.clear()
+    step_registry.unregister_plugin_steps()
+    _LOADED.clear()
+
+
+def _load_one(
+    source: str, origin: str, importer: Callable[[], ModuleType]
+) -> PluginInfo:
+    try:
+        module = importer()
+    except Exception as exc:  # a plugin must never crash startup
+        _log.warning("plugin %r failed to import: %s", source, exc)
+        return PluginInfo(
+            source=source, origin=origin, status="error", error=f"import failed: {exc}"
+        )
+    try:
+        manifest = validate_manifest(module)
+    except InvalidManifest as exc:
+        _log.warning("plugin %r has an invalid manifest: %s", source, exc)
+        return PluginInfo(source=source, origin=origin, status="error", error=str(exc))
+    return _register(source, origin, manifest, module)
+
+
+# ── Contribution registration (per-contribution isolation) ──────────────────
+def _register(
+    source: str, origin: str, manifest: PluginManifest, module: ModuleType
+) -> PluginInfo:
+    problems: list[str] = []
+    parsers = _register_parsers(getattr(module, "PARSERS", None), problems)
+    models = _register_models(getattr(module, "FIT_MODELS", None), problems)
+    steps = _register_steps(getattr(module, "STEPS", None), manifest.name, problems)
+    _log.info(
+        "plugin %r (v%s) loaded: %d parser(s), %d model(s), %d step(s)",
+        manifest.name, manifest.version, len(parsers), len(models), len(steps),
+    )
+    return PluginInfo(
+        source=source,
+        origin=origin,
+        status="loaded",
+        name=manifest.name,
+        version=manifest.version,
+        error="; ".join(problems),
+        parsers=tuple(parsers),
+        fit_models=tuple(models),
+        steps=tuple(steps),
+    )
+
+
+def _as_specs(value: Any) -> list[Any]:
+    return list(value) if isinstance(value, list | tuple) else []
+
+
+def _register_parsers(specs: Any, problems: list[str]) -> list[str]:
+    registered: list[str] = []
+    for spec in _as_specs(specs):
+        if not isinstance(spec, Mapping):
+            problems.append("bad parser spec (not a mapping)")
+            continue
+        exts = spec.get("extensions")
+        read = spec.get("read")
+        sniff = spec.get("sniff")
+        if not isinstance(exts, list | tuple) or not exts or read is None:
+            problems.append("bad parser spec (needs 'extensions' + 'read')")
+            continue
+        parser = _wrap_read(read)
+        wrapped_sniff = _wrap_sniff(sniff) if sniff is not None else None
+        for raw_ext in exts:
+            ext = str(raw_ext)
+            try:
+                register_parser([ext], parser, sniff=wrapped_sniff)
+            except ValueError as exc:
+                problems.append(str(exc))
+                continue
+            registered.append(_norm_ext(ext))
+    return registered
+
+
+def _register_models(specs: Any, problems: list[str]) -> list[str]:
+    registered: list[str] = []
+    for spec in _as_specs(specs):
+        if not isinstance(spec, Mapping):
+            problems.append("bad fit-model spec (not a mapping)")
+            continue
+        name = spec.get("name")
+        fn = spec.get("fn")
+        params_raw = spec.get("params", spec.get("param_names"))
+        if (
+            not isinstance(name, str)
+            or not name
+            or fn is None
+            or not isinstance(params_raw, list | tuple)
+        ):
+            problems.append(f"bad fit-model spec for {name!r}")
+            continue
+        if name in FIT_MODELS:
+            problems.append(f"fit model '{name}' is already registered")
+            continue
+        params = [str(p) for p in params_raw]
+        n = len(params)
+        guess = spec.get("guess")
+        p0 = [float(v) for v in guess] if isinstance(guess, list | tuple) else [1.0] * n
+        if len(p0) != n:
+            p0 = (p0 + [1.0] * n)[:n]
+        register_model(name, "Plugin", fn, params, p0, [-_INF] * n, [_INF] * n)
+        _PLUGIN_MODEL_NAMES.append(name)
+        registered.append(name)
+    return registered
+
+
+def _register_steps(specs: Any, plugin_name: str, problems: list[str]) -> list[str]:
+    registered: list[str] = []
+    for spec in _as_specs(specs):
+        if not isinstance(spec, Mapping):
+            problems.append("bad step spec (not a mapping)")
+            continue
+        name = spec.get("name")
+        fn = spec.get("fn")
+        if not isinstance(name, str) or not name or fn is None:
+            problems.append(f"bad step spec for {name!r}")
+            continue
+        try:
+            step_registry.register_step(name, fn, plugin=plugin_name)
+        except ValueError as exc:
+            problems.append(str(exc))
+            continue
+        registered.append(name)
+    return registered
+
+
+# ── Adapters: plugin callable shapes -> registry callable shapes ────────────
+def _norm_ext(ext: str) -> str:
+    lowered = ext.lower()
+    return lowered if lowered.startswith(".") else f".{lowered}"
+
+
+def _wrap_read(read: Any) -> Parser:
+    """Adapt a plugin ``read(path)`` (returns a DataStruct OR a DataStruct dict)
+    to the registry's ``Callable[[Path], DataStruct]``."""
+
+    def parser(path: Path) -> DataStruct:
+        result = read(path)
+        if isinstance(result, DataStruct):
+            return result
+        if isinstance(result, Mapping):
+            return DataStruct.from_dict(result)
+        raise TypeError(
+            "plugin parser 'read' must return a DataStruct or a DataStruct dict, "
+            f"got {type(result).__name__}"
+        )
+
+    return parser
+
+
+def _wrap_sniff(sniff: Any) -> Sniffer:
+    """Adapt a plugin ``sniff(bytes)`` to the registry's ``Callable[[Path], bool]``.
+
+    The first :data:`_SNIFF_BYTES` bytes of the file are handed to the plugin. A
+    sniffer that raises or a file that cannot be read is treated as "no match"
+    (a plugin sniffer must never break resolution for other parsers)."""
+
+    def _sniff_path(path: Path) -> bool:
+        try:
+            with path.open("rb") as handle:
+                data = handle.read(_SNIFF_BYTES)
+        except OSError:
+            return False
+        try:
+            return bool(sniff(data))
+        except Exception:
+            return False
+
+    return _sniff_path

quantized/plugins/steps.py

@@ -0,0 +1,90 @@
+"""Pipeline-step registry for plugin-contributed steps (gap #8).
+
+A step is a pure transform ``fn(DataStruct, params) -> DataStruct``. Plugin API
+v1 REGISTERS and LISTS steps server-side; surfacing them in the frontend
+pipeline palette and replaying them in templates/batches is a later ecosystem
+item. Giving steps a small pure home here means the contract is complete now,
+without a premature route.
+
+All steps are plugin-contributed (there are no built-in steps), so
+:func:`unregister_plugin_steps` simply clears the registry.
+
+Pure ``plugins`` layer — imports only :mod:`quantized.datastruct`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from quantized.datastruct import DataStruct
+
+__all__ = [
+    "StepSpec",
+    "get_step",
+    "list_steps",
+    "register_step",
+    "run_step",
+    "unregister_plugin_steps",
+]
+
+StepFn = Callable[[DataStruct, dict[str, Any]], DataStruct]
+
+
+@dataclass(frozen=True)
+class StepSpec:
+    """One registered pipeline step: a stable ``name`` -> pure transform."""
+
+    name: str
+    fn: StepFn
+    plugin: str = ""
+
+
+_STEPS: dict[str, StepSpec] = {}
+
+
+def register_step(name: str, fn: StepFn, *, plugin: str = "") -> None:
+    """Register a pipeline step under ``name``.
+
+    Refuses (``ValueError``) an empty name or a duplicate — a plugin cannot
+    silently override another plugin's step.
+    """
+    if not name or not name.strip():
+        raise ValueError("step name must be a non-empty string")
+    if name in _STEPS:
+        raise ValueError(f"step '{name}' is already registered")
+    _STEPS[name] = StepSpec(name=name, fn=fn, plugin=plugin)
+
+
+def list_steps() -> list[str]:
+    """Names of all registered steps, sorted for a stable listing."""
+    return sorted(_STEPS)
+
+
+def get_step(name: str) -> StepSpec:
+    """The :class:`StepSpec` registered under ``name`` (``KeyError`` if unknown)."""
+    if name not in _STEPS:
+        raise KeyError(f"unknown step: {name!r}")
+    return _STEPS[name]
+
+
+def run_step(
+    name: str, data: DataStruct, params: dict[str, Any] | None = None
+) -> DataStruct:
+    """Run a registered step — the seam the later execution-wiring item builds on.
+
+    Raises ``KeyError`` for an unknown step and ``TypeError`` if the step returns
+    something other than a :class:`DataStruct`.
+    """
+    result = get_step(name).fn(data, params or {})
+    if not isinstance(result, DataStruct):
+        raise TypeError(
+            f"step '{name}' must return a DataStruct, got {type(result).__name__}"
+        )
+    return result
+
+
+def unregister_plugin_steps() -> None:
+    """Clear all plugin-registered steps (idempotent reload / test isolation)."""
+    _STEPS.clear()

quantized/routes/__init__.py

@@ -0,0 +1,7 @@
+"""Thin FastAPI adapters: validate → call io/calc → serialize. No business logic.
+
+One small router per domain (parsers, plot, corrections, fitting, calc_*,
+workspace, export, session, jobs, dev). Added from M1 #5 onward.
+"""
+
+from __future__ import annotations

quantized/routes/_bookcache.py

@@ -0,0 +1,62 @@
+"""Small bounded LRU cache of one Origin project's per-book DataStructs, keyed
+by ``(resolved path, mtime)`` -- the lazy per-book transport's speed-up
+(``ORIGIN_FILE_DECODE_PLAN`` #38).
+
+``/api/parsers/import``/``upload`` already parse the WHOLE project once
+(``read_origin_project_all``) to build the primary payload + the per-book
+inventory; this module caches that same book list so a later
+``/api/parsers/books/data`` fetch (a book's first activation in the UI) is a
+plain dict lookup, not a second ~4s reparse of a 122-book / 8.5M-cell project.
+
+Lives in ``routes/`` (not ``io/``): it is a transport-layer cache of HTTP
+access patterns, not a parsing concern -- ``io/origin_project`` stays a pure
+reader with no notion of "recently imported". Bounded (a handful of projects)
+and mtime-keyed so an edited-on-disk file is never served stale.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from pathlib import Path
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["cache_project_books", "get_cached_book"]
+
+_MAX_PROJECTS = 4
+_cache: OrderedDict[tuple[str, float], dict[str, DataStruct]] = OrderedDict()
+
+
+def _book_id(ds: DataStruct) -> str:
+    return str(ds.metadata.get("origin_book", ""))
+
+
+def cache_project_books(path: Path, books: list[DataStruct]) -> None:
+    """Cache every book of one already-parsed project, keyed by the path's
+    CURRENT mtime. A later call with a changed mtime lands under a new key
+    (the old one just ages out via the LRU bound below) -- automatic
+    invalidation on file edit, no explicit eviction needed for that case."""
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return
+    key = (str(path), mtime)
+    _cache[key] = {_book_id(b): b for b in books}
+    _cache.move_to_end(key)
+    while len(_cache) > _MAX_PROJECTS:
+        _cache.popitem(last=False)
+
+
+def get_cached_book(path: Path, book_id: str) -> DataStruct | None:
+    """The requested book if the project is cached at its CURRENT mtime, else
+    ``None`` (cold cache, evicted, or the file changed on disk since caching)."""
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return None
+    key = (str(path), mtime)
+    by_id = _cache.get(key)
+    if by_id is None:
+        return None
+    _cache.move_to_end(key)
+    return by_id.get(book_id)

quantized/routes/_export_common.py

@@ -0,0 +1,27 @@
+"""Shared export helpers (MIME types, filename sanitization, attachment headers)."""
+
+from __future__ import annotations
+
+import re
+
+_FIGURE_MIME = {
+    "pdf": "application/pdf",
+    "svg": "image/svg+xml",
+    "png": "image/png",
+    "tiff": "image/tiff",
+}
+_DPI_MIN, _DPI_MAX = 50, 1200  # clamp: guards against absurd allocations
+
+
+def _safe_name(name: str, ext: str) -> str:
+    """Filename safe for a Content-Disposition header: keep only word chars,
+    dot, dash; guarantee the extension. Prevents CRLF/quote injection +
+    path traversal."""
+    base = re.sub(r"[^A-Za-z0-9._-]", "_", name).strip("._") or "export"
+    if not base.lower().endswith(ext):
+        base += ext
+    return base
+
+
+def _attachment(name: str) -> dict[str, str]:
+    return {"Content-Disposition": f'attachment; filename="{name}"'}