loopgain 0.1.2__tar.gz → 0.1.4__tar.gz

{loopgain-0.1.2 → loopgain-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.2
+Version: 0.1.4
 Summary: Barkhausen stability monitor for AI agent loops. Real-time loop-gain (Aβ) monitoring with five named threshold bands, best-so-far rollback, and ETA prediction.
 Author-email: Dave Fitzsimmons <dave_fitz@icloud.com>
 License: Apache-2.0
@@ -101,7 +101,7 @@ Plus a short-circuit: if observed error drops at or below `target_error`, the lo
 
 The `±0.05` noise band around `Aβ=1` absorbs stochastic jitter from agent outputs without triggering false-positive aborts. The `0.85` `STALLING` boundary is an early warning — by the time `Aβ` crosses `1.0`, you've already wasted iterations.
 
-These threshold defaults work well for typical agent loops out of the box. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
+These threshold defaults are derived from the Barkhausen-stability analysis and serve as reasonable starting points. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
 
 ---
 
@@ -234,5 +234,3 @@ Loop types this applies to in practice:
 - **Code generation with linter/test feedback** — generate, run tests/linter, fix, repeat. Error = failing test count or linter violation count.
 - **Multi-step reasoning loops** — ReAct-style think/act/observe iterations. Error = whatever the agent's quality assessor returns.
 - **Custom feedback loops** — anything where you can produce a number that should drop toward zero as the loop succeeds.
-
-See [loopgain.ai](https://loopgain.ai) for the longer write-up.

{loopgain-0.1.2 → loopgain-0.1.4}/README.md

@@ -73,7 +73,7 @@ Plus a short-circuit: if observed error drops at or below `target_error`, the lo
 
 The `±0.05` noise band around `Aβ=1` absorbs stochastic jitter from agent outputs without triggering false-positive aborts. The `0.85` `STALLING` boundary is an early warning — by the time `Aβ` crosses `1.0`, you've already wasted iterations.
 
-These threshold defaults work well for typical agent loops out of the box. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
+These threshold defaults are derived from the Barkhausen-stability analysis and serve as reasonable starting points. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
 
 ---
 
@@ -206,5 +206,3 @@ Loop types this applies to in practice:
 - **Code generation with linter/test feedback** — generate, run tests/linter, fix, repeat. Error = failing test count or linter violation count.
 - **Multi-step reasoning loops** — ReAct-style think/act/observe iterations. Error = whatever the agent's quality assessor returns.
 - **Custom feedback loops** — anything where you can produce a number that should drop toward zero as the loop succeeds.
-
-See [loopgain.ai](https://loopgain.ai) for the longer write-up.

{loopgain-0.1.2 → loopgain-0.1.4}/loopgain/__init__.py

@@ -24,7 +24,7 @@ from loopgain.core import (
 )
 from loopgain.telemetry import build_payload as build_telemetry_payload
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = [
     "LoopGain",

{loopgain-0.1.2 → loopgain-0.1.4}/loopgain/core.py

@@ -10,7 +10,7 @@ named states and decides whether to continue, stop, or roll back.
 
 The math is foundational EE control theory. The product layer is the
 threshold bands, the best-so-far buffer, the ETA prediction, and the
-clean Python API. See https://loopgain.ai for the long-form write-up.
+clean Python API.
 
 License: Apache-2.0
 """
@@ -109,6 +109,19 @@ class LoopGainResult:
     """Iterations saved versus the assumed fixed cap (default 10).
     Zero if the loop hit ``max_iterations``; otherwise non-negative."""
 
+    first_eta_prediction: Optional[int] = None
+    """First non-None ``eta`` snapshot captured during the loop —
+    the predicted iterations-remaining at the moment the prediction
+    became computable. ``None`` if no prediction was ever made
+    (e.g., ``target_error == 0``, loop never converged toward target,
+    or the loop terminated before two observations)."""
+
+    first_eta_at_iteration: Optional[int] = None
+    """Iteration count when ``first_eta_prediction`` was captured.
+    ``None`` if no prediction was ever made. Predicted *total*
+    iterations = ``first_eta_at_iteration + first_eta_prediction``,
+    comparable to ``iterations_used`` for calibration."""
+
 
 class LoopGain:
     """Barkhausen stability monitor for AI agent loops.
@@ -173,6 +186,8 @@ class LoopGain:
         self._outputs: list[Any] = []
         self._state: str = INIT
         self._terminal: bool = False
+        self._first_eta_prediction: Optional[int] = None
+        self._first_eta_at_iteration: Optional[int] = None
 
     # ----- Public observation API -----
 
@@ -237,6 +252,17 @@ class LoopGain:
             self._state = MAX_ITERATIONS
             self._terminal = True
 
+        # Snapshot the first computable eta prediction for calibration.
+        # eta is None until smoothing settles and the loop looks convergent;
+        # we capture the *first* value it produces and the iteration it was
+        # produced at, so predicted_total = at_iter + eta is comparable to
+        # iterations_used.
+        if self._first_eta_prediction is None:
+            eta_now = self.eta
+            if eta_now is not None and eta_now > 0:
+                self._first_eta_prediction = eta_now
+                self._first_eta_at_iteration = len(self._error_history)
+
         return self._state
 
     def should_continue(self) -> bool:
@@ -333,6 +359,8 @@ class LoopGain:
             error_history=list(self._error_history),
             gain_margin=self.gain_margin,
             savings_vs_fixed_cap=savings,
+            first_eta_prediction=self._first_eta_prediction,
+            first_eta_at_iteration=self._first_eta_at_iteration,
         )
 
     # ----- Internal helpers -----

{loopgain-0.1.2 → loopgain-0.1.4}/loopgain/telemetry.py

@@ -25,10 +25,13 @@ if TYPE_CHECKING:
 
 
 # Schema version is incremented when the payload format breaks compatibility.
-SCHEMA_VERSION = 1
+# v2 (2026-05-13) adds first_eta_prediction + first_eta_at_iteration for the
+# ETA Accuracy dashboard panel. Receiver remains backward-compatible: v1
+# payloads are still accepted (new fields default to None).
+SCHEMA_VERSION = 2
 
 # Library version (kept in sync with __init__.py).
-LIBRARY_VERSION = "0.1.2"
+LIBRARY_VERSION = "0.1.4"
 
 
 def build_payload(
@@ -83,6 +86,13 @@ def build_payload(
             "savings_vs_fixed_cap": result.savings_vs_fixed_cap,
             "convergence_profile_summary": profile_summary,
             "rollback_triggered": result.outcome in ("oscillating", "diverged"),
+            # v2: first computable eta snapshot, for ETA calibration dashboard.
+            # Predicted total iterations = first_eta_at_iteration +
+            # first_eta_prediction; compare to iterations_used to compute the
+            # calibration error. Both are None when no prediction was made
+            # (target_error=0, loop never looked convergent, etc.).
+            "first_eta_prediction": result.first_eta_prediction,
+            "first_eta_at_iteration": result.first_eta_at_iteration,
         },
         "thresholds": {
             "fast_converge": lg.thresholds.fast_converge,

{loopgain-0.1.2 → loopgain-0.1.4}/loopgain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.2
+Version: 0.1.4
 Summary: Barkhausen stability monitor for AI agent loops. Real-time loop-gain (Aβ) monitoring with five named threshold bands, best-so-far rollback, and ETA prediction.
 Author-email: Dave Fitzsimmons <dave_fitz@icloud.com>
 License: Apache-2.0
@@ -101,7 +101,7 @@ Plus a short-circuit: if observed error drops at or below `target_error`, the lo
 
 The `±0.05` noise band around `Aβ=1` absorbs stochastic jitter from agent outputs without triggering false-positive aborts. The `0.85` `STALLING` boundary is an early warning — by the time `Aβ` crosses `1.0`, you've already wasted iterations.
 
-These threshold defaults work well for typical agent loops out of the box. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
+These threshold defaults are derived from the Barkhausen-stability analysis and serve as reasonable starting points. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
 
 ---
 
@@ -234,5 +234,3 @@ Loop types this applies to in practice:
 - **Code generation with linter/test feedback** — generate, run tests/linter, fix, repeat. Error = failing test count or linter violation count.
 - **Multi-step reasoning loops** — ReAct-style think/act/observe iterations. Error = whatever the agent's quality assessor returns.
 - **Custom feedback loops** — anything where you can produce a number that should drop toward zero as the loop succeeds.
-
-See [loopgain.ai](https://loopgain.ai) for the longer write-up.

{loopgain-0.1.2 → loopgain-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopgain"
-version = "0.1.2"
+version = "0.1.4"
 description = "Barkhausen stability monitor for AI agent loops. Real-time loop-gain (Aβ) monitoring with five named threshold bands, best-so-far rollback, and ETA prediction."
 authors = [{name = "Dave Fitzsimmons", email = "dave_fitz@icloud.com"}]
 readme = "README.md"

{loopgain-0.1.2 → loopgain-0.1.4}/tests/test_core.py

@@ -199,6 +199,70 @@ def test_eta_none_when_target_is_zero():
     assert lg.eta is None
 
 
+# ----- First-eta snapshot (for ETA Accuracy dashboard panel) -----
+
+
+def test_first_eta_snapshot_captured_during_converging_run():
+    """Result carries the first non-None eta and the iter it was made at."""
+    target = 0.1
+    errors = _decay(0.5, e0=100.0)
+    lg = LoopGain(target_error=target, max_iterations=100)
+    for e in errors:
+        lg.observe(e)
+        if not lg.should_continue():
+            break
+
+    result = lg.result
+    # First eta becomes computable on the 2nd observation (smoothed_history
+    # exists, target > 0, current > target, Aβ_smooth < 1).
+    assert result.first_eta_at_iteration == 2
+    assert result.first_eta_prediction is not None
+    assert result.first_eta_prediction > 0
+    # Predicted total iterations should be within ±2 of actual (the prediction
+    # is made early, before smoothing has fully settled).
+    predicted_total = result.first_eta_at_iteration + result.first_eta_prediction
+    assert abs(predicted_total - result.iterations_used) <= 2
+
+
+def test_first_eta_snapshot_none_when_target_is_zero():
+    """No prediction is captured when target_error=0 (eta is always None)."""
+    lg = LoopGain(target_error=0.0, max_iterations=5)
+    for _ in range(5):
+        lg.observe(10.0)
+    result = lg.result
+    assert result.first_eta_prediction is None
+    assert result.first_eta_at_iteration is None
+
+
+def test_first_eta_snapshot_none_when_loop_never_converges():
+    """Oscillating loop (Aβ ≈ 1) never produces a positive eta."""
+    lg = LoopGain(target_error=0.5)
+    for _ in range(5):
+        lg.observe(10.0)
+        if not lg.should_continue():
+            break
+    result = lg.result
+    assert result.first_eta_prediction is None
+    assert result.first_eta_at_iteration is None
+
+
+def test_first_eta_snapshot_is_idempotent():
+    """Subsequent observations don't overwrite the first prediction."""
+    target = 0.1
+    errors = _decay(0.5, e0=100.0)
+    lg = LoopGain(target_error=target, max_iterations=100)
+    lg.observe(errors[0])
+    lg.observe(errors[1])
+    first = lg._first_eta_prediction
+    first_iter = lg._first_eta_at_iteration
+    assert first is not None
+    # Run a few more iterations; the snapshot should not change.
+    for e in errors[2:6]:
+        lg.observe(e)
+    assert lg._first_eta_prediction == first
+    assert lg._first_eta_at_iteration == first_iter
+
+
 # ----- observe() input coercion -----
 
 

{loopgain-0.1.2 → loopgain-0.1.4}/tests/test_telemetry.py

@@ -172,6 +172,52 @@ def test_payload_for_not_started_loop():
     assert p["loop"]["convergence_profile_summary"]["samples"] == 0
 
 
+# ----- v2 schema: ETA calibration fields -----
+
+
+def test_payload_schema_version_is_v2():
+    """Schema bumped to v2 with the addition of first_eta_* fields."""
+    assert SCHEMA_VERSION == 2
+    lg = _make_terminated_loop()
+    p = build_payload(lg)
+    assert p["schema_version"] == 2
+
+
+def test_payload_includes_first_eta_fields_when_loop_converged():
+    """A converging loop produces a captured eta snapshot."""
+    lg = _make_terminated_loop()
+    p = build_payload(lg)
+    loop = p["loop"]
+    assert "first_eta_prediction" in loop
+    assert "first_eta_at_iteration" in loop
+    assert loop["first_eta_prediction"] is not None
+    assert loop["first_eta_at_iteration"] is not None
+    assert loop["first_eta_prediction"] > 0
+    assert loop["first_eta_at_iteration"] >= 2
+
+
+def test_payload_first_eta_none_for_target_zero():
+    """target_error=0 means eta is never computable; both fields are None."""
+    lg = LoopGain(target_error=0.0, max_iterations=4)
+    for _ in range(4):
+        lg.observe(10.0)
+    p = build_payload(lg)
+    assert p["loop"]["first_eta_prediction"] is None
+    assert p["loop"]["first_eta_at_iteration"] is None
+
+
+def test_payload_first_eta_none_for_diverging_loop():
+    """A divergent loop never produces a positive eta."""
+    lg = LoopGain(target_error=0.5, max_iterations=20)
+    for e in [10.0, 12.0, 15.0, 20.0, 30.0]:
+        if not lg.should_continue():
+            break
+        lg.observe(e)
+    p = build_payload(lg)
+    assert p["loop"]["first_eta_prediction"] is None
+    assert p["loop"]["first_eta_at_iteration"] is None
+
+
 # ----- send_payload behavior -----