floudsonnx 1.0.0__py3-none-any.whl

floudsonnx/__init__.py

@@ -0,0 +1,90 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+"""
+floudsonnx
+~~~~~~~~~~
+Ollama-style ONNX model store and runtime.
+
+Quick start:
+    from floudsonnx import create_model
+
+    model = create_model("sentence-transformers/all-MiniLM-L6-v2")
+    outputs = model.run(None, {"input_ids": ids, "attention_mask": mask})
+"""
+from typing import Any, List
+
+from floudsonnx.api.client import FloudsOnnxClient, get_default_client
+from floudsonnx.config.model_config import ModelConfig
+from floudsonnx.config.settings import FloudsOnnxSettings
+from floudsonnx.exceptions import (
+    ExporterNotInstalledError,
+    ExportError,
+    FloudsOnnxError,
+    ManifestError,
+    ModelLoadError,
+    ModelNotFoundError,
+    OptimumNotInstalledError,
+    StrategyError,
+    TokenizerError,
+)
+from floudsonnx.runtime.loader import LoadedModel
+from floudsonnx.runtime.strategy import SessionStrategy
+from floudsonnx.store.manifest import ModelManifest
+
+__version__ = "1.0.0"
+__all__ = [
+    # Primary API
+    "create_model",
+    "load_model",
+    "pull",
+    "list_models",
+    "remove_model",
+    # Client / settings
+    "FloudsOnnxClient",
+    "FloudsOnnxSettings",
+    "get_default_client",
+    # Types
+    "ModelConfig",
+    "LoadedModel",
+    "SessionStrategy",
+    # Exceptions
+    "FloudsOnnxError",
+    "ModelNotFoundError",
+    "ModelLoadError",
+    "TokenizerError",
+    "ExportError",
+    "ExporterNotInstalledError",
+    "OptimumNotInstalledError",
+    "ManifestError",
+    "StrategyError",
+]
+
+
+# ── Top-level convenience functions (delegate to default client singleton) ────
+
+
+def create_model(model_name: str, model_for: str = "fe", **kwargs: Any) -> LoadedModel:
+    """Pull (auto-export if missing) + load session. Primary entry-point."""
+    return get_default_client().create_model(model_name, model_for, **kwargs)
+
+
+def load_model(model_name: str, model_for: str = "fe") -> LoadedModel:
+    """Load a model already on disk (no auto-pull)."""
+    return get_default_client().load_model(model_name, model_for)
+
+
+def pull(model_name: str, model_for: str = "fe", **kwargs: Any) -> ModelManifest:
+    """Export model to disk only (no session load)."""
+    return get_default_client().pull(model_name, model_for, **kwargs)
+
+
+def list_models() -> List[ModelManifest]:
+    """Return manifests for all locally stored models."""
+    return get_default_client().list()
+
+
+def remove_model(model_name: str, model_for: str = "fe") -> bool:
+    """Delete model from disk and evict from session pool."""
+    return get_default_client().remove(model_name, model_for)

floudsonnx/api/__init__.py

@@ -0,0 +1,7 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from floudsonnx.api.client import FloudsOnnxClient, get_default_client
+
+__all__ = ["FloudsOnnxClient", "get_default_client"]

floudsonnx/api/client.py

