loopgain 0.1.0__tar.gz → 0.1.2__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.0
+Version: 0.1.2
 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
 Project-URL: Homepage, https://loopgain.ai
 Project-URL: Repository, https://github.com/loopgain-ai/loopgain
 Project-URL: Issues, https://github.com/loopgain-ai/loopgain/issues
-Keywords: ai,agent,barkhausen,loop-stability,control-theory,feedback-loop,llm,agentic,verify-revise,convergence
+Keywords: ai,agent,ai-agent,ai-agents,agentic,agentic-ai,llm,llm-agent,llm-orchestration,agent-orchestration,agent-loop,verify-revise,verify-revise-loop,gvr,generator-verifier-reviser,convergence,divergence-detection,infinite-loop,infinite-loop-detection,loop-detection,loop-stability,stability-monitor,early-stopping,max-iterations,barkhausen,barkhausen-criterion,control-theory,feedback-loop,feedback-loop-stability,loop-gain,rollback,best-so-far,langgraph,crewai,autogen,claude,anthropic,openai
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -28,13 +28,18 @@ Dynamic: license-file
 
 # LoopGain
 
-**Barkhausen stability monitor for AI agent verify-revise loops.**
+**Barkhausen stability monitor for AI agent loops.**
 
 Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows whether your agent loop is converging, stalling, oscillating, or diverging — and what to do in each case.
 
 [![PyPI](https://img.shields.io/pypi/v/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![Python](https://img.shields.io/pypi/pyversions/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-73_passing-brightgreen.svg)](tests/)
+
+Works for **any iterative AI workflow with a measurable error signal** — verify-revise loops, refinement passes, tool-use retry chains, RAG with self-correction, code-gen with linter feedback, multi-step reasoning loops. Integrates with **LangGraph**, **CrewAI**, **AutoGen**, **Claude Agent SDK**, and custom stacks. Pure Python, no runtime dependencies.
+
+**Keywords:** AI agent loops · agentic AI · infinite loop detection · divergence detection · early stopping · convergence · agent orchestration · LLM stability · generator-verifier-reviser · feedback-loop control.
 
 ---
 
@@ -42,8 +47,6 @@ Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows
 
 Production agent loops universally use `max_iterations=N` as their termination policy. It's the embarrassing default of agentic AI: you either waste compute (loop stops too late) or ship bad output (loop stops too early). LoopGain replaces it with a control-theoretic stability monitor based on the **Barkhausen criterion** — a foundational result from electrical-engineering feedback-oscillator analysis (1921).
 
-The math is foundational. The product is the threshold bands, the best-so-far buffer, the ETA prediction, and the clean Python API.
-
 ---
 
 ## Install
@@ -58,7 +61,7 @@ Pure Python, no dependencies, supports Python 3.10+.
 
 ## Usage
 
-Three lines of code wrap any verify-revise loop:
+Three lines of code wrap any iterative loop with a measurable error signal:
 
 ```python
 from loopgain import LoopGain
@@ -169,24 +172,42 @@ Terminal result with `outcome`, `iterations_used`, `best_index`, `best_output`,
 **Opt-in.** Send a single anonymized telemetry POST after the loop terminates. Best-effort — never raises, returns `True` on 2xx, `False` otherwise.
 
 ```python
+import os
+from loopgain import LoopGain
+
+lg = LoopGain(target_error=0.1)
+# ... run the loop ...
 lg.send_telemetry(
-    endpoint="https://telemetry.loopgain.ai/v1/aggregate",  # or self-hosted
-    token="your-token",                                     # bearer auth
-    workload_id="my-rag-pipeline",                          # opaque label
+    endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],   # or hardcode
+    token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],         # never hardcode
+    workload_id="my-rag-pipeline",                        # opaque label
 )
 ```
 
+Recommended setup: store the token outside source. Two clean options:
+
+```bash
+# Option A: environment variable (simplest)
+export LOOPGAIN_TELEMETRY_ENDPOINT="https://telemetry.loopgain.ai/v1/aggregate"
+export LOOPGAIN_TELEMETRY_TOKEN="lgk_..."   # add to ~/.zshrc or ~/.bashrc
+
+# Option B: macOS Keychain (more secure)
+pip install keyring
+python3 -c "import keyring; keyring.set_password('loopgain', 'telemetry', input('Token: '))"
+# Then in code: keyring.get_password('loopgain', 'telemetry')
+```
+
 What is sent: state transitions, Aβ summary (min/max/median), gain margin, rollback flag, iterations used, savings, library version, optional opaque `workload_id`, threshold config, hour-bucketed timestamp.
 
 **What is NEVER sent: prompts, completions, error contents, output buffer, individual Aβ values, or any customer identity beyond the bearer token.** Privacy contract is enforced by the payload-shape unit tests in `tests/test_telemetry.py`.
 
-The Cascade-Systems-hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination; the receiver code is open-source so customers can self-host to keep telemetry fully under their control.
+The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. The [receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are both open-source — self-host to keep telemetry fully under your control.
 
 ---
 
 ## Status
 
-**v0.1.0 — initial public release.** Core library shipped. Framework adapters (LangGraph, CrewAI, AutoGen, Vesper) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
+**Initial public release.** Core library shipped (current version: see the PyPI badge at the top). Framework adapters (LangGraph, CrewAI, AutoGen) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
 
 This is alpha software. The API may break before 1.0 if production usage surfaces design issues; pin the version.
 
@@ -202,6 +223,16 @@ This is alpha software. The API may break before 1.0 if production usage surface
 
 LoopGain applies the **Barkhausen stability criterion** (Heinrich Barkhausen, 1921 — the foundational result on when feedback amplifiers oscillate) to AI agent feedback loops. The criterion was originally a way to predict whether an electronic oscillator would sustain oscillation; it turns out to map cleanly onto any feedback loop you can attach an error signal to.
 
-The cleanest summary: a verify-revise loop is a feedback system with measurable error magnitude. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+The cleanest summary: an iterative AI loop with a measurable error signal is a feedback system. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+
+Loop types this applies to in practice:
+
+- **Verify-revise loops** (GVR pattern) — generator produces, verifier finds issues, reviser fixes. Error = issue count or severity-weighted score.
+- **Refinement loops** — initial output, iterate to improve. Error = distance from target spec / rubric score.
+- **Tool-use retry chains** — agent calls tool, gets back error/success, retries. Error = consecutive failure count or aggregate score.
+- **RAG with self-correction** — retrieve, generate, critique, re-retrieve. Error = critique severity or hallucination score.
+- **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.0 → loopgain-0.1.2}/README.md

@@ -1,12 +1,17 @@
 # LoopGain
 
-**Barkhausen stability monitor for AI agent verify-revise loops.**
+**Barkhausen stability monitor for AI agent loops.**
 
 Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows whether your agent loop is converging, stalling, oscillating, or diverging — and what to do in each case.
 
 [![PyPI](https://img.shields.io/pypi/v/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![Python](https://img.shields.io/pypi/pyversions/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-73_passing-brightgreen.svg)](tests/)
+
+Works for **any iterative AI workflow with a measurable error signal** — verify-revise loops, refinement passes, tool-use retry chains, RAG with self-correction, code-gen with linter feedback, multi-step reasoning loops. Integrates with **LangGraph**, **CrewAI**, **AutoGen**, **Claude Agent SDK**, and custom stacks. Pure Python, no runtime dependencies.
+
+**Keywords:** AI agent loops · agentic AI · infinite loop detection · divergence detection · early stopping · convergence · agent orchestration · LLM stability · generator-verifier-reviser · feedback-loop control.
 
 ---
 
@@ -14,8 +19,6 @@ Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows
 
 Production agent loops universally use `max_iterations=N` as their termination policy. It's the embarrassing default of agentic AI: you either waste compute (loop stops too late) or ship bad output (loop stops too early). LoopGain replaces it with a control-theoretic stability monitor based on the **Barkhausen criterion** — a foundational result from electrical-engineering feedback-oscillator analysis (1921).
 
-The math is foundational. The product is the threshold bands, the best-so-far buffer, the ETA prediction, and the clean Python API.
-
 ---
 
 ## Install
@@ -30,7 +33,7 @@ Pure Python, no dependencies, supports Python 3.10+.
 
 ## Usage
 
-Three lines of code wrap any verify-revise loop:
+Three lines of code wrap any iterative loop with a measurable error signal:
 
 ```python
 from loopgain import LoopGain
