aether-robotics 5.2.2__tar.gz → 5.2.3__tar.gz

{aether_robotics-5.2.2/aether_robotics.egg-info → aether_robotics-5.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-robotics
-Version: 5.2.2
+Version: 5.2.3
 Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
 Author: Chahel Paatur
 License: MIT

aether_robotics-5.2.3/VERSION

@@ -0,0 +1 @@
+5.2.3

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/__init__.py

@@ -1,4 +1,11 @@
-__version__ = "5.2.2"
+import time as _time
+
+#: Wall clock at the very first moment AETHER code runs. boot_timer measures
+#: from here so "python_imports" is attributed rather than showing up as an
+#: unexplained gap between the phase total and wall clock (v5.2.3).
+_IMPORT_START = _time.time()
+
+__version__ = "5.2.3"
 __author__ = "Chahel Paatur"
 
 #: Where users should actually be sent. v5.1.2: the GitHub repository is

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/app.py

@@ -907,6 +907,7 @@ def _extract_key_facts(output) -> str:
 
 def run_agent(args) -> None:
     """Real agent mode: prompt-driven loop with live tool execution."""
+    from aether.core import boot_timer
     from aether.core.analytics import check_consent_or_prompt
     check_consent_or_prompt()   # v4.1.0.2: consent gate on every entrypoint
     from aether.core.tool_registry import ToolRegistry, ToolResult, register_built_tools
@@ -942,14 +943,15 @@ def run_agent(args) -> None:
     # ── Step 2: Banner already printed in main() ──────────────────────
 
     # ── Step 3: AutoUpdater ───────────────────────────────────────────
-    updater = AutoUpdater()
+    with boot_timer.phase("autoupdater"):
+        updater = AutoUpdater()
     AutoUpdater.ensure_version_file(_PROJECT_ROOT)
     updater.run(auto_update=auto_update, no_update=no_update)
 
     # ── Step 4: Capability Discovery ──────────────────────────────────
-    from aether.core import boot_timer
     discovery = ToolDiscovery()
-    discovery.discover()
+    with boot_timer.phase("discovery"):
+        discovery.discover()
     # v5.1.1 UI 1: the ~70-line inventory is a debugging surface, not a boot
     # screen. It stays one `capabilities` command (or AETHER_VERBOSE=1) away,
     # and `aether doctor` is untouched.
@@ -957,8 +959,10 @@ def run_agent(args) -> None:
         discovery.print_summary()
 
     # ── Step 5: AutoInstaller ─────────────────────────────────────────
-    installer = AutoInstaller(discovery.manifest)
-    packages_installed = installer.run(auto_install=auto_install, no_install=no_install)
+    with boot_timer.phase("autoinstaller"):
+        installer = AutoInstaller(discovery.manifest)
+        packages_installed = installer.run(auto_install=auto_install,
+                                           no_install=no_install)
 
     # ── Step 6: Re-run discovery if anything was installed ────────────
     if packages_installed:
@@ -1080,8 +1084,9 @@ def run_agent(args) -> None:
     planner = Planner()
 
     # ── Step 7: Build Tools + Navigation Engine ───────────────────────
-    builder = ToolBuilder(discovery.manifest)
-    built_tools = builder.build_all()
+    with boot_timer.phase("tool_build"):
+        builder = ToolBuilder(discovery.manifest)
+        built_tools = builder.build_all()
     _print_activity("TOOLS", builder.build_summary())
 
     # OLED startup animation (only on Pi with real hardware attached)
@@ -1093,7 +1098,8 @@ def run_agent(args) -> None:
         except Exception as e:
             _print_activity("OLED", f"startup animation failed: {e}")
 
-    nav_engine = NavigationEngine(discovery.manifest, tools=built_tools)
+    with boot_timer.phase("nav_engine"):
+        nav_engine = NavigationEngine(discovery.manifest, tools=built_tools)
     _register_gpio_cleanup(nav_engine)   # drain PWMs + GPIO.cleanup on exit
     nav_actions = nav_engine.available_actions()
     _print_activity("NAV", f"Level {nav_engine.level} ({nav_engine.level_name}) — "

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/core/auto_updater.py

@@ -87,6 +87,26 @@ class AutoUpdater:
                 pass
         return CURRENT_VERSION
 
+    #: v5.2.3: the update check is CACHED for a day. It used to hit PyPI on
+    #: every boot — network I/O on the critical path, which is exactly the
+    #: user>>real gap that made a 50s boot only 21s of CPU. A version check is
+    #: not worth a single millisecond of a robot's startup.
+    _CHECK_TTL_S = 24 * 3600
+
+    def _cached_check(self):
+        try:
+            from aether.core.providers._cache import cache_get
+            return cache_get("update:latest", self._CHECK_TTL_S)
+        except Exception:
+            return None
+
+    def _remember_check(self, payload) -> None:
+        try:
+            from aether.core.providers._cache import cache_set
+            cache_set("update:latest", payload)
+        except Exception:
+            pass
+
     def _fetch_latest_release(self) -> Optional[Dict]:
         """Latest published version, from PyPI.
 
@@ -98,6 +118,11 @@ class AutoUpdater:
 
         Returns the same {"tag_name", "body"} shape the callers already expect.
         """
+        cached = self._cached_check()
+        if isinstance(cached, dict) and cached.get("tag_name"):
+            return cached
+        if os.environ.get("AETHER_NO_UPDATE_CHECK"):
+            return None
         try:
             import urllib.request
             with urllib.request.urlopen(_PYPI_JSON_URL,
@@ -108,8 +133,11 @@ class AutoUpdater:
         version = str(info.get("version") or "").strip()
         if not version:
             return None
-        return {"tag_name": f"v{version}",
-                "body": f"See {info.get('project_url') or 'PyPI'} for details."}
+        payload = {"tag_name": f"v{version}",
+                   "body": f"See {info.get('project_url') or 'PyPI'} "
+                           f"for details."}
+        self._remember_check(payload)
+        return payload
 
     def check_for_update(self) -> Optional[str]:
         """Check GitHub releases for a newer version.

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/core/boot_timer.py

@@ -75,6 +75,56 @@ def summary_line(limit: int = 6) -> str:
     return " · ".join(parts) + f" · total {total_ms():.0f}ms"
 
 
+#: Wall clock at interpreter start, so the report covers process start to
+#: prompt rather than only the phases someone remembered to wrap.
+try:
+    from aether import _IMPORT_START as _PROCESS_START
+except Exception:
+    _PROCESS_START = time.time()
+
+#: The measured phases must account for at least this fraction of wall clock.
+#: v5.2.2 shipped a timer that wrapped ONE function and then printed
+#: "total 25ms" for a 50,845ms boot — a claim far worse than no instrumentation,
+#: because it said the problem was solved. If coverage is below this, the
+#: report says so instead of quoting a total it cannot justify.
+COVERAGE_FLOOR = 0.95
+
+
+def wall_ms() -> float:
+    return (time.time() - _PROCESS_START) * 1000.0
+
+
+def coverage() -> float:
+    """Fraction of wall clock the measured phases actually account for."""
+    wall = wall_ms()
+    return (total_ms() / wall) if wall > 0 else 0.0
+
+
+def coverage_note() -> str:
+    """'(wall 50845ms ✓)' or a loud warning that the numbers do not sum."""
+    wall = wall_ms()
+    if coverage() >= COVERAGE_FLOOR:
+        return f"(wall {wall:.0f}ms ✓)"
+    unmeasured = wall - total_ms()
+    return (f"(wall {wall:.0f}ms — ⚠ {unmeasured:.0f}ms UNMEASURED, "
+            f"phases cover only {coverage() * 100:.0f}%)")
+
+
+def record_import_phase() -> None:
+    """Attribute everything before the first timed phase to python_imports.
+
+    Without this the phases never sum to wall clock and the coverage check
+    warns forever, which would train everyone to ignore it — the same way the
+    v5.2.2 "total 25ms" line trained us to believe boot was fast.
+    """
+    if not _enabled or any(p["phase"] == "python_imports" for p in _phases):
+        return
+    already = total_ms()
+    before = wall_ms() - already
+    if before > 0:
+        _phases.insert(0, {"phase": "python_imports", "ms": round(before, 1)})
+
+
 def report() -> None:
     """Print the summary under AETHER_VERBOSE=1 and always emit analytics.
 
@@ -84,9 +134,13 @@ def report() -> None:
     """
     if not _phases:
         return
+    record_import_phase()
     try:
         if os.environ.get("AETHER_VERBOSE"):
-            print(f"  [BOOT] {summary_line()}")
+            for entry in sorted(_phases, key=lambda p: -p["ms"]):
+                print(f"  [BOOT] {entry['phase']:<24} {entry['ms']:>8.0f}ms")
+            print(f"  [BOOT] {'TOTAL':<24} {total_ms():>8.0f}ms "
+                  f"{coverage_note()}")
     except Exception:
         pass
     try:
@@ -94,5 +148,9 @@ def report() -> None:
         for entry in _phases:
             track("boot_latency", {"phase": entry["phase"], "ms": entry["ms"]})
         track("boot_latency", {"phase": "total", "ms": total_ms()})
+        # Coverage travels with the numbers: a total that accounts for 3% of
+        # wall clock must not be read as a fast boot.
+        track("boot_latency", {"phase": "wall", "ms": round(wall_ms(), 1),
+                               "coverage": round(coverage(), 3)})
     except Exception:
         pass

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/core/navigation_engine.py

@@ -149,22 +149,44 @@ class _CameraNav:
     cv2 is not installed.
     """
 
+    @property
+    def _backend_name(self):
+        self._resolve_nav_backend()
+        return self._backend_name_cached
+
+    @property
+    def _backend_mod(self):
+        self._resolve_nav_backend()
+        return self._backend_mod_cached
+
+    def _resolve_nav_backend(self):
+        if self._nav_backend_resolved:
+            return
+        self._nav_backend_resolved = True
+        (self._backend_name_cached,
+         self._backend_mod_cached) = _detect_nav_camera_backend()
+        # Logged here, not in __init__: reading the backend just to name it
+        # was what imported cv2 on every boot.
+        if self._backend_name_cached == "cv2":
+            self._cv2 = self._backend_mod_cached
+            _nav_cam_log.info("Using cv2 backend")
+        elif self._backend_name_cached == "picamera2":
+            _nav_cam_log.info("Using picamera2 backend")
+        else:
+            _nav_cam_log.warning("No camera backend available")
+
     def __init__(self):
-        self._backend_name, self._backend_mod = _detect_nav_camera_backend()
+        # v5.2.3: deferred — this imported cv2 on every boot for a camera the
+        # session may never use.
+        self._backend_name_cached = None
+        self._backend_mod_cached = None
+        self._nav_backend_resolved = False
         self._cv2 = None
         self._cap = None           # cv2 VideoCapture
         self._picam = None         # picamera2 instance
         self._picam_started = False
         self._prev_gray = None
 
-        if self._backend_name == "cv2":
-            self._cv2 = self._backend_mod
-            _nav_cam_log.info("Using cv2 backend")
-        elif self._backend_name == "picamera2":
-            _nav_cam_log.info("Using picamera2 backend")
-        else:
-            _nav_cam_log.warning("No camera backend available")
-
         atexit.register(self.close)
 
     def _ensure_picamera(self) -> Optional[str]:

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/core/tool_builder.py

@@ -187,22 +187,47 @@ class CameraTool:
     Camera is initialized once (singleton) and released on shutdown.
     """
 
+    @property
+    def _backend_name(self):
+        """Resolved on first access (v5.2.3 lazy import)."""
+        self._resolve_backend()
+        return self._backend_name_cached
+
+    @property
+    def _backend(self):
+        self._resolve_backend()
+        return self._backend_cached
+
+    def _resolve_backend(self):
+        if self._backend_resolved:
+            return
+        self._backend_resolved = True
+        (self._backend_name_cached,
+         self._backend_cached) = _detect_camera_backend()
+        # Logged here rather than in __init__: reading the backend just to say
+        # which one it is was what imported cv2 on every boot.
+        if self._backend_name_cached == "cv2":
+            self._cv2 = self._backend_cached
+            _cam_log.info("Using cv2 backend")
+        elif self._backend_name_cached == "picamera2":
+            _cam_log.info("Using picamera2 backend")
+        else:
+            _cam_log.warning(
+                "No camera backend available (neither cv2 nor picamera2)")
+
     def __init__(self):
-        self._backend_name, self._backend = _detect_camera_backend()
+        # v5.2.3: backend detection imports cv2 (or picamera2), which is
+        # ~0.1s on a Mac and far worse on a Pi. Deferred to first camera use —
+        # a session that never touches the camera never pays for it.
+        self._backend_name_cached = None
+        self._backend_cached = None
+        self._backend_resolved = False
         self._cv2 = None
         self._cap = None          # cv2 VideoCapture
         self._picam = None        # picamera2 instance
         self._picam_started = False
         self._prev_frame = None   # for motion detection (numpy array)
 
-        if self._backend_name == "cv2":
-            self._cv2 = self._backend
-            _cam_log.info("Using cv2 backend")
-        elif self._backend_name == "picamera2":
-            _cam_log.info("Using picamera2 backend")
-        else:
-            _cam_log.warning("No camera backend available (neither cv2 nor picamera2)")
-
         atexit.register(self.close)
 
     # ── picamera2 singleton management ────────────────────────────────
@@ -484,15 +509,24 @@ class YOLOTool:
 
     def __init__(self, camera_tool: Optional["CameraTool"] = None):
         self._model = None
+        # v5.2.3: ultralytics is NOT imported here. It pulls torch, so
+        # constructing this tool at boot cost the full torch import for a
+        # detector most sessions never invoke.
         self._ultralytics = None
         self._camera = camera_tool
-        self._has_ultralytics = False
-        try:
-            import ultralytics
-            self._ultralytics = ultralytics
-            self._has_ultralytics = True
-        except ImportError:
-            pass
+        self._ultra_resolved = False
+
+    @property
+    def _has_ultralytics(self) -> bool:
+        """Resolved on first access (v5.2.3 lazy import)."""
+        if not self._ultra_resolved:
+            self._ultra_resolved = True
+            try:
+                import ultralytics
+                self._ultralytics = ultralytics
+            except ImportError:
+                self._ultralytics = None
+        return self._ultralytics is not None
 
     def _ensure_model(self):
         """Lazy-load the YOLOv8n model on first use."""
@@ -907,19 +941,32 @@ class GPUTool:
     """GPU operations via PyTorch. Built when torch + gpu available."""
 
     def __init__(self):
+        # v5.2.3: torch is NOT imported here. Constructing this tool at boot
+        # used to pull the whole of torch — ~0.6s on a dev Mac and 10-20s on a
+        # Pi 4 — before the prompt appeared, for a GPU tool most sessions
+        # never call. Resolution is deferred to first use.
         self._torch = None
         self._device = None
+        self._resolved = False
+
+    def _ensure_torch(self):
+        """Import torch on first actual use. Idempotent."""
+        if self._resolved:
+            return self._torch
+        self._resolved = True
         try:
             import torch
             self._torch = torch
             if torch.cuda.is_available():
                 self._device = torch.device("cuda")
-            elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            elif hasattr(torch.backends, "mps") \
+                    and torch.backends.mps.is_available():
                 self._device = torch.device("mps")
             else:
                 self._device = torch.device("cpu")
         except ImportError:
             pass
+        return self._torch
 
     def get_gpu_memory(self) -> Dict:
         """Report GPU memory usage."""

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/aether/core/tool_discovery.py

@@ -1071,6 +1071,13 @@ class ToolDiscovery:
             print("  [DISCOVERY] Using cached hardware profile "
                   "(fingerprint match)")
             self._manifest = cached
+            # v5.2.3: restore the score too. v5.2.2 returned the manifest
+            # without it, so a cached boot displayed "Capability 0/100" while
+            # a cold boot on the same robot showed 79/100.
+            try:
+                self._score = int(cached.get("capability_score", 0) or 0)
+            except Exception:
+                self._score = 0
             return self._manifest
 
         with boot_timer.phase("platform"):

{aether_robotics-5.2.2 → aether_robotics-5.2.3/aether_robotics.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-robotics
-Version: 5.2.2
+Version: 5.2.3
 Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
 Author: Chahel Paatur
 License: MIT

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aether-robotics"
-version = "5.2.2"
+version = "5.2.3"
 description = "Autonomous multi-agent robotics system with DRL-First Hybrid FDIR"
 readme = "README.md"
 license = {text = "MIT"}

{aether_robotics-5.2.2 → aether_robotics-5.2.3}/tests/test_plan_cache.py

@@ -502,3 +502,142 @@ def test_one_shot_flag_exists_and_skips_the_repl():
     assert "enable_readline" in src[idx_repl - 400:idx_repl] or True
     # and it must not block on the feedback prompt
     assert "session_ended()" in src[idx_oneshot:idx_repl]
+
+
+# ── v5.2.3: instrumentation must not lie ───────────────────────────────
+
+def test_coverage_is_reported_when_phases_do_not_sum():
+    """v5.2.2 wrapped ONE function and printed "total 25ms" for a 50,845ms
+    boot. A total that accounts for 3% of wall clock is worse than no
+    instrumentation, because it says the problem is solved."""
+    from aether.core import boot_timer
+
+    boot_timer.reset(); boot_timer.enable()
+    boot_timer.record("fingerprint", 25.0)
+    boot_timer._PROCESS_START = time.time() - 50.845   # 50,845ms of wall
+
+    assert boot_timer.coverage() < 0.05
+    note = boot_timer.coverage_note()
+    assert "UNMEASURED" in note and "⚠" in note
+    assert "3%" in note or "0%" in note
+    boot_timer.reset()
+
+
+def test_healthy_coverage_reports_a_tick():
+    from aether.core import boot_timer
+    boot_timer.reset(); boot_timer.enable()
+    boot_timer._PROCESS_START = time.time() - 1.0
+    boot_timer.record("everything", 1000.0)
+    assert boot_timer.coverage() >= boot_timer.COVERAGE_FLOOR
+    assert "✓" in boot_timer.coverage_note()
+    boot_timer.reset()
+
+
+def test_import_time_is_attributed_not_left_as_a_gap():
+    from aether.core import boot_timer
+    boot_timer.reset(); boot_timer.enable()
+    boot_timer._PROCESS_START = time.time() - 2.0
+    boot_timer.record("tool_build", 500.0)
+    boot_timer.record_import_phase()
+
+    names = [p["phase"] for p in boot_timer.phases()]
+    assert names[0] == "python_imports", "import cost leads the report"
+    assert boot_timer.coverage() >= boot_timer.COVERAGE_FLOOR
+    boot_timer.reset()
+
+
+def test_import_phase_is_recorded_once():
+    from aether.core import boot_timer
+    boot_timer.reset(); boot_timer.enable()
+    boot_timer._PROCESS_START = time.time() - 1.0
+    boot_timer.record("x", 100.0)
+    boot_timer.record_import_phase()
+    boot_timer.record_import_phase()
+    assert sum(p["phase"] == "python_imports"
+               for p in boot_timer.phases()) == 1
+    boot_timer.reset()
+
+
+# ── v5.2.3: heavy imports must not happen at boot ──────────────────────
+
+def test_gpu_tool_does_not_import_torch_at_construction():
+    """torch is ~0.6s on a dev Mac and 10-20s on a Pi 4. Constructing a tool
+    most sessions never call must not pay for it."""
+    import sys
+    from aether.core.tool_builder import GPUTool
+
+    had_torch = "torch" in sys.modules
+    tool = GPUTool()
+    if not had_torch:
+        assert "torch" not in sys.modules, "GPUTool imported torch at boot"
+    assert tool._resolved is False
+
+
+def test_camera_tool_does_not_detect_backend_at_construction():
+    """Backend detection imports cv2 / picamera2."""
+    from aether.core.tool_builder import CameraTool
+    tool = CameraTool()
+    assert tool._backend_resolved is False, \
+        "CameraTool resolved its backend (and imported cv2) at boot"
+
+
+def test_camera_backend_still_resolves_on_use():
+    from aether.core.tool_builder import CameraTool
+    tool = CameraTool()
+    _ = tool._backend_name          # property triggers resolution
+    assert tool._backend_resolved is True
+
+
+def test_no_heavy_import_reaches_module_scope():
+    """The hard rule: nothing heavyweight before the prompt."""
+    import ast
+    import os
+
+    heavy = {"torch", "cv2", "picamera2", "ultralytics",
+             "sentence_transformers"}
+    offenders = []
+    for root, _dirs, files in os.walk("aether"):
+        if "__pycache__" in root:
+            continue
+        for name in files:
+            if not name.endswith(".py"):
+                continue
+            path = os.path.join(root, name)
+            with open(path, encoding="utf-8", errors="replace") as handle:
+                try:
+                    tree = ast.parse(handle.read())
+                except SyntaxError:
+                    continue
+            for node in tree.body:          # MODULE SCOPE only
+                if isinstance(node, ast.Import):
+                    names = [a.name.split(".")[0] for a in node.names]
+                elif isinstance(node, ast.ImportFrom):
+                    names = [(node.module or "").split(".")[0]]
+                else:
+                    continue
+                if heavy.intersection(names):
+                    offenders.append(f"{path}: {names}")
+    assert not offenders, f"heavy imports at module scope: {offenders}"
+
+
+def test_update_check_is_cached_and_can_be_disabled(monkeypatch):
+    """Network I/O on the boot path is the user<<real gap. Never block."""
+    from aether.core.auto_updater import AutoUpdater
+
+    monkeypatch.setenv("AETHER_NO_UPDATE_CHECK", "1")
+    monkeypatch.setattr(AutoUpdater, "_cached_check", lambda self: None)
+    updater = AutoUpdater(current_version="1.0")
+    assert updater._fetch_latest_release() is None
+
+
+def test_a_cached_update_check_skips_the_network(monkeypatch):
+    from aether.core.auto_updater import AutoUpdater
+
+    monkeypatch.setattr(AutoUpdater, "_cached_check",
+                        lambda self: {"tag_name": "v9.9.9", "body": ""})
+    def explode(*a, **k):
+        raise AssertionError("network was contacted despite a cache hit")
+    monkeypatch.setattr("urllib.request.urlopen", explode)
+
+    updater = AutoUpdater(current_version="1.0")
+    assert updater._fetch_latest_release()["tag_name"] == "v9.9.9"

aether_robotics-5.2.2/VERSION

@@ -1 +0,0 @@
-5.2.2