imperal-sdk 6.3.5__tar.gz → 6.3.7__tar.gz

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 6.3.7 — 2026-10-21
+
+### Changed
+- Plain names: `DwellGuard` / `DwellGuardStep` (module `imperal_sdk.dwell_guard`) -- the dwell guard says what it
+  checks (nesting depth, steps on one entity without coverage gain, a growing gap) and its alarms say what to do.
+  `GNCLyapunovGuard` / `GNCEnergyState` (`imperal_sdk.gnc_guard`) stay as old names of the same classes.
+- `DEFAULT_APP_ICON` (old name `DEFAULT_QUANTUM_ICON` kept); docstrings no longer say "ICNLI Quantum SDK".
+
+## 6.3.6 — 2026-10-21
+
+### Fixed
+- Code index: a source with an embedder says so (`meta.embeds`), so the vault asks it once for the versions it
+  holds without vectors. A repo first synced by a source without an embedder stayed `semantic: off` forever --
+  a held version was never sent again.
+
 ## 6.3.5 — 2026-10-20
 
 ### Changed

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imperal-sdk
-Version: 6.3.5
+Version: 6.3.7
 Summary: SDK for building Imperal Cloud extensions
 Author: Imperal, Inc.
 Author-email: Valentin Scerbacov <valentin@imperal.io>

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/sdk-reference.json

