bladekit 4.5.0__py3-none-any.whl

bladekit/_cls.py

@@ -0,0 +1,574 @@
+"""``@app.cls()`` classes and their container-lifecycle hooks.
+
+The standard inference pattern: a class loads its model once per container, then
+each method call reuses it::
+
+    @app.cls(gpu="RTX-A4500", image=img)
+    class Embedder:
+        @bladekit.enter()
+        def load(self):
+            self.model = load_model()
+
+        @app.method()
+        def embed(self, texts):
+            return self.model.encode(texts)
+
+    Embedder().embed.remote([...])
+
+Contract (runner-protocol.md §10): the runner instantiates the class with NO
+args, runs every method marked ``__forge_enter__`` (in ``__forge_enter_seq__``
+order — set by ``@bladekit.enter()``), once per container, then calls the target
+method. ``FunctionRef.class_name`` carries the class qualname; ``qualname`` is
+the full method qualname (``Embedder.embed``). Those two attributes are THE
+SDK↔runner contract — see also ``forge-runner``.
+
+Three lifecycle hooks mirror one another (all discovered by a marker attribute
+the runner scans for, exactly like ``__forge_enter__``):
+
+- ``@bladekit.build`` — runs ONCE at image-build time to bake state into the image
+  (weights, caches). Until the control-plane build path executes it, the runner
+  falls back to running it once per container, before the enter hooks — see
+  ``comingSoon`` in the tutorial and the runner's ``instantiate_with_enter``.
+- ``@bladekit.enter`` — runs once per container before the first call (model load).
+- ``@bladekit.exit`` — runs once per container at graceful teardown, after the last
+  call drains and before the process exits (flush caches, close handles).
+
+``bladekit.parameter()`` declares a typed parameter so ONE class definition deploys
+as many parametrized instances, each addressed by its parameter values (the
+``modal.parameter`` equivalent) — the runner instantiates one container per
+distinct parameter tuple and routes each call to the matching instance.
+
+A run targets ONE method (one run = one callable + a FIFO call queue). Two
+methods = two runs.
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from . import exceptions as exc
+
+# Global, monotonically-increasing sequences = definition order of each hook
+# kind across the whole process. The runner orders hooks by these values (§10).
+# Each kind has its own counter so build/enter/exit never interleave by accident.
+_enter_seq = itertools.count()
+_build_seq = itertools.count()
+_exit_seq = itertools.count()
+
+# Sentinel for "no default" so ``None`` stays a valid parameter default.
+_MISSING = object()
+
+# The value types a ``bladekit.parameter()`` may carry. Kept to the small set that
+# is safely serializable AND hashable (so a parameter tuple can key a container
+# pool), matching modal.parameter's supported types.
+_PARAM_TYPES: Tuple[type, ...] = (str, int, float, bool, bytes)
+
+# Resolve a stringized annotation back to its concrete type. Under
+# ``from __future__ import annotations`` (PEP 563 — common in user modules) a
+# class annotation is a *string* ("str", "int", …), so the annotation read off
+# ``__annotations__`` never equals the ``str``/``int`` type object and type
+# validation would silently no-op. We resolve the small allowed set by name.
+_PARAM_TYPES_BY_NAME: Dict[str, type] = {t.__name__: t for t in _PARAM_TYPES}
+
+
+def _resolve_param_type(annotation: Any) -> Optional[type]:
+    """Normalise a parameter annotation to a concrete type (or None).
+
+    Accepts a type object as-is and resolves a stringized annotation (PEP 563)
+    by name against the allowed scalar types; anything else resolves to None
+    (untyped — no validation beyond the scalar allow-list at bind time).
+    """
+    if isinstance(annotation, type):
+        return annotation
+    if isinstance(annotation, str):
+        return _PARAM_TYPES_BY_NAME.get(annotation)
+    return None
+
+
+def _reject_async(fn: Callable[..., Any], what: str) -> None:
+    """Reject ``async def`` at decoration time (see _app._reject_coroutine_function).
+
+    Imported lazily: ``_app`` imports ``_cls`` (inside ``App.cls``), so a
+    module-level import here would close the cycle.
+    """
+    from ._app import _reject_coroutine_function  # noqa: PLC0415 - avoids an import cycle
+
+    _reject_coroutine_function(fn, what)
+
+
+def enter() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Mark a method to run once per container before the first call (model load).
+
+    Usable as ``@bladekit.enter()``. Re-run after a hot reload (``blade serve``):
+    the instance is dropped with its module, so the hook reloads the model on
+    the new code (runner-protocol.md §9/§10).
+    """
+
+    def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
+        _reject_async(fn, "@bladekit.enter")
+        fn.__forge_enter__ = True  # type: ignore[attr-defined]
+        fn.__forge_enter_seq__ = next(_enter_seq)  # type: ignore[attr-defined]
+        return fn
+
+    return deco
+
+
+def build() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Mark a method to run ONCE at image-build time to bake state into the image.
+
+    Usable as ``@bladekit.build()``. The canonical use is to persist expensive,
+    deterministic setup — download model weights, warm a compile cache — into the
+    image layer so every container starts with it already present, paying the cost
+    once at build time rather than on every cold start.
+
+    Build-time execution is driven by the control-plane image-build path. Until
+    that path is deployed, the runner falls back to running ``@bladekit.build``
+    methods once per container, before the enter hooks (see
+    ``forge_runner.execute.instantiate_with_enter``). The fallback is semantically
+    weaker (per-container, not baked into the image) but keeps user code correct;
+    the tutorial documents the limitation honestly.
+    """
+
+    def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
+        _reject_async(fn, "@bladekit.build")
+        fn.__forge_build__ = True  # type: ignore[attr-defined]
+        fn.__forge_build_seq__ = next(_build_seq)  # type: ignore[attr-defined]
+        return fn
+
+    return deco
+
+
+def exit() -> Callable[[Callable[..., Any]], Callable[..., Any]]:  # noqa: A001 - public API mirrors modal.exit
+    """Mark a method to run once per container at graceful shutdown/teardown.
+
+    Usable as ``@bladekit.exit()``. The runner runs every ``@bladekit.exit`` method,
+    in ``__forge_exit_seq__`` order, after the container's last call has drained
+    and BEFORE the process exits — on a normal drain and on a teardown alike
+    (runner-protocol.md §10). Use it to flush a cache, commit a Volume, close a
+    network handle, or write a final metric. Exit hooks are best-effort: an
+    exception in one is logged and the remaining hooks still run, so a failing
+    teardown never wedges container shutdown.
+    """
+
+    def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
+        _reject_async(fn, "@bladekit.exit")
+        fn.__forge_exit__ = True  # type: ignore[attr-defined]
+        fn.__forge_exit_seq__ = next(_exit_seq)  # type: ignore[attr-defined]
+        return fn
+
+    return deco
+
+
+class _Parameter:
+    """A declared typed parameter of an ``@app.cls`` class (see ``parameter``).
+
+    Placed as a class attribute (``model_name: str = bladekit.parameter()``) it turns
+    the class into a *parametrized* class: instead of a single instance, one
+    definition deploys as many instances, one per distinct set of parameter
+    values, each addressed by those values. ``name``/``type`` are filled in by
+    ``Cls`` when it scans the user class (``type`` from the annotation unless given
+    explicitly).
+    """
+
+    __slots__ = ("default", "type", "name")
+
+    def __init__(self, default: Any = _MISSING, *, type: Optional[type] = None) -> None:  # noqa: A002 - mirrors modal.parameter
+        self.default = default
+        self.type = type
+        self.name: Optional[str] = None
+
+    @property
+    def required(self) -> bool:
+        return self.default is _MISSING
+
+    def __repr__(self) -> str:
+        d = "<required>" if self.required else repr(self.default)
+        return f"<bladekit.parameter name={self.name!r} type={self.type} default={d}>"
+
+
+def parameter(default: Any = _MISSING, *, type: Optional[type] = None) -> Any:  # noqa: A002 - mirrors modal.parameter
+    """Declare a typed parameter on an ``@app.cls`` class (``modal.parameter``).
+
+    Usage::
+
+        @app.cls(gpu="RTX-A4500", image=img)
+        class Model:
+            model_name: str = bladekit.parameter(default="Qwen/Qwen2.5-1.5B-Instruct")
+
+            @bladekit.enter()
+            def load(self):
+                self.pipe = load(self.model_name)
+
+            @app.method()
+            def generate(self, prompt): ...
+
+        # one definition, two parametrized instances → two container pools
+        Model(model_name="Qwen/Qwen2.5-1.5B-Instruct").generate.remote("hi")
+        Model(model_name="meta-llama/Llama-3.1-8B-Instruct").generate.remote("hi")
+
+    The value type is taken from the annotation (or the explicit ``type=``) and
+    must be one of ``str``, ``int``, ``float``, ``bool``, ``bytes``. A parameter
+    without a ``default`` is required at call time. The bound values travel with
+    the call so the runner instantiates the class with them and routes the call to
+    the matching parametrized container.
+    """
+    return _Parameter(default=default, type=type)
+
+
+def _validate_param_value(name: str, value: Any, declared: Optional[type]) -> None:
+    """Validate a bound parameter value against the allowed types / declaration."""
+    # bool is a subclass of int; check the concrete type against the allow-list so
+    # e.g. a list or a numpy scalar is rejected with a clear message.
+    if type(value) not in _PARAM_TYPES:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            f"parameter {name!r} must be one of str/int/float/bool/bytes, "
+            f"got {type(value).__name__}",
+        )
+    if declared in _PARAM_TYPES:
+        # Accept an int where a float is declared (the usual numeric widening);
+        # every other mismatch is an error.
+        if declared is float and isinstance(value, int) and not isinstance(value, bool):
+            return
+        if not isinstance(value, declared):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"parameter {name!r} expects {declared.__name__}, "
+                f"got {type(value).__name__}",
+            )
+
+
+class Method:
+    """A method of an ``@app.cls`` class, callable remotely.
+
+    Bound onto an instance via the descriptor protocol so
+    ``Embedder().embed.remote(...)`` works. The handle creates a run whose
+    ``FunctionRef`` names the class and the full method qualname.
+    """
+
+    def __init__(self, fn: Callable[..., Any]) -> None:
+        _reject_async(fn, "@app.method")
+        self._fn = fn
+        self.__name__ = getattr(fn, "__name__", "method")
+        self.__qualname__ = getattr(fn, "__qualname__", self.__name__)
+        self.__doc__ = getattr(fn, "__doc__", None)
+        self._cls: Optional["Cls"] = None  # set by Cls._bind_methods
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.__name__ = name
+
+    def __get__(self, instance: Any, owner: type) -> Any:
+        # Accessed on the class object (owner) before instantiation, or on an
+        # instance. Either way we return a bound remote handle. The user's
+        # local code path goes through __call__ on the underlying function.
+        if instance is None:
+            return self
+        return _BoundMethod(self, instance)
+
+    def __call__(self, instance: Any, *args: Any, **kwargs: Any) -> Any:
+        """Direct local call (also the path forge-runner uses after getattr)."""
+        return self._fn(instance, *args, **kwargs)
+
+
+class _BoundMethod:
+    """``instance.method`` — exposes ``.remote()`` / ``.spawn()`` / ``.local()``."""
+
+    def __init__(self, method: Method, instance: Any) -> None:
+        self._method = method
+        self._instance = instance
+        # Parametrized classes stamp the bound parameter values on the instance so
+        # the remote handle can carry them to the runner (routing by param value).
+        self._params: Optional[Dict[str, Any]] = getattr(
+            instance, "__forge_bound_params__", None
+        )
+
+    def local(self, *args: Any, **kwargs: Any) -> Any:
+        return self._method._fn(self._instance, *args, **kwargs)
+
+    __call__ = local
+
+    def _function(self):
+        cls = self._method._cls
+        if cls is None:
+            raise exc.FabricError(
+                f"method {self._method.__name__!r} is not registered on an "
+                "@app.cls class"
+            )
+        return cls._function_for(self._method, params=self._params)
+
+    def remote(self, *args: Any, **kwargs: Any) -> Any:
+        return self._function().remote(*args, **kwargs)
+
+    def spawn(self, *args: Any, **kwargs: Any):
+        return self._function().spawn(*args, **kwargs)
+
+
+class Cls:
+    """An ``@app.cls()``-decorated class: a namespace of remote methods.
+
+    Calling it (``Embedder()``) returns a normal instance for local use; remote
+    calls go through ``instance.method.remote(...)``.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        user_cls: type,
+        *,
+        gpu: Optional[str] = None,
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        timeout: Optional[int] = None,
+        image: Any = None,
+        idle_timeout: Optional[int] = None,
+        volumes: Optional[Dict[str, Any]] = None,
+        secrets: Optional[List[Any]] = None,
+        gpu_class: str = "spot",
+        best_effort: bool = False,
+        max_interruptions: Optional[int] = None,
+    ) -> None:
+        self._app = app
+        self._user_cls = user_cls
+        self._gpu = gpu
+        self._cpu = cpu
+        self._memory = memory
+        self._timeout = timeout
+        self._image = image
+        self._idle_timeout = idle_timeout
+        self._volumes = volumes
+        self._secrets = secrets
+        # Capacity class + preemption budget, forwarded to the per-method
+        # Function (m8-spot.md §13).
+        self._gpu_class = gpu_class
+        self._best_effort = best_effort
+        self._max_interruptions = max_interruptions
+        self._serve = False
+        # method name -> Function (lazily built, cached per method)
+        self._functions: Dict[Tuple[str, Optional[tuple]], Any] = {}
+        self._methods: Dict[str, Method] = {}
+        self.__name__ = user_cls.__name__
+        self.__qualname__ = user_cls.__qualname__
+        self.__doc__ = user_cls.__doc__
+        # SDK↔runner contract (runner-protocol §10): @app.cls replaces the class
+        # in the module namespace with this wrapper, so the runner's
+        # getattr(module, class_name) resolves to a Cls, not a `type`. Expose the
+        # underlying class under a stable dunder so the runner can unwrap it and
+        # instantiate it / find its @bladekit.enter hooks. Additive, documented in
+        # contracts/CHANGELOG.md.
+        self.__forge_user_class__ = user_cls
+        self._bind_methods()
+        # Declared bladekit.parameter() attributes (name -> _Parameter). Non-empty
+        # ⇒ this is a parametrized class: __call__ binds values instead of running
+        # the user __init__ (mirrors modal.parameter, which synthesizes __init__).
+        self._parameters: Dict[str, _Parameter] = self._collect_parameters()
+
+    def _bind_methods(self) -> None:
+        for name, attr in vars(self._user_cls).items():
+            if isinstance(attr, Method):
+                attr._cls = self
+                self._methods[name] = attr
+
+    def _collect_parameters(self) -> Dict[str, _Parameter]:
+        """Scan the class (MRO) for ``bladekit.parameter()`` declarations.
+
+        The value type is taken from the matching annotation unless the parameter
+        gave an explicit ``type=``. Own-class declarations win over inherited
+        ones (a subclass may re-declare a parameter).
+        """
+        annotations: Dict[str, Any] = {}
+        params: Dict[str, _Parameter] = {}
+        # Walk base→derived so a subclass override replaces the parent's entry.
+        for klass in reversed(self._user_cls.__mro__):
+            annotations.update(getattr(klass, "__annotations__", {}) or {})
+            for name, attr in vars(klass).items():
+                if isinstance(attr, _Parameter):
+                    attr.name = name
+                    if attr.type is None:
+                        attr.type = _resolve_param_type(annotations.get(name))
+                    else:
+                        # An explicit type= may still arrive stringized.
+                        attr.type = _resolve_param_type(attr.type)
+                    params[name] = attr
+        return params
+
+    @property
+    def parameters(self) -> Dict[str, _Parameter]:
+        return dict(self._parameters)
+
+    def _bind_parameters(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        """Resolve call-time kwargs against the declared parameters (validated)."""
+        bound: Dict[str, Any] = {}
+        for name, param in self._parameters.items():
+            if name in kwargs:
+                value = kwargs[name]
+            elif not param.required:
+                value = param.default
+            else:
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"missing required parameter {name!r} for @app.cls "
+                    f"{self.__name__!r}",
+                )
+            _validate_param_value(name, value, param.type)
+            bound[name] = value
+        extra = sorted(set(kwargs) - set(self._parameters))
+        if extra:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"unknown parameter(s) {extra} for @app.cls {self.__name__!r}; "
+                f"declared: {sorted(self._parameters)}",
+            )
+        return bound
+
+    def _construct_parametrized(self, bound: Dict[str, Any]) -> Any:
+        """Build an instance for a parametrized class WITHOUT the user __init__.
+
+        Like modal.parameter, a parametrized class does not define its own
+        ``__init__``; the parameter values are set as attributes directly. The
+        enter/build hooks (which read ``self.<param>``) run afterwards.
+        """
+        # The ignore below is a mypy limitation, not a defect: mypy cannot model
+        # `type.__new__` on a dynamic class object -- it offers only the 1-arg
+        # `type(o)` and 3-arg `type(name, bases, ns)` overloads, and this is
+        # neither. Keeping
+        # `cls.__new__(cls)` is deliberate -- it is the stdlib idiom for building
+        # an instance without running `__init__` (what copy and pickle use) and
+        # it still honours a user-defined `__new__`. `object.__new__(cls)` does
+        # type-check, and is WRONG here: it would bypass that `__new__`.
+        instance = self._user_cls.__new__(self._user_cls)  # type: ignore[call-overload]
+        for name, value in bound.items():
+            setattr(instance, name, value)
+        return instance
+
+    @staticmethod
+    def _params_cache_key(params: Optional[Dict[str, Any]]) -> Optional[tuple]:
+        if not params:
+            return None
+        return tuple(sorted(params.items()))
+
+    @property
+    def methods(self) -> Dict[str, Method]:
+        return dict(self._methods)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Instantiate the underlying class (local use / runner instantiation).
+
+        For a parametrized class (``bladekit.parameter`` declared) the call binds the
+        keyword parameter values, validates them, and returns an instance carrying
+        ``__forge_bound_params__`` so the remote handle routes to the matching
+        parametrized container. A non-parametrized class instantiates normally.
+        """
+        if self._parameters:
+            if args:
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"parametrized @app.cls {self.__name__!r} takes keyword "
+                    "parameters only, not positional arguments",
+                )
+            bound = self._bind_parameters(kwargs)
+            instance = self._construct_parametrized(bound)
+            instance.__forge_bound_params__ = bound
+            return instance
+        return self._user_cls(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return (
+            f"<bladekit.Cls {self._app.name}.{self.__name__} "
+            f"methods={list(self._methods)}>"
+        )
+
+    def _function_for(
+        self, method: Method, params: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        """Build (and cache) the ``Function`` backing one method's remote calls.
+
+        ``params`` (when the method is called on a parametrized instance) is
+        folded into the cache key AND the FunctionRef, so each distinct parameter
+        tuple gets its own Function — hence its own run and its own container pool,
+        routed by parameter value.
+        """
+        name = method.__name__
+        cache_key = (name, self._params_cache_key(params))
+        cached = self._functions.get(cache_key)
+        if cached is not None:
+            return cached
+
+        from ._app import Function
+
+        # The Function wraps the method so the runner imports the module,
+        # instantiates the class, runs @bladekit.build/@bladekit.enter hooks, then calls
+        # the method (runner-protocol.md §10). Locally, calling the Function runs
+        # the user method on a fresh instance — matching the remote semantics.
+        user_cls = self._user_cls
+        cls_obj = self
+
+        def _local_call(*args: Any, **kwargs: Any) -> Any:
+            if params:
+                instance = cls_obj._construct_parametrized(params)
+            else:
+                instance = user_cls()
+            _run_build_hooks(instance)
+            _run_enter_hooks(instance)
+            return method._fn(instance, *args, **kwargs)
+
+        _local_call.__name__ = name
+        # The runner resolves the method by "ClassName.method_name". We use the
+        # short class __name__ (not __qualname__) so that the qualname is always
+        # in the form "Embedder.embed" — resolvable by getattr from the module —
+        # regardless of where the class was defined (e.g. inside a test helper).
+        _local_call.__qualname__ = f"{self.__name__}.{name}"
+        _local_call.__module__ = getattr(user_cls, "__module__", "__main__")
+
+        fn = Function(
+            self._app,
+            _local_call,
+            gpu=self._gpu,
+            cpu=self._cpu,
+            memory=self._memory,
+            timeout=self._timeout,
+            image=self._image,
+            idle_timeout=self._idle_timeout,
+            volumes=self._volumes,
+            secrets=self._secrets,
+            class_name=self.__name__,
+            serve=self._serve,
+            gpu_class=self._gpu_class,
+            best_effort=self._best_effort,
+            max_interruptions=self._max_interruptions,
+            parameters=params,
+        )
+        self._functions[cache_key] = fn
+        return fn
+
+
+def _run_marked_hooks(instance: Any, marker: str, seq_marker: str) -> None:
+    """Run every method carrying ``marker`` in ``seq_marker`` order.
+
+    Shared by the build/enter/exit local runners; the ordering key is the global
+    per-kind sequence the decorator assigned at definition time (runner-protocol
+    §10). Mirrors the runner's ``execute._marked_hooks``.
+    """
+    hooks = []
+    for attr_name in dir(type(instance)):
+        attr = getattr(type(instance), attr_name, None)
+        if callable(attr) and getattr(attr, marker, False):
+            hooks.append((getattr(attr, seq_marker, 0), attr_name))
+    hooks.sort()
+    for _seq, attr_name in hooks:
+        getattr(instance, attr_name)()
+
+
+def _run_build_hooks(instance: Any) -> None:
+    """Run @bladekit.build hooks in ``__forge_build_seq__`` order (runtime fallback)."""
+    _run_marked_hooks(instance, "__forge_build__", "__forge_build_seq__")
+
+
+def _run_enter_hooks(instance: Any) -> None:
+    """Run @bladekit.enter hooks in ``__forge_enter_seq__`` order (runner-protocol §10)."""
+    _run_marked_hooks(instance, "__forge_enter__", "__forge_enter_seq__")
+
+
+def _run_exit_hooks(instance: Any) -> None:
+    """Run @bladekit.exit hooks in ``__forge_exit_seq__`` order (runner-protocol §10)."""
+    _run_marked_hooks(instance, "__forge_exit__", "__forge_exit_seq__")

bladekit/_constants.py

@@ -0,0 +1,121 @@
+"""Contract-derived constants.
+
+Single source of the numbers and strings pinned by contracts/conventions.md,
+contracts/openapi.yaml and contracts/runner-protocol.md. Keeping them in one
+module makes it obvious when an implementation value is normative rather than
+arbitrary.
+"""
+
+from __future__ import annotations
+
+# --- Limits (conventions.md §6) ---------------------------------------------
+
+# Raw binary (pre-base64) inline payload ceiling: 1 MiB. Above this, the object
+# store flow (pl_ payload) is mandatory.
+INLINE_PAYLOAD_MAX_BYTES = 1_048_576
+
+# Compressed bundle (tar.gz) ceiling: 256 MiB.
+BUNDLE_MAX_BYTES = 256 * 1024 * 1024
+
+# Pagination.
+DEFAULT_PAGE_LIMIT = 50
+MAX_PAGE_LIMIT = 200
+
+# --- Defaults for ResourceSpec (openapi.yaml ResourceSpec) ------------------
+
+DEFAULT_CPU_MILLICORES = 1000
+# 16 GiB: a sane floor for ML workloads. Raised from 4096 (4 GiB) after a
+# real-GPU validation where loading a 7B model was OOM-killed by the memory
+# cgroup under the old default. Kept in lockstep with the control-plane
+# default (state.DefaultMemoryMB). Set memory= explicitly to override.
+DEFAULT_MEMORY_MB = 16384
+DEFAULT_TIMEOUT_SECONDS = 3600
+DEFAULT_IDLE_TIMEOUT_SECONDS = 60
+
+# --- Serialization format (conventions.md §8) -------------------------------
+
+PAYLOAD_FORMAT = "cloudpickle"
+
+# --- Terminal states (conventions.md §7) ------------------------------------
+
+RUN_TERMINAL_STATES = frozenset({"succeeded", "failed", "cancelled", "lost"})
+CALL_TERMINAL_STATES = frozenset({"succeeded", "failed", "cancelled", "lost"})
+
+# Ordered run lifecycle, for progress rendering.
+RUN_PROGRESS_ORDER = (
+    "pending",
+    "scheduled",
+    "starting",
+    "running",
+)
+
+# --- Default network endpoints ----------------------------------------------
+
+# The public control plane: what `pip install forge-shadow` should be able to
+# talk to with nothing configured. This was `http://localhost:8080` — an
+# orchestration dev convention that is nobody's plane once the package is
+# installed, so `blade setup` with no --api-url died on a refused connection.
+#
+# Everything that runs against another plane already says so and does not reach
+# this default: the runner injects FORGE_API_URL into the container, the e2e
+# drivers and the CI jobs require it, and a developer running the control plane
+# locally exports it (or `blade token set --api-url http://localhost:8080`).
+# Env and config file both win over this value — see config.load_config.
+DEFAULT_API_URL = "https://cp.run.blade.sh"
+
+# --- Polling for .remote()/.get() (openapi GET /v1/calls/{id} guidance) -----
+
+POLL_INITIAL_INTERVAL = 0.2
+POLL_MAX_INTERVAL = 2.0
+
+# --- map/queue/dict limits (conventions.md §6) -------------------------------
+
+# map() inputs per POST /v1/maps/{id}/inputs (≤ 1000 per request).
+MAP_INPUT_BATCH_SIZE = 1000
+
+# Maximum inputs per map invocation (1 M).
+MAP_MAX_INPUTS = 1_000_000
+
+# Results page limit for GET /v1/maps/{id}/results (≤ 200, conventions §6).
+MAP_RESULTS_PAGE_LIMIT = 200
+
+# Polling intervals for map results (seconds).
+MAP_POLL_INTERVAL = 0.3
+MAP_POLL_MAX_INTERVAL = 3.0
+
+# --- dynamic batching (@bladekit.batched) ---------------------------------------
+
+# A batched function collects individual calls into one invocation that runs the
+# user function once over the whole batch. A batch is dispatched as soon as it
+# reaches max_batch_size inputs OR the per-batch wait window elapses.
+#
+# BATCH_MAX_SIZE_LIMIT is the platform serving ceiling (max_concurrent_inputs
+# BETWEEN 1 AND 100 in the schema), NOT an arbitrary cap: a replica fills a batch
+# by pulling calls concurrently, one runner worker per pending call, so the batch
+# can never grow past the replica's serving concurrency. Accepting a larger
+# max_batch_size here would silently cap the real batch at 100 and force every
+# batch to wait the full window (the size trigger would be unreachable), so the
+# decorator rejects anything above the ceiling instead. Mirrored by the control
+# plane (runs.go batchServingCeiling) and the runner (config.max_concurrent_inputs).
+BATCH_MAX_SIZE_LIMIT = 100  # ceiling for max_batch_size (== serving concurrency)
+BATCH_WAIT_MS_LIMIT = 600_000  # ceiling for wait_ms (10 minutes)
+
+# priority range (conventions §6 — 0–9, higher = more urgent).
+PRIORITY_MIN = 0
+PRIORITY_MAX = 9
+PRIORITY_DEFAULT = 5
+
+# retries (conventions §6).
+RETRIES_MAX = 10
+RETRIES_BACKOFF_INITIAL_MAX = 300
+RETRIES_BACKOFF_MAX_MAX = 3600
+RETRIES_BACKOFF_FACTOR_MIN = 1.0
+RETRIES_BACKOFF_FACTOR_MAX = 10.0
+
+# gpu_count (conventions §6 — borne relevée 1→8, additif).
+GPU_COUNT_MIN = 0
+GPU_COUNT_MAX = 8
+
+# Queue/Dict limits.
+QUEUE_GET_TIMEOUT_MAX = 600
+DICT_KEY_MAX_BYTES = 256