letify 2.3.0__tar.gz → 2.4.0__tar.gz

{letify-2.3.0 → letify-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.3.0
+Version: 2.4.0
 Summary: Declarations that become infrastructure.
 Project-URL: Homepage, https://github.com/DarkPyonix/letify
 Project-URL: Documentation, https://github.com/DarkPyonix/letify/tree/main/docs

{letify-2.3.0 → letify-2.4.0}/letify/__init__.py

@@ -62,7 +62,7 @@ remote: Final = Host.remote
 # The enum class stays importable from letify.declare.instance for letify's own use.
 del Host
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"
 
 
 def fetch(tensor):  # type: ignore[no-untyped-def]

{letify-2.3.0 → letify-2.4.0}/letify/providers/base.py

@@ -383,6 +383,17 @@ class Provider(abc.ABC):
         """
         return None
 
+    @property
+    def fallback_mib_per_s(self) -> float:
+        """What this provider's own fallback carries, or 0 when it is not known.
+
+        Spec "A floor rejection never picks something slower": a link the floor rejected
+        is kept when it beats this, because refusing a slow link only makes sense when
+        what happens instead is better.
+        """
+        value = self.config.option("fallback_mib_per_s")
+        return max(0.0, float(value)) if isinstance(value, (int, float)) else 0.0
+
     @property
     def any_accelerator(self) -> bool:
         """Whether a card other than the one asked for is accepted, from ``any_accelerator``."""

{letify-2.3.0 → letify-2.4.0}/letify/providers/kaggle.py

@@ -103,6 +103,9 @@ FIRESTORE_DOCUMENT = (
 #: runnable. A freshly created empty notebook cancels its own session because it has nothing
 #: to run, so the session is started with one committed cell.
 NOTEBOOK_TITLE = "letify runtime"
+#: What the kernel bridge carries, measured sending 64 MiB on a live account. The
+#: floor compares a link against this rather than refusing one that beats it.
+BRIDGE_MIB_PER_S = 2.0
 NOTEBOOK_BODY = json.dumps(
     {
         "cells": [
@@ -1112,7 +1115,9 @@ class Kaggle(Provider):
     usage_unit = "GPU hours"
     usage_source = "the weekly accelerator quota the official Kaggle CLI's quota command reads"
 
-    default_workspace = "/kaggle/working/letify"
+    # Spec "Kaggle runtimes": /kaggle/working is the notebook's output directory on its
+    # own 19.5 GB device, while /kaggle is the overlay with about 1 TB free.
+    default_workspace = "/kaggle/letify"
 
     def account_note(self) -> str | None:
         """How the account's cookie is doing, for `letify providers`, with no network call.
@@ -1319,6 +1324,7 @@ class Kaggle(Provider):
         return LinkFloor(
             min_bps=float(min_mib) * MIB if isinstance(min_mib, (int, float)) else default.min_bps,
             max_rtt_ms=float(max_rtt) if isinstance(max_rtt, (int, float)) else default.max_rtt_ms,
+            fallback_bps=self.fallback_mib_per_s * MIB,
         )
 
     @property
@@ -1339,7 +1345,15 @@ class Kaggle(Provider):
 
         try:
             link = self.link_over(bridge, name=name)
-        except Exception:
+        except Exception as exc:
+            # Never silent: a session that quietly changed channel is one nobody can
+            # account for. Spec "A floor rejection never picks something slower".
+            from ..transport.announce import printer
+
+            printer(bool(self.__dict__.get("announce", True)))(
+                f"{self.alias}: the kernel bridge is carrying {name} at about "
+                f"{self.fallback_mib_per_s:.1f} MiB/s, because no link was chosen: {exc}"
+            )
             return bridge
         self._links[name] = link
         return PersistentChannel(
@@ -1347,6 +1361,17 @@ class Kaggle(Provider):
             name=name,
         )
 
+    @property
+    def fallback_mib_per_s(self) -> float:
+        """The kernel bridge, measured at 2.0 MiB/s sending 64 MiB on a live account.
+
+        Spec "A floor rejection never picks something slower": without this a punched link
+        at down 8.1 MiB/s was refused for being under the 10 MiB/s floor and 26 GB went
+        over the 2 MiB/s bridge instead.
+        """
+        value = self.config.option("fallback_mib_per_s")
+        return max(0.0, float(value)) if isinstance(value, (int, float)) else BRIDGE_MIB_PER_S
+
     @property
     def transfer_connection_cost_s(self) -> float:
         """A punch, which is what one more stream costs here. Measured at about 10 s."""

{letify-2.3.0 → letify-2.4.0}/letify/transport/pipeline.py

@@ -61,11 +61,39 @@ class LinkFloor:
 
     min_bps: float
     max_rtt_ms: float
+    #: What the provider's own fallback carries, when it is known. A link the floor
+    #: rejected is kept when it beats this. Spec "A floor rejection never picks something
+    #: slower".
+    fallback_bps: float = 0.0
 
     @classmethod
     def default(cls) -> LinkFloor:
         return cls(min_bps=DEFAULT_MIN_MIB_PER_S * MIB, max_rtt_ms=DEFAULT_MAX_RTT_MS)
 
+    def kept_below(self, result: ProbeResult, floored: list[str]) -> str | None:
+        """Why a link the floor rejected is used anyway, or None when it is not.
+
+        Spec "A floor rejection never picks something slower".
+        """
+        if not floored or not self.beats_fallback(result):
+            return None
+        return (
+            f"kept below the floor, because the fallback carries "
+            f"{self.fallback_bps / MIB:.1f} MiB/s"
+        )
+
+    def beats_fallback(self, result: ProbeResult) -> bool:
+        """Whether this probe is faster than the path that would be used instead.
+
+        Spec "A floor rejection never picks something slower": the floor refuses a slow
+        link so a slow link is not used, which is only right when what happens instead is
+        better. A provider with no measurable fallback has nothing to compare against, so
+        the answer is False and the rejection stands.
+        """
+        if not self.fallback_bps:
+            return False
+        return result.upload_bps > self.fallback_bps and result.download_bps > self.fallback_bps
+
     def violations(self, result: ProbeResult) -> list[str]:
         """Each direction, or the round trip, that the probe failed to clear."""
         found = _below(
@@ -312,6 +340,10 @@ class Pipeline:
                 return link
             if measured is not None:
                 floored = self.floor.violations(measured)
+                kept = self.floor.kept_below(measured, floored)
+                if kept:
+                    self._say(f"{link.strategy} {kept}")
+                    floored = []
                 if floored:
                     self._say(f"rejected {link.strategy}: below the floor: {', '.join(floored)}")
                     _close(link)
@@ -389,6 +421,10 @@ class Pipeline:
             _close(link)
             return None
         floored = self.floor.violations(measured)
+        kept = self.floor.kept_below(measured, floored)
+        if kept:
+            self._say(f"cached {name} {kept}")
+            floored = []
         if floored:
             self._say(f"cached {name} rejected: below the floor: {', '.join(floored)}")
             reasons.append(f"{name}: below the floor: {', '.join(floored)}")
@@ -573,6 +609,10 @@ class Pipeline:
             else:
                 if measured is not None:
                     floored = self.floor.violations(measured)
+                    kept = self.floor.kept_below(measured, floored)
+                    if kept:
+                        self._say(f"{link.strategy} {kept}")
+                        floored = []
                     if floored:
                         below = f"{link.strategy}: below the floor: {', '.join(floored)}"
                         self._say(f"rejected {below}")
@@ -598,6 +638,10 @@ class Pipeline:
         above_floor: list[tuple[Any, ProbeResult]] = []
         for link, measured in probed:
             floored = self.floor.violations(measured)
+            kept = self.floor.kept_below(measured, floored)
+            if kept:
+                self._say(f"{link.strategy} {kept}")
+                floored = []
             if floored:
                 self._say(f"rejected {link.strategy}: below the floor: {', '.join(floored)}")
                 below = f"{link.strategy}: below the floor: {', '.join(floored)}"

{letify-2.3.0 → letify-2.4.0}/letify-core/Cargo.lock

@@ -138,7 +138,7 @@ dependencies = [
 
 [[package]]
 name = "letify-agent"
-version = "2.3.0"
+version = "2.4.0"
 dependencies = [
  "letify-wire",
  "libloading",
@@ -146,7 +146,7 @@ dependencies = [
 
 [[package]]
 name = "letify-driver"
-version = "2.3.0"
+version = "2.4.0"
 dependencies = [
  "letify-wire",
 ]
@@ -164,7 +164,7 @@ dependencies = [
 
 [[package]]
 name = "letify-wire"
-version = "2.3.0"
+version = "2.4.0"
 
 [[package]]
 name = "libc"

{letify-2.3.0 → letify-2.4.0}/letify-core/Cargo.toml

@@ -8,7 +8,7 @@ resolver = "3"
 members = ["letify-wire", "letify-driver", "letify-agent", "letify-quic"]
 
 [workspace.package]
-version = "2.3.0"
+version = "2.4.0"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/DarkPyonix/letify"

{letify-2.3.0 → letify-2.4.0}/letify-ext/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "letify-status",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "letify-status",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "license": "SEE LICENSE IN LICENSE",
       "devDependencies": {
         "@types/node": "^18.19.0",

{letify-2.3.0 → letify-2.4.0}/letify-ext/package.json

@@ -2,7 +2,7 @@
   "name": "letify-status",
   "displayName": "letify Status",
   "description": "letify quota and GPU activity in the status bar, read from the letify CLI.",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "publisher": "darkpyonix",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

{letify-2.3.0 → letify-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "letify"
-version = "2.3.0"
+version = "2.4.0"
 description = "Declarations that become infrastructure."
 readme = "README.md"
 requires-python = ">=3.11"

{letify-2.3.0 → letify-2.4.0}/tests/test_kaggle.py

@@ -1232,3 +1232,65 @@ def test_a_kaggle_account_is_asked_for_its_sessions(launcher_from, fake_kaggle_c
     row = rows.get("kaggle_a")
     assert row is not None, rows
     assert row.get("reason") != "session discovery is not supported"
+
+
+def test_the_kaggle_workspace_is_not_under_the_output_directory() -> None:
+    """Spec "Kaggle": /kaggle/working is the output directory, on its own 19.5 GB device.
+
+    Measured on a live session: /kaggle/working has 19.5 GB against Kaggle's 20 GB output
+    limit, while /kaggle is the overlay with 1069.9 GB free. A venv and a call's blobs are
+    not the notebook's output, and a 26 GB dataset does not fit on the smaller one.
+    /kaggle/temp, which looks like the obvious scratch path, does not exist on the image.
+    """
+    provider = kaggle_provider()
+    assert provider.workspace_root == "/kaggle/letify"
+    assert "/kaggle/working" not in provider.workspace_root
+
+
+def test_a_kaggle_account_can_still_name_its_own_workspace(config_file) -> None:
+    """Spec: an account that wants another path sets workspace."""
+    from conftest import provider_of
+
+    from letify.providers import Kaggle
+
+    provider = provider_of(Kaggle, "kaggle_a", workspace="/kaggle/working/letify")
+    assert provider.workspace_root == "/kaggle/working/letify"
+
+
+def test_the_kaggle_floor_knows_what_the_bridge_carries() -> None:
+    """Spec "A floor rejection never picks something slower": the bridge is 2.0 MiB/s."""
+    from letify.transport.pipeline import MIB
+
+    provider = kaggle_provider()
+    assert provider.fallback_mib_per_s == 2.0
+    assert provider.link_floor.fallback_bps == 2.0 * MIB
+
+
+def test_an_account_can_say_what_its_bridge_carries(config_file) -> None:
+    """Spec: an account overrides it with fallback_mib_per_s."""
+    from conftest import provider_of
+
+    from letify.providers import Kaggle
+
+    provider = provider_of(Kaggle, "kaggle_a", fallback_mib_per_s=5)
+    assert provider.fallback_mib_per_s == 5.0
+
+
+def test_falling_back_to_the_bridge_says_so(monkeypatch, capsys) -> None:
+    """Spec: taking the fallback is never silent.
+
+    A live session spent 25 minutes on the bridge with no line saying which channel it was
+    on, because the fallback was reached through a bare `except Exception: return bridge`.
+    """
+    provider = kaggle_provider()
+    provider.announce = True
+
+    def refuse(channel, name=None):
+        raise RuntimeError("every strategy was below the floor")
+
+    monkeypatch.setattr(provider, "link_over", refuse)
+    bridge = object()
+    assert provider.channel_over(bridge, name="k-1") is bridge
+    err = capsys.readouterr().err
+    assert "the kernel bridge is carrying k-1" in err
+    assert "2.0 MiB/s" in err

{letify-2.3.0 → letify-2.4.0}/tests/test_transport.py

@@ -901,3 +901,35 @@ def test_a_platform_without_the_kernel_copy_still_splices(monkeypatch) -> None:
     left.close()
     near.close()
     thread.join(10)
+
+
+def test_a_link_below_the_floor_is_kept_when_the_fallback_is_slower(isolated_home, capsys) -> None:
+    """Spec "A floor rejection never picks something slower".
+
+    A live Kaggle session refused a punched link at down 8.1 MiB/s for being under the
+    10 MiB/s floor and then carried 26 GB over the 2 MiB/s kernel bridge instead, which is
+    the opposite of what the floor is for.
+    """
+    floor = LinkFloor(min_bps=10 * MIB, max_rtt_ms=300.0, fallback_bps=2 * MIB)
+    punch = FakeStrategy("tcp_punch", 2, result=result(8.1, 8.1, rtt=190.0))
+    link = pipeline([punch], floor=floor).connect()
+    assert link.strategy == "tcp_punch"
+    err = capsys.readouterr().err
+    assert "kept below the floor" in err
+    assert "2.0 MiB/s" in err
+
+
+def test_a_link_slower_than_the_fallback_is_still_refused(isolated_home) -> None:
+    """Spec: only a link that beats the fallback is kept; a slower one is given up."""
+    floor = LinkFloor(min_bps=10 * MIB, max_rtt_ms=300.0, fallback_bps=2 * MIB)
+    punch = FakeStrategy("tcp_punch", 2, result=result(8.1, 0.5, rtt=190.0))
+    with pytest.raises(letify.ProviderUnavailable):
+        pipeline([punch], floor=floor).connect()
+
+
+def test_a_provider_with_no_known_fallback_keeps_failing_below_the_floor(isolated_home) -> None:
+    """Spec: a provider with no measurable fallback has nothing to compare against."""
+    floor = LinkFloor(min_bps=10 * MIB, max_rtt_ms=300.0)
+    punch = FakeStrategy("tcp_punch", 2, result=result(8.1, 8.1, rtt=190.0))
+    with pytest.raises(letify.ProviderUnavailable):
+        pipeline([punch], floor=floor).connect()