@@ -141,24 +144,42 @@ Terminal result with `outcome`, `iterations_used`, `best_index`, `best_output`,
 **Opt-in.** Send a single anonymized telemetry POST after the loop terminates. Best-effort — never raises, returns `True` on 2xx, `False` otherwise.
 
 ```python
+import os
+from loopgain import LoopGain
+
+lg = LoopGain(target_error=0.1)
+# ... run the loop ...
 lg.send_telemetry(
-    endpoint="https://telemetry.loopgain.ai/v1/aggregate",  # or self-hosted
-    token="your-token",                                     # bearer auth
-    workload_id="my-rag-pipeline",                          # opaque label
+    endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],   # or hardcode
+    token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],         # never hardcode
+    workload_id="my-rag-pipeline",                        # opaque label
 )
 ```
 
+Recommended setup: store the token outside source. Two clean options:
+
+```bash
+# Option A: environment variable (simplest)
+export LOOPGAIN_TELEMETRY_ENDPOINT="https://telemetry.loopgain.ai/v1/aggregate"
+export LOOPGAIN_TELEMETRY_TOKEN="lgk_..."   # add to ~/.zshrc or ~/.bashrc
+
+# Option B: macOS Keychain (more secure)
+pip install keyring
+python3 -c "import keyring; keyring.set_password('loopgain', 'telemetry', input('Token: '))"
+# Then in code: keyring.get_password('loopgain', 'telemetry')
+```
+
 What is sent: state transitions, Aβ summary (min/max/median), gain margin, rollback flag, iterations used, savings, library version, optional opaque `workload_id`, threshold config, hour-bucketed timestamp.
 
 **What is NEVER sent: prompts, completions, error contents, output buffer, individual Aβ values, or any customer identity beyond the bearer token.** Privacy contract is enforced by the payload-shape unit tests in `tests/test_telemetry.py`.
 
