bladekit 4.5.0__py3-none-any.whl

bladekit/_cron.py

@@ -0,0 +1,88 @@
+"""bladekit.Cron — cron schedule declaration for @app.function.
+
+A ``Cron`` object declares a cron schedule that the control plane's cron
+scheduler will use to trigger the decorated function automatically.
+
+Usage::
+
+    @app.function(schedule=bladekit.Cron("0 3 * * *"))
+    def nightly_job():
+        ...
+
+The cron expression must be a standard 5-field UTC cron string
+(``minute hour day-of-month month day-of-week``). Validation is done both
+locally (basic 5-field check) and by the server (CRON_EXPRESSION_INVALID).
+
+The schedule is part of the deployment manifest (deploy path). For a
+``blade run`` path, the schedule is stored in the function's metadata
+but not automatically triggered — the control plane only triggers registered
+crons in a deployed app.
+
+Limits (conventions.md §6):
+- Up to 64 crons per deployment.
+- Cron history retained for 90 days or 1000 executions per schedule.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+# Very lightweight validation: 5 space-separated fields of printable non-space
+# chars. The server performs authoritative validation (CRON_EXPRESSION_INVALID).
+_CRON_RE = re.compile(
+    r"^(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)$"
+)
+
+
+class Cron:
+    """A cron schedule for use with ``@app.function(schedule=bladekit.Cron(...))``.
+
+    Args:
+        expression: A 5-field UTC cron expression, e.g. ``"0 3 * * *"`` (every
+            day at 03:00 UTC), ``"*/5 * * * *"`` (every 5 minutes).
+        overlap_policy: What to do if a previous execution is still running when
+            the next one is due. ``"skip"`` (default): skip the new trigger;
+            ``"allow"``: start the new trigger alongside the existing one.
+
+    The expression is validated locally (structure only) and by the server on
+    deployment (``CRON_EXPRESSION_INVALID`` with ``details.field`` on error).
+    """
+
+    def __init__(
+        self,
+        expression: str,
+        *,
+        overlap_policy: str = "skip",
+    ) -> None:
+        if not isinstance(expression, str):
+            raise TypeError(f"Cron expression must be a str, got {type(expression).__name__}")
+        expression = expression.strip()
+        if not _CRON_RE.match(expression):
+            from . import exceptions as exc
+
+            raise exc.InvalidArgumentError(
+                "CRON_EXPRESSION_INVALID",
+                f"cron expression {expression!r} must have exactly 5 space-separated "
+                "fields (minute hour day-of-month month day-of-week)",
+            )
+        valid_policies = ("skip", "allow")
+        if overlap_policy not in valid_policies:
+            from . import exceptions as exc
+
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"overlap_policy must be one of {valid_policies}, got {overlap_policy!r}",
+            )
+        self.expression = expression
+        self.overlap_policy = overlap_policy
+
+    def __repr__(self) -> str:
+        return f"bladekit.Cron({self.expression!r})"
+
+    def to_dict(self) -> dict:
+        """Serialize for inclusion in a deployment manifest or run create body."""
+        return {
+            "expression": self.expression,
+            "overlap_policy": self.overlap_policy,
+        }

bladekit/_dict.py

@@ -0,0 +1,174 @@
+"""bladekit.Dict — distributed key-value store.
+
+Persistent, backed by Postgres on the control plane. Used for sharing state
+between remote workers (e.g. config broadcast, progress tracking, dedup sets).
+
+Protocol (conventions.md §14.5):
+- get(key): returns the value or None if absent (never raises NotFoundError).
+- put(key, value): upsert — last-write-wins per key.
+- contains(key): check existence without fetching the value.
+- delete(key): remove a key (idempotent — no error if absent).
+- [] accessor: d["key"] → get; d["key"] = v → put.
+- from_name(name): get-or-create by name.
+
+Limits (conventions.md §6):
+- Up to 100,000 entries per Dict.
+- Key: UTF-8 string, ≤ 256 bytes (DICT_KEY_TOO_LARGE).
+- Value: ≤ 1 MiB inline; object store beyond (DICT_VALUE_TOO_LARGE).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Dict:
+    """A distributed key-value store persistent in the AI Fabric control plane.
+
+    Usage::
+
+        d = bladekit.Dict.from_name("checkpoints")
+        d["step"] = 42
+        step = d["step"]   # 42
+        "step" in d        # True
+
+    Keys are UTF-8 strings (≤ 256 bytes). Values are serialized with cloudpickle.
+    The dict is identified by name; ``from_name`` is idempotent (get-or-create).
+    ``put`` is an upsert: last-write-wins per key (no transactions across keys).
+    """
+
+    def __init__(self, name: str, client: Any) -> None:
+        self._name = name
+        self._client = client
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return f"bladekit.Dict(name={self._name!r})"
+
+    @classmethod
+    def from_name(cls, name: str, *, create_if_missing: bool = False) -> "Dict":
+        """Reference a Dict by name (get-or-create on first use).
+
+        No round-trip here: the server creates the Dict lazily on the first
+        put/get (openapi.yaml: "get-or-create by name at usage time"). Two
+        references with the same name address the same store. ``create_if_missing``
+        is accepted for parity with ``Volume.from_name`` but is a no-op.
+        """
+        _ = create_if_missing
+        from ._client import Client
+        from .config import load_config
+        from . import exceptions as exc_mod
+
+        cfg = load_config()
+        if not cfg.token:
+            raise exc_mod.AuthenticationError(
+                "UNAUTHENTICATED",
+                "no token configured: run `blade token set <token>` or set FABRIC_TOKEN",
+            )
+        return cls(name, Client(cfg.api_url, cfg.token))
+
+    @classmethod
+    def _from_client(cls, name: str, client: Any) -> "Dict":
+        """Create a Dict object backed by an existing client (for tests)."""
+        return cls(name, client)
+
+    # -- key validation ---------------------------------------------------
+
+    @staticmethod
+    def _validate_key(key: str) -> None:
+        from . import exceptions as exc_mod
+
+        if not isinstance(key, str):
+            raise exc_mod.InvalidArgumentError(
+                "INVALID_ARGUMENT", f"Dict key must be a str, got {type(key).__name__}"
+            )
+        encoded = key.encode("utf-8")
+        if len(encoded) > 256:
+            raise exc_mod.InvalidArgumentError(
+                "DICT_KEY_TOO_LARGE",
+                f"Dict key is {len(encoded)} bytes (UTF-8), exceeds the 256-byte limit",
+            )
+
+    # -- operations -------------------------------------------------------
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return the value for ``key``, or ``default`` if absent."""
+        self._validate_key(key)
+        from ._serialize import decode_payload_out, loads
+
+        # DictGetResponse: {found, value}. found=false ⇒ absent (200, not 404).
+        resp = self._client.dict_get(self._name, key)
+        if not resp.get("found"):
+            return default
+        payload = resp.get("value")
+        if payload is None:
+            return default
+        raw = decode_payload_out(payload, fetch=self._client.download_presigned)
+        # put() serialized (value,) as args; unwrap.
+        result = loads(raw)
+        if isinstance(result, tuple) and len(result) == 2:
+            args, kwargs = result
+            if isinstance(args, tuple) and len(args) == 1 and not kwargs:
+                return args[0]
+        return result
+
+    def put(self, key: str, value: Any) -> None:
+        """Upsert ``key`` with ``value`` (last-write-wins)."""
+        self._validate_key(key)
+        from ._serialize import dumps_args, make_payload_in
+
+        raw = dumps_args((value,), {})
+        payload_in, object_bytes = make_payload_in(raw)
+        if object_bytes is not None:
+            decl = self._client.create_payload(
+                payload_in["size_bytes"], payload_in["sha256"]
+            )
+            self._client.upload_to_presigned(
+                decl["put_url"], object_bytes, "application/octet-stream"
+            )
+            payload_in["payload_id"] = decl["payload_id"]
+        self._client.dict_put(self._name, key, payload_in)
+
+    def contains(self, key: str) -> bool:
+        """Return True if ``key`` exists in the dict."""
+        self._validate_key(key)
+        resp = self._client.dict_get(self._name, key)
+        return bool(resp.get("found", False))
+
+    def delete(self, key: str) -> None:
+        """Remove ``key`` from the dict (idempotent — no error if absent)."""
+        self._validate_key(key)
+        from . import exceptions as exc_mod
+
+        try:
+            self._client.dict_delete(self._name, key)
+        except exc_mod.NotFoundError:
+            pass  # idempotent — missing key is not an error
+
+    # -- Pythonic accessors ------------------------------------------------
+
+    def __getitem__(self, key: str) -> Any:
+        result = self.get(key)
+        if result is None and not self.contains(key):
+            raise KeyError(key)
+        return result
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.put(key, value)
+
+    def __delitem__(self, key: str) -> None:
+        if not self.contains(key):
+            raise KeyError(key)
+        self.delete(key)
+
+    def __contains__(self, key: object) -> bool:
+        if not isinstance(key, str):
+            return False
+        return self.contains(key)
+
+    def delete_store(self) -> None:
+        """Delete the entire Dict store."""
+        self._client.delete_dict(self._name)

bladekit/_env.py

@@ -0,0 +1,98 @@
+"""Environment variable lookup for the SDK and the in-container runtime.
+
+The SDK reads ``FABRIC_<NAME>`` first and falls back to the legacy
+``FORGE_<NAME>`` (PAAS-771). The fallback is load-bearing, not cosmetic: the
+control plane still injects ``FORGE_*`` into every container (FORGE_API_URL,
+FORGE_RUNNER_TOKEN, FORGE_VOLUMES, FORGE_SERVER_PORT, ...), and existing users
+have ``FORGE_TOKEN`` / ``FORGE_API_URL`` in their shells and CI. Drop the
+fallback only once the server injects ``FABRIC_*`` and the old names have been
+deprecated for a release cycle.
+
+An empty value counts as unset, matching how the SDK has always treated these
+variables (``if os.environ.get(...)``).
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Optional, Set, Tuple
+
+PREFIX = "FABRIC_"
+LEGACY_PREFIX = "FORGE_"
+# Every prefix the runtime owns. User-defined image env layers may not use them
+# (see Image.env), or a user value could shadow what the platform injects.
+RESERVED_PREFIXES = (PREFIX, LEGACY_PREFIX)
+
+
+# Names already warned about (FABRIC_X and FORGE_X both set, different values),
+# so a variable read on every request warns once per process.
+_conflicts_warned: Set[str] = set()
+
+
+def lookup(name: str) -> Tuple[Optional[str], Optional[str]]:
+    """Return ``(value, variable)`` for ``FABRIC_<name>``, else ``FORGE_<name>``.
+
+    ``variable`` is the name actually read (for "where did this come from"
+    messages such as ``blade token show``); both are None when neither is set.
+    When both are set to different values FABRIC_* wins and a ``UserWarning``
+    says so (once per name per process).
+    """
+    value = os.environ.get(PREFIX + name)
+    legacy = os.environ.get(LEGACY_PREFIX + name)
+    if value:
+        if legacy and legacy != value and name not in _conflicts_warned:
+            _conflicts_warned.add(name)
+            warnings.warn(
+                f"both {PREFIX}{name} and {LEGACY_PREFIX}{name} are set, to different "
+                f"values; using {PREFIX}{name} ({LEGACY_PREFIX}{name} is the deprecated "
+                "spelling).",
+                UserWarning,
+                stacklevel=3,
+            )
+        return value, PREFIX + name
+    if legacy:
+        return legacy, LEGACY_PREFIX + name
+    return None, None
+
+
+def get(name: str, default: Optional[str] = None) -> Optional[str]:
+    """Value of ``FABRIC_<name>``, else ``FORGE_<name>``, else ``default``."""
+    value, _ = lookup(name)
+    return value if value is not None else default
+
+
+def flag(name: str) -> bool:
+    """Boolean variable: set and not one of "", 0, false, no, off."""
+    value = get(name)
+    return value is not None and value.strip().lower() not in ("", "0", "false", "no", "off")
+
+
+# Variables the platform injects into a container for USER code to read
+# (documented as FABRIC_*). The server still injects them as FORGE_* (PAAS-771),
+# so importing the SDK copies each one to its FABRIC_* name when that is unset —
+# `os.environ["FABRIC_SERVER_PORT"]` then works in a function body and in the
+# subprocesses it spawns (e.g. `vllm serve --port $FABRIC_SERVER_PORT`).
+# Credentials are deliberately absent: FORGE_RUNNER_TOKEN is scrubbed by the
+# runner and must not be resurrected under another name.
+MIRRORED_RUNTIME_VARS = (
+    "SERVER_PORT",
+    "VOLUMES",
+    "PREEMPT_GRACE_SECONDS",
+    "MAX_SESSION_SECONDS",
+    "TURN_URL",
+    "TURNS_URL",
+    "TURN_SECRET",
+)
+
+
+def mirror_legacy_runtime_env() -> None:
+    """Set ``FABRIC_<NAME>`` from ``FORGE_<NAME>`` for :data:`MIRRORED_RUNTIME_VARS`.
+
+    Never overwrites a FABRIC_* value already present; a no-op outside a
+    container, where none of these is set.
+    """
+    for name in MIRRORED_RUNTIME_VARS:
+        legacy = os.environ.get(LEGACY_PREFIX + name)
+        if legacy and not os.environ.get(PREFIX + name):
+            os.environ[PREFIX + name] = legacy