@@ -1,5 +1,5 @@
 {
-  "sdk_version": "6.3.5",
+  "sdk_version": "6.3.7",
   "symbols": {
     "ActionResult": {
       "action_vocab_safe": false,

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "6.3.5",
+  "_sdk_version": "6.3.7",
   "constants": {
     "max_call_depth": {
       "counts_root": true,

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Imperal Cloud SDK — build extensions for the Imperal platform."""
 from typing import TYPE_CHECKING
 
-__version__ = "6.3.5"
+__version__ = "6.3.7"
 
 # 5.2.2 (2026-06-11): the package root resolves its public surface lazily
 # (PEP 562). The eager imports pulled the HTTP transport (Context / client
@@ -48,12 +48,14 @@ _LAZY_ATTRS = {
     # hand-roll a token_refresh.py; four divergent copies are how an expired
     # Google Analytics token turned into "please reconnect" (2026-08-21).
     "fresh_token": "imperal_sdk.oauth_tokens",
-    # GNC Marathon Resilience & Tenant Vault Working RAM (ICNLI V17)
+    # Marathon dwell guard & Tenant Vault Working RAM
     "TenantVaultRAM": "imperal_sdk.vault_ram_client",
     "TargetEntity": "imperal_sdk.vault_ram_client",
     "WorkingRAMSnapshot": "imperal_sdk.vault_ram_client",
-    "GNCLyapunovGuard": "imperal_sdk.gnc_guard",
-    "GNCEnergyState": "imperal_sdk.gnc_guard",
+    "DwellGuard": "imperal_sdk.dwell_guard",
+    "DwellGuardStep": "imperal_sdk.dwell_guard",
+    "GNCLyapunovGuard": "imperal_sdk.gnc_guard",   # old name of DwellGuard
+    "GNCEnergyState": "imperal_sdk.gnc_guard",     # old name of DwellGuardStep
     "BOMExtractor": "imperal_sdk.bom_extractor",
     "BOMEntity": "imperal_sdk.bom_extractor",
     "BOMReport": "imperal_sdk.bom_extractor",

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/app.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) 2026 Imperal, Inc.
 # Licensed under the Apache-2.0 License.
-"""ICNLI Quantum SDK v6.0 — The Universal Zero-Boilerplate Application Engine.
+"""Imperal SDK App: an extension with no boilerplate.
 
 Empowers developers to build next-generation AI Cloud OS applications with:
 1. Zero-Manifest: 100% automatic type-to-schema extraction from Python signatures.
@@ -25,7 +25,7 @@ from imperal_sdk.context import Context
 from imperal_sdk.types.identity import UserContext, TenantContext
 from imperal_sdk.auto_ui import project_to_declarative_ir
 
-DEFAULT_QUANTUM_ICON = (
+DEFAULT_APP_ICON = (
     '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" '
     'stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-atom">'
     '<circle cx="12" cy="12" r="1"/>'
@@ -33,6 +33,7 @@ DEFAULT_QUANTUM_ICON = (
     '<path d="M15.7 15.7c4.52-4.54 6.54-9.87 4.5-11.9-2.03-2.04-7.36-.02-11.9 4.5-4.52 4.54-6.54 9.87-4.5 11.9 2.03 2.04 7.36.02 11.9-4.5Z"/>'
     '</svg>'
 )
+DEFAULT_QUANTUM_ICON = DEFAULT_APP_ICON  # old name
 
 
 def _python_type_to_json_schema(py_type):
@@ -75,7 +76,7 @@ def create_ambient_context(user_id="ambient_user"):
 
 
 class App(Extension):
-    """High-level ICNLI Quantum Application.
+    """High-level Imperal SDK application.
     
     Zero-manifest, auto-schema, ambient-context, auto-IR enabled container.
     Inherits from `Extension` for 100% backward compatibility with all
@@ -99,7 +100,7 @@ class App(Extension):
         if len(desc) < 40:
             desc = "{} Fully compliant with the ICNLI Agentic OS specification.".format(desc)
 
-        effective_icon = icon or DEFAULT_QUANTUM_ICON
+        effective_icon = icon or DEFAULT_APP_ICON
 
         super(App, self).__init__(
             app_id=app_id,

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/auto_ui.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
 # Licensed under the Apache-2.0 License. See LICENSE file for details.
-"""Auto-IR & UI-as-Data Projector for ICNLI Quantum SDK.
+"""Auto UI for the Imperal SDK: return values become UI components.
 
 Transforms standard Python return types (dicts, dataclasses, lists, primitives)
 into reactive Declarative IR components without writing custom frontend templates.

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/bom_extractor.py

@@ -1,5 +1,5 @@
 """
-Pre-Flight BOM Extractor (RFC: ICNLI V17 / GNC Marathon Resilience Engine)
+Pre-Flight BOM Extractor 
 
 Scans target codebases (NodeJS: Express/Fastify/Koa/Next.js/HTML, Python: Flask/FastAPI/Django)
 to extract a ground-truth Bill-of-Materials (BOM) before coding starts:

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/code_index.py

@@ -1673,6 +1673,11 @@ async def sync_source(plan, apply, meta: dict, listing: list, read, *, embed_chu
     meta = dict(meta or {})
     meta["extractor_version"] = EXTRACTOR_VERSION
     meta.setdefault("listed_at", _time.time())
+    # a source with an embedder says so: the vault then asks, once, for the versions it holds without vectors (a
+    # repo synced by a source without one stayed "semantic: off" forever -- a held version is never sent again)
+    embed_chunks = bool(embed_chunks) and _backend() is not None
+    if embed_chunks:
+        meta["embeds"] = True
     partial: list = []
     items: list = []
     for it in listing or []:

imperal_sdk-6.3.5/src/imperal_sdk/gnc_guard.py → imperal_sdk-6.3.7/src/imperal_sdk/dwell_guard.py

@@ -1,13 +1,15 @@
 """
-GNC Lyapunov Guard for Autonomous Long-Running Marathons (RFC: ICNLI V17)
+Dwell guard for long-running marathons: is the agent stuck on one item?
 
-Replaces scalar 1D Lyapunov error V(q, p) with a composite multi-scale potential:
-  V(S) = alpha * (1 - MacroCoverage)^2 + beta * ||x_micro||^2 + gamma * Psi(tau_dwell)
+Each step scores a gap from three measured parts:
+  gap = alpha * (1 - coverage)^2 + beta * error^2 + gamma * excess_dwell^2
 
-Features:
-  1. Sub-manifold Limit Cycle Detection (prevents 70,000s traps like Ignat's marathon)
-  2. Macro-Velocity Governor (tracks coverage progress per step/time)
-  3. Anti-Yak-Shaving Barrier (caps recursion depth <= 2 and forces scratchpad deferral)
+and raises an alarm when the agent
+  1. goes deeper than ``max_subtask_depth`` nested subtasks,
+  2. stays on one entity for more than ``max_dwell_steps`` steps without coverage gain, or
+  3. lets the gap grow while dwelling.
+
+(``imperal_sdk.gnc_guard`` keeps the old names ``GNCLyapunovGuard`` / ``GNCEnergyState``.)
 """
 
 from __future__ import annotations
@@ -19,7 +21,7 @@ from typing import Dict, List, Optional, Tuple, Any
 
 
 @dataclass
-class GNCEnergyState:
+class DwellGuardStep:
     step: int
     timestamp: float
     active_entity_id: str
@@ -35,19 +37,16 @@ class GNCEnergyState:
     alarm_reason: Optional[str] = None
 
 
-class GNCLyapunovGuard:
-    """
-    Composite Multi-Scale Lyapunov Stability Guard.
-    Directly connected to Tenant Vault Working RAM.
-    """
+class DwellGuard:
+    """Scores each step's gap and raises an alarm when the agent dwells on one entity."""
 
     def __init__(
         self,
-        alpha: float = 10.0,       # Macro-weight (high penalty for unfinished system)
-        beta: float = 1.0,         # Micro-weight (local syntax/test error)
-        gamma: float = 5.0,        # Barrier weight for dwelling/stalling
+        alpha: float = 10.0,       # weight of the unfinished share of the plan
+        beta: float = 1.0,         # weight of the local error (syntax / test)
+        gamma: float = 5.0,        # weight of the steps over the dwell budget
         max_dwell_steps: int = 12, # Max allowed steps on one entity before alarm
-        max_subtask_depth: int = 2 # Anti-Yak-Shaving depth barrier
+        max_subtask_depth: int = 2 # max nesting of subtasks
     ):
         self.alpha = alpha
         self.beta = beta
@@ -55,7 +54,7 @@ class GNCLyapunovGuard:
         self.max_dwell_steps = max_dwell_steps
         self.max_subtask_depth = max_subtask_depth
         
-        self.history: List[GNCEnergyState] = []
+        self.history: List[DwellGuardStep] = []
         self._current_subtask_depth: int = 1
         self._last_active_entity: Optional[str] = None
         self._entity_dwell_counter: int = 0
@@ -67,10 +66,8 @@ class GNCLyapunovGuard:
         active_entity_id: str,
         micro_error: float = 0.0,
         subtask_depth: int = 1
-    ) -> GNCEnergyState:
-        """
-        Calculates composite Lyapunov energy V(S) and checks stability criteria.
-        """
+    ) -> DwellGuardStep:
+        """Scores this step's gap and checks the depth, dwell and growth limits."""
         now = time.time()
         step_num = len(self.history) + 1
 
@@ -110,33 +107,33 @@ class GNCLyapunovGuard:
         else:
             delta_v = 0.0
 
-        # Detect limit cycle / stall
+        # Detect a stall
         is_limit_cycle = False
         alarm_reason = None
 
-        # Check Depth Barrier (Anti-Yak-Shaving)
+        # Too many nested subtasks
         if subtask_depth > self.max_subtask_depth:
             is_limit_cycle = True
             alarm_reason = (
-                f"Anti-Yak-Shaving Barrier tripped: subtask depth {subtask_depth} exceeds "
-                f"limit {self.max_subtask_depth}. Refuse deep refactoring; defer blocker to scratchpad."
+                f"Subtask depth {subtask_depth} exceeds the limit {self.max_subtask_depth}: "
+                f"do not go deeper; note the blocker and return to the item."
             )
-        # Check Dwell Barrier
+        # Too many steps on one entity
         elif dwell > self.max_dwell_steps:
             is_limit_cycle = True
             alarm_reason = (
-                f"Limit cycle detected on '{active_entity_id}': dwell steps ({dwell}) exceeded "
-                f"budget ({self.max_dwell_steps}) with zero macro coverage gain. Forcing phase transition!"
+                f"Stuck on '{active_entity_id}': {dwell} steps without coverage gain "
+                f"(limit {self.max_dwell_steps}). Move to another item or report the blocker."
             )
-        # Check Energy Divergence
+        # The gap grows while dwelling
         elif delta_v > 0.5 and dwell > 5:
             is_limit_cycle = True
             alarm_reason = (
-                f"Lyapunov energy diverging (Delta V = +{delta_v:.3f}): system is expanding energy "
-                f"on secondary details without macroscopic convergence."
+                f"The gap grew by {delta_v:.3f} while dwelling: the steps go into side details "
+                f"without moving the plan."
             )
 
-        state = GNCEnergyState(
+        state = DwellGuardStep(
             step=step_num,
             timestamp=now,
             active_entity_id=active_entity_id,

imperal_sdk-6.3.7/src/imperal_sdk/gnc_guard.py

@@ -0,0 +1,4 @@
+"""Old names of :mod:`imperal_sdk.dwell_guard`, kept so existing extensions keep importing."""
+from imperal_sdk.dwell_guard import DwellGuard as GNCLyapunovGuard, DwellGuardStep as GNCEnergyState
+
+__all__ = ["GNCLyapunovGuard", "GNCEnergyState"]

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/schema/marathon_ram.sql

@@ -1,6 +1,6 @@
 -- ============================================================================
 -- IMPERAL CLOUD OS — TENANT VAULT WORKING RAM (COGNITIVE BLACKBOARD)
--- RFC: ICNLI V17 / GNC Marathon Resilience Engine
+-- RFC: ICNLI V17
 -- ============================================================================
 
 -- 1. Target System Entities (BOM: screens, routes, models, services)

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/src/imperal_sdk/vault_ram_client.py

@@ -1,5 +1,5 @@
 """
-Tenant Vault Working RAM Client (RFC: ICNLI V17 / GNC Marathon Resilience Engine)
+Tenant Vault Working RAM Client 
 
 Provides sub-3ms working memory access for autonomous marathons.
 Separates LLM Reasoning Core (CPU/ALU) from Persistent State Store (Working RAM).

imperal_sdk-6.3.5/tests/test_quantum_app.py → imperal_sdk-6.3.7/tests/test_app_engine.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
 # Licensed under the Apache-2.0 License. See LICENSE file for details.
-"""Tests for ICNLI Quantum SDK v6.0 App Engine."""
+"""Tests for the Imperal SDK App."""
 from __future__ import annotations
 
 import asyncio

{imperal_sdk-6.3.5 → imperal_sdk-6.3.7}/tests/test_code_index_indexer.py

@@ -443,3 +443,28 @@ def test_a_file_whose_facts_do_not_fit_an_apply_is_kept_as_text_and_said(monkeyp
     assert "defs" not in bundle["facts"] and bundle["facts"]["lines"] > 1000
     assert any(b["facts"].get("defs") for b in sent.values() if b["text"] != big)
     assert "bundle.py kept as text only" in out["partial_reason"]
+
+
+def test_a_source_with_an_embedder_says_so_to_the_vault_and_one_without_never_does(monkeypatch):
+    """6.3.6 (frame audit 2026-10-21: every repo said "semantic: off"): ``meta.embeds`` lets the vault ask an
+    embedding source, once, for the versions it holds without vectors."""
+    import asyncio
+    from imperal_sdk import code_index as ci
+    seen = []
+
+    async def plan(items, meta):
+        seen.append(dict(meta))
+        return {"changed": [], "removed": [], "have_blobs": []}
+
+    async def apply(**payload):
+        return {}
+
+    async def read(paths):
+        return {}
+    listing = [{"path": "a.py", "size": 3, "mtime": 1.0}]
+    monkeypatch.setattr(ci, "_backend", lambda: object())
+    asyncio.run(ci.sync_source(plan, apply, {"source": "t"}, listing, read))
+    asyncio.run(ci.sync_source(plan, apply, {"source": "t"}, listing, read, embed_chunks=False))
+    monkeypatch.setattr(ci, "_backend", lambda: None)
+    asyncio.run(ci.sync_source(plan, apply, {"source": "t"}, listing, read))
+    assert [m.get("embeds") for m in seen] == [True, None, None]