-The Cascade-Systems-hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination; the receiver code is open-source so customers can self-host to keep telemetry fully under their control.
+The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. The [receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are both open-source — self-host to keep telemetry fully under your control.
 
 ---
 
 ## Status
 
-**v0.1.0 — initial public release.** Core library shipped. Framework adapters (LangGraph, CrewAI, AutoGen, Vesper) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
+**Initial public release.** Core library shipped (current version: see the PyPI badge at the top). Framework adapters (LangGraph, CrewAI, AutoGen) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
 
 This is alpha software. The API may break before 1.0 if production usage surfaces design issues; pin the version.
 
@@ -174,6 +195,16 @@ This is alpha software. The API may break before 1.0 if production usage surface
 
 LoopGain applies the **Barkhausen stability criterion** (Heinrich Barkhausen, 1921 — the foundational result on when feedback amplifiers oscillate) to AI agent feedback loops. The criterion was originally a way to predict whether an electronic oscillator would sustain oscillation; it turns out to map cleanly onto any feedback loop you can attach an error signal to.
 
-The cleanest summary: a verify-revise loop is a feedback system with measurable error magnitude. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+The cleanest summary: an iterative AI loop with a measurable error signal is a feedback system. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+
+Loop types this applies to in practice:
+
+- **Verify-revise loops** (GVR pattern) — generator produces, verifier finds issues, reviser fixes. Error = issue count or severity-weighted score.
+- **Refinement loops** — initial output, iterate to improve. Error = distance from target spec / rubric score.
+- **Tool-use retry chains** — agent calls tool, gets back error/success, retries. Error = consecutive failure count or aggregate score.
+- **RAG with self-correction** — retrieve, generate, critique, re-retrieve. Error = critique severity or hallucination score.
+- **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.0 → loopgain-0.1.2}/loopgain/__init__.py

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

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

@@ -1,9 +1,12 @@
 """LoopGain — Barkhausen stability monitor for AI agent loops.
 
 The product layer of the Barkhausen stability criterion (1921) applied to
-agent verify-revise feedback loops. Replaces the universal max_iterations
-hack with a real-time loop-gain monitor that classifies the loop into one
-of five named states and decides whether to continue, stop, or roll back.
+any iterative AI loop with a measurable error signal: verify-revise (GVR)
+patterns, refinement passes, tool-use retry chains, RAG with self-correction,
+code-gen with linter feedback, multi-step reasoning loops, and custom
+feedback systems. Replaces the universal max_iterations hack with a
+real-time loop-gain monitor that classifies the loop into one of five
+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
@@ -108,12 +111,16 @@ class LoopGainResult:
 
 
 class LoopGain:
-    """Barkhausen stability monitor for AI agent verify-revise loops.
-
-    Wraps any iterative loop and decides in real time whether to continue,
-    stop, or roll back. Replaces the universal ``max_iterations=N`` hack
-    with a control-theoretic stability monitor based on the Barkhausen
-    criterion.
+    """Barkhausen stability monitor for AI agent loops.
+
+    Wraps any iterative loop with a measurable error signal and decides in
+    real time whether to continue, stop, or roll back. Works for
+    verify-revise (GVR) loops, refinement passes, tool-use retry chains,
+    RAG with self-correction, code-gen with linter feedback, multi-step
+    reasoning loops, and any custom iterative process where you can
+    produce a number that should drop toward zero. Replaces the universal
+    ``max_iterations=N`` hack with a control-theoretic stability monitor
+    based on the Barkhausen criterion.
 
     Example:
 

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

@@ -6,9 +6,9 @@ rollback flag, library version, optional opaque workload label) are sent.
 Never sends prompts, completions, error contents, or customer identity beyond
 the bearer token.
 
-The Cascade-Systems-hosted endpoint at ``telemetry.loopgain.ai`` is one
-acceptable destination; customers can also self-host the receiver to keep
-the data fully under their control.
+The hosted endpoint at ``telemetry.loopgain.ai`` is one acceptable
+destination; the receiver code is open-source so users can also self-host
+to keep the data fully under their control.
 """
 
 from __future__ import annotations