@@ -0,0 +1,115 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from __future__ import annotations
+
+import threading
+from typing import Any, List, Optional
+
+from floudsonnx.config.model_config import ModelConfig
+from floudsonnx.config.settings import FloudsOnnxSettings
+from floudsonnx.runtime.loader import LoadedModel, ModelLoader
+from floudsonnx.store.manifest import ModelManifest
+
+
+class FloudsOnnxClient:
+    """Friendly facade over ModelLoader."""
+
+    def __init__(self, settings: Optional[FloudsOnnxSettings] = None) -> None:
+        self._loader = ModelLoader(settings)
+
+    def pull(
+        self,
+        model_name: str,
+        model_for: str = "fe",
+        task: Optional[str] = None,
+        force: bool = False,
+        config: Optional[ModelConfig] = None,
+        optimize: Optional[bool] = None,
+        optimization_level: Optional[int] = None,
+        opset_version: Optional[int] = None,
+        device: str = "cpu",
+        framework: Optional[str] = None,
+        library: Optional[str] = None,
+        normalize_embeddings: Optional[bool] = None,
+        trust_remote_code: bool = False,
+        use_external_data_format: bool = False,
+        use_subprocess: Optional[bool] = None,
+        use_fallback_if_failed: bool = False,
+        merge: bool = False,
+        skip_validator: bool = False,
+        hf_token: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ModelManifest:
+        return self._loader.pull(
+            model_name,
+            model_for,
+            task=task,
+            force=force,
+            config=config,
+            optimize=optimize,
+            optimization_level=optimization_level,
+            opset_version=opset_version,
+            device=device,
+            framework=framework,
+            library=library,
+            normalize_embeddings=normalize_embeddings,
+            trust_remote_code=trust_remote_code,
+            use_external_data_format=use_external_data_format,
+            use_subprocess=use_subprocess,
+            use_fallback_if_failed=use_fallback_if_failed,
+            merge=merge,
+            skip_validator=skip_validator,
+            hf_token=hf_token,
+            **kwargs,
+        )
+
+    def list(self) -> List[ModelManifest]:
+        return self._loader.list()
+
+    def remove(self, model_name: str, model_for: str = "fe") -> bool:
+        return self._loader.remove(model_name, model_for)
+
+    def create_model(
+        self,
+        model_name: str,
+        model_for: str = "fe",
+        task: Optional[str] = None,
+        force_pull: bool = False,
+        config: Optional[ModelConfig] = None,
+        **kwargs: Any,
+    ) -> LoadedModel:
+        return self._loader.create_model(model_name, model_for, task=task, force_pull=force_pull, config=config, **kwargs)
+
+    def load_model(self, model_name: str, model_for: str = "fe") -> LoadedModel:
+        return self._loader.load_model(model_name, model_for)
+
+    def reload(self, model_name: str, model_for: str = "fe") -> LoadedModel:
+        return self._loader.reload(model_name, model_for)
+
+    def unload(self, model_name: str, model_for: str = "fe") -> bool:
+        return self._loader.unload(model_name, model_for)
+
+    def is_loaded(self, model_name: str, model_for: str = "fe") -> bool:
+        return self._loader.is_loaded(model_name, model_for)
+
+    def cache_stats(self) -> dict[str, Any]:
+        return self._loader.cache_stats()
+
+    @property
+    def settings(self) -> FloudsOnnxSettings:
+        return self._loader._settings
+
+
+_default_client: Optional[FloudsOnnxClient] = None
+_default_client_lock = threading.Lock()
+
+
+def get_default_client() -> FloudsOnnxClient:
+    global _default_client
+    if _default_client is None:
+        with _default_client_lock:
+            if _default_client is None:
+                _default_client = FloudsOnnxClient()
+    return _default_client

floudsonnx/api/routers/__init__.py

@@ -0,0 +1,4 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================

floudsonnx/api/routers/health.py

@@ -0,0 +1,19 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from fastapi import APIRouter
+
+    router: Any = APIRouter(tags=["health"])
+
+    @router.get("/health")
+    async def health():
+        return {"status": "ok", "service": "floudsonnx"}
+
+except ImportError:
+    router = None

floudsonnx/api/routers/models.py

@@ -0,0 +1,93 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from __future__ import annotations
+
+from typing import Annotated, Any, Optional
+
+try:
+    from fastapi import APIRouter, HTTPException, Query
+    from pydantic import BaseModel as _BM
+
+    from floudsonnx.api.client import get_default_client
+    from floudsonnx.exceptions import FloudsOnnxError
+
+    router = APIRouter(tags=["models"])
+
+    class PullRequest(_BM):
+        model_name: str
+        model_for: str = "fe"
+        task: Optional[str] = None
+        force: bool = False
+        optimize: Optional[bool] = None
+        trust_remote_code: bool = False
+        use_external_data_format: bool = False
+        use_fallback_if_failed: bool = False
+        hf_token: Optional[str] = None
+
+    class LoadRequest(_BM):
+        model_name: str
+        model_for: str = "fe"
+
+    @router.get("/models")
+    async def list_models() -> list[dict[str, Any]]:
+        return [m.model_dump(mode="json") for m in get_default_client().list()]
+
+    @router.get("/models/{name:path}")
+    async def get_model(name: str, model_for: Annotated[str, Query()] = "fe") -> dict[str, Any]:
+        manifest = get_default_client()._loader._registry.get_manifest(name, model_for)
+        if manifest is None:
+            raise HTTPException(status_code=404, detail=f"Model '{name}' not found")
+        return manifest.model_dump(mode="json")
+
+    @router.post("/models/pull")
+    async def pull_model(req: PullRequest) -> dict[str, Any]:
+        try:
+            manifest = get_default_client().pull(
+                req.model_name,
+                req.model_for,
+                task=req.task,
+                force=req.force,
+                optimize=req.optimize,
+                trust_remote_code=req.trust_remote_code,
+                use_external_data_format=req.use_external_data_format,
+                use_fallback_if_failed=req.use_fallback_if_failed,
+                hf_token=req.hf_token,
+            )
+            return manifest.model_dump(mode="json")
+        except FloudsOnnxError as exc:
+            raise HTTPException(status_code=500, detail=str(exc))
+
+    @router.post("/models/load")
+    async def load_model(req: LoadRequest) -> dict[str, str]:
+        try:
+            loaded = get_default_client().load_model(req.model_name, req.model_for)
+            return {"model_name": loaded.model_name, "model_for": loaded.model_for, "strategy": loaded.session_strategy.value, "status": "loaded"}
+        except FloudsOnnxError as exc:
+            raise HTTPException(status_code=500, detail=str(exc))
+
+    @router.post("/models/reload")
+    async def reload_model(req: LoadRequest) -> dict[str, str]:
+        try:
+            loaded = get_default_client().reload(req.model_name, req.model_for)
+            return {"model_name": loaded.model_name, "strategy": loaded.session_strategy.value, "status": "reloaded"}
+        except FloudsOnnxError as exc:
+            raise HTTPException(status_code=500, detail=str(exc))
+
+    @router.post("/models/unload")
+    async def unload_model(req: LoadRequest) -> dict[str, Any]:
+        evicted = get_default_client().unload(req.model_name, req.model_for)
+        return {"model_name": req.model_name, "evicted": evicted}
+
+    @router.delete("/models/{name:path}")
+    async def remove_model(name: str, model_for: Annotated[str, Query()] = "fe") -> dict[str, Any]:
+        removed = get_default_client().remove(name, model_for)
+        return {"model_name": name, "removed": removed}
+
+    @router.get("/stats")
+    async def stats() -> dict[str, Any]:
+        return get_default_client().cache_stats()
+
+except ImportError:
+    router = None

floudsonnx/api/server.py

@@ -0,0 +1,30 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from __future__ import annotations
+
+from typing import Any
+
+from floudsonnx.exceptions import ServerNotInstalledError
+
+
+def create_app() -> Any:
+    try:
+        from fastapi import FastAPI
+    except ImportError as exc:
+        raise ServerNotInstalledError() from exc
+    from floudsonnx.api.routers import health, models
+
+    app = FastAPI(title="floudsonnx", description="ONNX model store and runtime REST API", version="1.0.0")
+    app.include_router(health.router)
+    app.include_router(models.router, prefix="/api/v1")
+    return app
+
+
+def run_server(host: str = "127.0.0.1", port: int = 19720, reload: bool = False) -> None:
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise ServerNotInstalledError() from exc
+    uvicorn.run("floudsonnx.api.server:create_app", factory=True, host=host, port=port, reload=reload)

floudsonnx/cli/__init__.py

@@ -0,0 +1,4 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================

floudsonnx/cli/main.py

@@ -0,0 +1,190 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+"""
+floudsonnx CLI — entry-point: floudsonnx <command> [options]
+
+Commands:
+  pull    <model_name>  [--for fe] [--task T] [--optimize] [--force]
+                        [--trust-remote-code] [--use-external-data-format]
+                        [--use-fallback-if-failed] [--hf-token T]
+  list
+  info    <model_name>  [--for fe]
+  remove  <model_name>  [--for fe]
+  reload  <model_name>  [--for fe]
+  stats
+  serve   [--host H] [--port P]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+
+def _client() -> Any:
+    from floudsonnx.api.client import get_default_client
+
+    return get_default_client()
+
+
+def cmd_pull(args: argparse.Namespace) -> int:
+    print(f"Pulling '{args.model_name}' (model_for={args.model_for}, optimize={args.optimize}) ...")
+    try:
+        manifest = _client().pull(
+            args.model_name,
+            model_for=args.model_for,
+            task=args.task or None,
+            force=args.force,
+            optimize=args.optimize,
+            optimization_level=args.optimization_level,
+            opset_version=args.opset_version,
+            device=args.device,
+            framework=args.framework or None,
+            library=args.library or None,
+            normalize_embeddings=args.normalize_embeddings,
+            trust_remote_code=args.trust_remote_code,
+            use_external_data_format=args.use_external_data_format,
+            use_subprocess=args.use_subprocess,
+            use_fallback_if_failed=args.use_fallback_if_failed,
+            merge=args.merge,
+            skip_validator=args.skip_validator,
+            hf_token=args.hf_token or None,
+        )
+        print(f"OK  {manifest.model_name}  [{manifest.model_for}]  pulled_at={manifest.pulled_at}")
+        print(f"    strategy : {manifest.session_strategy}")
+        print(f"    onnx     : {', '.join(manifest.onnx_files) or 'none'}")
+        return 0
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    manifests = _client().list()
+    if not manifests:
+        print("No models in local store.")
+        return 0
+    fmt = "{:<50}  {:<10}  {:<25}  {}"
+    print(fmt.format("MODEL", "FOR", "PULLED AT", "STRATEGY"))
+    print("-" * 105)
+    for m in manifests:
+        print(fmt.format(m.model_name[:48], m.model_for, m.pulled_at[:24], m.session_strategy))
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    manifest = _client()._loader._registry.get_manifest(args.model_name, args.model_for)
+    if manifest is None:
+        print(f"Model '{args.model_name}' not found.", file=sys.stderr)
+        return 1
+    print(json.dumps(manifest.model_dump(mode="json"), indent=2))
+    return 0
+
+
+def cmd_remove(args: argparse.Namespace) -> int:
+    removed = _client().remove(args.model_name, args.model_for)
+    print(f"Removed '{args.model_name}'" if removed else f"'{args.model_name}' was not in the local store.")
+    return 0
+
+
+def cmd_reload(args: argparse.Namespace) -> int:
+    try:
+        loaded = _client().reload(args.model_name, args.model_for)
+        print(f"Reloaded '{loaded.model_name}' — strategy={loaded.session_strategy.value}")
+        return 0
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    print(json.dumps(_client().cache_stats(), indent=2))
+    return 0
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    try:
+        from floudsonnx.api.server import run_server
+
+        print(f"Starting floudsonnx server on {args.host}:{args.port} ...")
+        run_server(host=args.host, port=args.port)
+        return 0
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="floudsonnx", description="Ollama-style ONNX model store and runtime")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # pull
+    p = sub.add_parser("pull", help="Pull (export) a model to the local store")
+    p.add_argument("model_name")
+    p.add_argument("--for", dest="model_for", default="fe", help="fe|s2s|sc|ranker|llm (default: fe)")
+    p.add_argument("--task", default="", help="Optimum export task")
+    p.add_argument("--optimize", action="store_true", default=True)
+    p.add_argument("--no-optimize", dest="optimize", action="store_false")
+    p.add_argument("--optimization-level", type=int, default=99)
+    p.add_argument("--opset-version", type=int, default=None)
+    p.add_argument("--device", default="cpu")
+    p.add_argument("--framework", default="")
+    p.add_argument("--library", default="")
+    p.add_argument("--normalize-embeddings", action="store_true")
+    p.add_argument("--force", action="store_true")
+    p.add_argument("--trust-remote-code", action="store_true")
+    p.add_argument("--use-external-data-format", action="store_true")
+    p.add_argument("--use-subprocess", action="store_true")
+    p.add_argument("--use-fallback-if-failed", action="store_true")
+    p.add_argument("--merge", action="store_true")
+    p.add_argument("--skip-validator", action="store_true")
+    p.add_argument("--hf-token", default="", help="HuggingFace API token")
+    p.set_defaults(func=cmd_pull)
+
+    # list
+    p = sub.add_parser("list", help="List all locally stored models")
+    p.set_defaults(func=cmd_list)
+
+    # info
+    p = sub.add_parser("info", help="Show manifest for a model")
+    p.add_argument("model_name")
+    p.add_argument("--for", dest="model_for", default="fe")
+    p.set_defaults(func=cmd_info)
+
+    # remove
+    p = sub.add_parser("remove", help="Delete a model from the local store")
+    p.add_argument("model_name")
+    p.add_argument("--for", dest="model_for", default="fe")
+    p.set_defaults(func=cmd_remove)
+
+    # reload
+    p = sub.add_parser("reload", help="Evict and re-load a model session from disk")
+    p.add_argument("model_name")
+    p.add_argument("--for", dest="model_for", default="fe")
+    p.set_defaults(func=cmd_reload)
+
+    # stats
+    p = sub.add_parser("stats", help="Show session cache statistics")
+    p.set_defaults(func=cmd_stats)
+
+    # serve
+    p = sub.add_parser("serve", help="Start the HTTP server")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=19720)
+    p.set_defaults(func=cmd_serve)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

floudsonnx/config/__init__.py

@@ -0,0 +1,8 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+from floudsonnx.config.model_config import DecoderInputNames, InputNames, ModelConfig, OutputNames
+from floudsonnx.config.settings import FloudsOnnxSettings
+
+__all__ = ["FloudsOnnxSettings", "ModelConfig", "InputNames", "OutputNames", "DecoderInputNames"]

floudsonnx/config/model_config.py

@@ -0,0 +1,108 @@
+# =============================================================================
+# Copyright (c) 2026 Goutam Malakar. All rights reserved.
+# Licensed under the Apache License, Version 2.0.
+# =============================================================================
+"""
+floudsonnx.config.model_config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Self-contained ModelConfig — clean replacement for OnnxConfig from model_service.
+All fields mirror OnnxConfig for manifest compatibility.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class InputNames(BaseModel):
+    input: str = "input_ids"
+    mask: str = "attention_mask"
+    position: Optional[str] = None
+    token_type: Optional[str] = None
+    decoder_input: str = "decoder_input_ids"
+
+
+class OutputNames(BaseModel):
+    output: str = "last_hidden_state"
+
+
+class DecoderInputNames(BaseModel):
+    input: str = "input_ids"
+    mask: str = "encoder_attention_mask"
+    encoder_output: str = "encoder_hidden_states"
+
+
+class ModelConfig(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+    model_name: str
+    model_for: str = "fe"  # fe | s2s | sc | ranker | llm
+    tasks: List[str] = Field(default_factory=list)
+    model_folder_name: Optional[str] = None
+
+    # ── Encoder / embedding ───────────────────────────────────────────────────
+    dimension: Optional[int] = None
+    native_dimension: Optional[int] = None
+    max_length: int = 256
+    min_length: int = 0
+    pooling_strategy: str = "mean"
+    normalize: bool = False
+    force_pooling: bool = True
+    lowercase: bool = True
+    remove_emojis: bool = False
+    legacy_tokenizer: bool = False
+    chunk_logic: str = "sentence"
+    chunk_overlap: int = 1
+    chunk_size: Optional[int] = None
+
+    # ── ONNX artifact names ───────────────────────────────────────────────────
+    encoder_onnx_model: str = "model.onnx"
+    optimized_onnx_model: str = "model_optimized.onnx"
+    decoder_onnx_model: str = "decoder_model.onnx"
+    decoder_onnx_model_with_past: Optional[str] = None
+
+    # ── Architecture flags ────────────────────────────────────────────────────
+    encoder_only: bool = False
+    decoder_only: bool = False
+    use_seq2seqlm: bool = False
+    merged_with_past: bool = False
+    use_cache: Optional[bool] = None
+
+    # ── I/O name mappings ─────────────────────────────────────────────────────
+    inputnames: InputNames = Field(default_factory=InputNames)
+    outputnames: OutputNames = Field(default_factory=OutputNames)
+    decoder_inputnames: DecoderInputNames = Field(default_factory=DecoderInputNames)
+
+    # ── Generation parameters ─────────────────────────────────────────────────
+    num_beams: int = 4
+    temperature: float = 0.0
+    top_k: Optional[int] = None
+    top_p: Optional[float] = None
+    repetition_penalty: Optional[float] = None
+    early_stopping: bool = True
+    max_new_tokens: Optional[int] = 512
+    forced_bos_token_id: Optional[int] = None
+    eos_token_id: Optional[int] = None
+    bos_token_id: Optional[int] = None
+    pad_token_id: int = 0
+    vocab_size: Optional[int] = None
+    prepend_text: str = "summarize: "
+
+    # ── Chat / LLM ────────────────────────────────────────────────────────────
+    model_family: Optional[str] = None
+    chat_template: Optional[str] = None
+    extract_assistant_only: bool = False
+    assistant_prefix: str = "assistant:"
+
+    # ── Quantization ─────────────────────────────────────────────────────────
+    quantize: bool = False
+    quantize_type: str = "int8"
+
+    # ── Special token file names ──────────────────────────────────────────────
+    special_tokens_map_path: str = "special_tokens_map.json"
+    generation_config_path: str = "generation_config.json"
+
+    # ── Extra / pass-through ──────────────────────────────────────────────────
+    extra: Dict[str, Any] = Field(default_factory=dict)