@@ -28,7 +28,7 @@ if TYPE_CHECKING:
 SCHEMA_VERSION = 1
 
 # Library version (kept in sync with __init__.py).
-LIBRARY_VERSION = "0.1.0"
+LIBRARY_VERSION = "0.1.2"
 
 
 def build_payload(

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.0
+Version: 0.1.2
 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
 Project-URL: Homepage, https://loopgain.ai
 Project-URL: Repository, https://github.com/loopgain-ai/loopgain
 Project-URL: Issues, https://github.com/loopgain-ai/loopgain/issues
-Keywords: ai,agent,barkhausen,loop-stability,control-theory,feedback-loop,llm,agentic,verify-revise,convergence
+Keywords: ai,agent,ai-agent,ai-agents,agentic,agentic-ai,llm,llm-agent,llm-orchestration,agent-orchestration,agent-loop,verify-revise,verify-revise-loop,gvr,generator-verifier-reviser,convergence,divergence-detection,infinite-loop,infinite-loop-detection,loop-detection,loop-stability,stability-monitor,early-stopping,max-iterations,barkhausen,barkhausen-criterion,control-theory,feedback-loop,feedback-loop-stability,loop-gain,rollback,best-so-far,langgraph,crewai,autogen,claude,anthropic,openai
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -28,13 +28,18 @@ Dynamic: license-file
 
 # LoopGain
 
-**Barkhausen stability monitor for AI agent verify-revise loops.**
+**Barkhausen stability monitor for AI agent loops.**
 
 Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows whether your agent loop is converging, stalling, oscillating, or diverging — and what to do in each case.
 
 [![PyPI](https://img.shields.io/pypi/v/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![Python](https://img.shields.io/pypi/pyversions/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-73_passing-brightgreen.svg)](tests/)
+
+Works for **any iterative AI workflow with a measurable error signal** — verify-revise loops, refinement passes, tool-use retry chains, RAG with self-correction, code-gen with linter feedback, multi-step reasoning loops. Integrates with **LangGraph**, **CrewAI**, **AutoGen**, **Claude Agent SDK**, and custom stacks. Pure Python, no runtime dependencies.
+
+**Keywords:** AI agent loops · agentic AI · infinite loop detection · divergence detection · early stopping · convergence · agent orchestration · LLM stability · generator-verifier-reviser · feedback-loop control.
 
 ---
 
@@ -42,8 +47,6 @@ Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows
 
 Production agent loops universally use `max_iterations=N` as their termination policy. It's the embarrassing default of agentic AI: you either waste compute (loop stops too late) or ship bad output (loop stops too early). LoopGain replaces it with a control-theoretic stability monitor based on the **Barkhausen criterion** — a foundational result from electrical-engineering feedback-oscillator analysis (1921).
 
-The math is foundational. The product is the threshold bands, the best-so-far buffer, the ETA prediction, and the clean Python API.
-
 ---
 
 ## Install
@@ -58,7 +61,7 @@ Pure Python, no dependencies, supports Python 3.10+.
 
 ## Usage
 
-Three lines of code wrap any verify-revise loop:
+Three lines of code wrap any iterative loop with a measurable error signal:
 
 ```python
 from loopgain import LoopGain
@@ -169,24 +172,42 @@ Terminal result with `outcome`, `iterations_used`, `best_index`, `best_output`,
 **Opt-in.** Send a single anonymized telemetry POST after the loop terminates. Best-effort — never raises, returns `True` on 2xx, `False` otherwise.
 
 ```python
+import os
+from loopgain import LoopGain
+
+lg = LoopGain(target_error=0.1)
+# ... run the loop ...
 lg.send_telemetry(
-    endpoint="https://telemetry.loopgain.ai/v1/aggregate",  # or self-hosted
-    token="your-token",                                     # bearer auth
-    workload_id="my-rag-pipeline",                          # opaque label
+    endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],   # or hardcode
+    token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],         # never hardcode
+    workload_id="my-rag-pipeline",                        # opaque label
 )
 ```
 
+Recommended setup: store the token outside source. Two clean options:
+
+```bash
+# Option A: environment variable (simplest)
+export LOOPGAIN_TELEMETRY_ENDPOINT="https://telemetry.loopgain.ai/v1/aggregate"
+export LOOPGAIN_TELEMETRY_TOKEN="lgk_..."   # add to ~/.zshrc or ~/.bashrc
+
+# Option B: macOS Keychain (more secure)
+pip install keyring
+python3 -c "import keyring; keyring.set_password('loopgain', 'telemetry', input('Token: '))"
+# Then in code: keyring.get_password('loopgain', 'telemetry')
+```
+
 What is sent: state transitions, Aβ summary (min/max/median), gain margin, rollback flag, iterations used, savings, library version, optional opaque `workload_id`, threshold config, hour-bucketed timestamp.
 
 **What is NEVER sent: prompts, completions, error contents, output buffer, individual Aβ values, or any customer identity beyond the bearer token.** Privacy contract is enforced by the payload-shape unit tests in `tests/test_telemetry.py`.
 
-The Cascade-Systems-hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination; the receiver code is open-source so customers can self-host to keep telemetry fully under their control.
+The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. The [receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are both open-source — self-host to keep telemetry fully under your control.
 
 ---
 
 ## Status
 
-**v0.1.0 — initial public release.** Core library shipped. Framework adapters (LangGraph, CrewAI, AutoGen, Vesper) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
+**Initial public release.** Core library shipped (current version: see the PyPI badge at the top). Framework adapters (LangGraph, CrewAI, AutoGen) and the cloud-aggregator dashboard come in v0.2+. The math and the API surface are stable.
 
 This is alpha software. The API may break before 1.0 if production usage surfaces design issues; pin the version.
 
@@ -202,6 +223,16 @@ This is alpha software. The API may break before 1.0 if production usage surface
 
 LoopGain applies the **Barkhausen stability criterion** (Heinrich Barkhausen, 1921 — the foundational result on when feedback amplifiers oscillate) to AI agent feedback loops. The criterion was originally a way to predict whether an electronic oscillator would sustain oscillation; it turns out to map cleanly onto any feedback loop you can attach an error signal to.
 
-The cleanest summary: a verify-revise loop is a feedback system with measurable error magnitude. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+The cleanest summary: an iterative AI loop with a measurable error signal is a feedback system. The ratio `E(n) / E(n-1)` is its empirical loop gain. The Barkhausen result tells you that loop gain less than 1 converges, equal to 1 oscillates, greater than 1 diverges. LoopGain operationalizes this: classifies the loop's current band, decides what to do, and tells you when you'll converge.
+
+Loop types this applies to in practice:
+
+- **Verify-revise loops** (GVR pattern) — generator produces, verifier finds issues, reviser fixes. Error = issue count or severity-weighted score.
+- **Refinement loops** — initial output, iterate to improve. Error = distance from target spec / rubric score.
+- **Tool-use retry chains** — agent calls tool, gets back error/success, retries. Error = consecutive failure count or aggregate score.
+- **RAG with self-correction** — retrieve, generate, critique, re-retrieve. Error = critique severity or hallucination score.
+- **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.0 → loopgain-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopgain"
-version = "0.1.0"
+version = "0.1.2"
 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"
@@ -13,14 +13,42 @@ requires-python = ">=3.10"
 keywords = [
     "ai",
     "agent",
-    "barkhausen",
-    "loop-stability",
-    "control-theory",
-    "feedback-loop",
-    "llm",
+    "ai-agent",
+    "ai-agents",
     "agentic",
+    "agentic-ai",
+    "llm",
+    "llm-agent",
+    "llm-orchestration",
+    "agent-orchestration",
+    "agent-loop",
     "verify-revise",
+    "verify-revise-loop",
+    "gvr",
+    "generator-verifier-reviser",
     "convergence",
+    "divergence-detection",
+    "infinite-loop",
+    "infinite-loop-detection",
+    "loop-detection",
+    "loop-stability",
+    "stability-monitor",
+    "early-stopping",
+    "max-iterations",
+    "barkhausen",
+    "barkhausen-criterion",
+    "control-theory",
+    "feedback-loop",
+    "feedback-loop-stability",
+    "loop-gain",
+    "rollback",
+    "best-so-far",
+    "langgraph",
+    "crewai",
+    "autogen",
+    "claude",
+    "anthropic",
+    "openai",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",