loopgain 0.2.0__tar.gz → 0.4.0__tar.gz

{loopgain-0.2.0 → loopgain-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.2.0
+Version: 0.4.0
 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 <hello@loopgain.ai>
 License: Apache-2.0
@@ -51,12 +51,12 @@ Dynamic: license-file
 
 **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.
+Replace `max_iterations=5` with a real-time trajectory classifier that reads four features off the loop's error series and routes it into one of five named states — knowing 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-119_passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-157_passing-brightgreen.svg)](tests/)
 
 **Home:** [loopgain.ai](https://loopgain.ai)
 
@@ -97,7 +97,7 @@ while lg.should_continue():
     output = reviser.revise(output, errors)
 
 result = lg.result
-print(result.outcome)              # "converged" | "oscillating" | "diverged" | "max_iterations"
+print(result.outcome)              # "converged" | "oscillating" | "diverged" | "stalled" | "max_iterations"
 print(result.best_output)          # the lowest-error iteration's output
 print(result.iterations_used)
 print(result.gain_margin)          # 1 / max(Aβ_smooth)
@@ -108,30 +108,56 @@ print(result.savings_vs_fixed_cap)
 
 ---
 
+## Defining your error signal
+
+The one thing you provide is the **error signal**: a single non-negative number, every iteration, that says how wrong the current output is. **Lower is better; zero means done.** LoopGain doesn't know what your loop does — it just watches that number's trajectory and decides whether to keep going, stop, or roll back.
+
+Your loop already has some way of knowing the output isn't good yet (or it wouldn't keep revising). Turn that into a number:
+
+| Loop | Error signal = |
+| --- | --- |
+| Agentic coding (write code → run tests) | number of **failing tests** (10 → 3 → 0) |
+| JSON / structured extraction | number of **schema violations** |
+| RAG with self-correction | number of **required facts still missing** |
+| Self-refinement with an LLM judge | judge's **gap to target** (e.g. `10 − quality_score`) |
+| Lint / format loop | **lint error count** |
+
+The only rules: non-negative, and **smaller as the output gets better**. Returning the raw list of problems works directly — `observe()` uses its length as the magnitude (e.g. hand it the list of failing tests).
+
+If your quality is fuzzy and has no natural "zero," run with `target_error=None`: LoopGain then stops when the number **stops improving**, wherever that plateau is, instead of waiting for an exact target.
+
+Every stop/continue decision is made from this one number, so **LoopGain is only as good as the error signal you give it** — pick one that genuinely tracks output quality.
+
+---
+
 ## How it works
 
-LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+LoopGain measures empirical loop gain (`Aβ = E(n) / E(n-1)`) at every iteration and exposes it as a smoothed time series for visualization. The decision engine, however, classifies the **full error trajectory** using four features:
 
 ```
-Aβ(n)     = E(n) / E(n-1)
-Aβ_smooth = EMA(Aβ, w=3)
+E_ratio   = E_current / E_first      # cumulative reduction
+slope_log = OLS slope of log10(E)    # geometric trend direction
+slope_p   = t-test p-value of slope  # statistical significance
+osc_std   = std of detrended log10(E) # oscillation magnitude
 ```
 
-It classifies `Aβ_smooth` into five named bands:
+It routes the trajectory into one of five named states:
 
-| `Aβ_smooth` range | State | Action |
+| State | Condition | Action |
 | --- | --- | --- |
-| `< 0.3` | `FAST_CONVERGE` | Continue, predict ETA |
-| `0.3 ≤ Aβ < 0.85` | `CONVERGING` | Continue, watch for upward drift |
-| `0.85 ≤ Aβ < 0.95` | `STALLING` | Warn — diminishing returns |
-| `0.95 ≤ Aβ ≤ 1.05` | `OSCILLATING` | Break — return best-so-far |
-| `> 1.05` | `DIVERGING` | Abort — roll back to best-so-far |
+| `FAST_CONVERGE` | cumulative reduction to ≤ 10% of E_first | Continue, predict ETA |
+| `CONVERGING` | negative slope with `p < 0.05`, OR cumulative ≤ 50% | Continue, watch for upward drift |
+| `STALLING` | no significant slope, no detectable oscillation | Stop after 2 consecutive readings — return best-so-far |
+| `OSCILLATING` | high residual variance with flat trend | Stop — return best-so-far |
+| `DIVERGING` | positive slope with `p < 0.05` AND cumulative > 110% | Abort — roll back to best-so-far |
 
 Plus a short-circuit: if observed error drops at or below `target_error`, the loop stops immediately with state `TARGET_MET`. The default `target_error=0.0` short-circuits on exactly zero error — the natural completion signal for verifier-driven loops. Pass `target_error=None` to disable the short-circuit and rely on stability detection alone.
 
-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.
+The decision is **conservative by design**: requiring both statistical significance and meaningful cumulative motion before terminating prevents false-positive aborts on noisy real-LLM error series. Validated at 98.8% macro-averaged accuracy across 5 regimes on N=1000 deterministic-mock trajectories (see `RESULTS_v2_classifier.md`). The STALLING ceiling of ~94% is the t-test's irreducible 5% type-I error rate, not a classifier weakness.
 
-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.
+**Recommended minimum: 6 iterations** for reliable trend significance. At n≤4 the t-test is severely underpowered (df=2 requires |t|>4.3 for p<0.05) — the classifier conservatively falls back to STALLING when evidence is thin. The thresholds are derived analytically (control theory + statistical convention), not fitted; tune them per domain via the `TrajectoryThresholds` argument once you have production traces.
+
+**Legacy single-feature classifier:** the original v0.1 single-Aβ-band classifier (thresholds 0.3 / 0.85 / 0.95 / 1.05) is still available via `LoopGain(classifier='legacy_bands')` for callers that have empirically tuned the bands to a specific workload.
 
 ---
 
@@ -161,16 +187,27 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ---
 
+## What LoopGain does and doesn't guarantee
+
+LoopGain saves money by stopping a loop once it stops improving — fewer iterations, fewer tokens. In our [public benchmark](https://github.com/loopgain-ai/loopgain-bench), that was a **93.5% median cut in API spend** vs `max_iterations=20`, with output quality preserved. Two honest limits:
+
+- **Savings depend on your workload.** Loops that usually succeed fast save the most (~96%); adversarial, failure-prone loops save less (~84%). The headline is a blend — run the benchmark on your own loops before quoting a number.
+- **LoopGain detects convergence, not correctness.** It stops when your error signal stops improving — which means more iterations won't help, *not* that the loop succeeded. On the benchmark this preserved quality (it rarely stopped early on a worse output; false-stop rate ≤3.5%), but a loop can stall with the error still above zero — a plateau at, say, 2 failing tests. So check `result.best_error` (or your own pass/fail) before you trust the output: if it plateaued short of your target, that's a quality gap LoopGain can't see, and a false stop that forces a rerun is the one way it eats into the savings. LoopGain decides *when to stop*; you decide *whether the answer is good enough*.
+
+---
+
 ## API reference
 
-### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, smoothing_window=3, assumed_fixed_cap=10)`
+### `LoopGain(target_error=0.0, max_iterations=50, thresholds=None, trajectory_thresholds=None, classifier='trajectory', smoothing_window=3, assumed_fixed_cap=10)`
 
 Construct the monitor.
 
 - `target_error` — Stop when an observed error drops at or below this. Default `0.0` short-circuits on exactly zero error (the natural completion signal for verifier-driven loops). Pass `None` to disable the short-circuit entirely.
-- `max_iterations` — Hard safety cap. Default `None` (rely on stability detection). Recommended ~20–50 for production.
-- `thresholds` — Custom `ThresholdBands` if defaults don't fit your domain.
-- `smoothing_window` — EMA window for the smoothed Aβ. Default 3.
+- `max_iterations` — Hard safety backstop. Default `50` so the loop can never run unbounded; a stability verdict normally terminates it well before this. Pass `None` to opt into a fully unbounded loop (only safe if your loop is guaranteed to reach `target_error` or a stop-state), or a smaller integer to cap tighter.
+- `thresholds` — Custom `ThresholdBands` for the legacy single-Aβ-band classifier. Ignored when `classifier='trajectory'`.
+- `trajectory_thresholds` — Custom `TrajectoryThresholds` for the multi-feature classifier (the default). Override only with workload-specific evidence.
+- `classifier` — `'trajectory'` (default, v0.2 multi-feature classifier) or `'legacy_bands'` (v0.1 single-Aβ-band classifier).
+- `smoothing_window` — EMA window for the smoothed Aβ series (always maintained for visualization, regardless of classifier choice). Default 3.
 - `assumed_fixed_cap` — Used to compute `savings_vs_fixed_cap`. Default 10.
 
 ### `lg.observe(errors, output=None) -> str`
@@ -183,7 +220,7 @@ Returns `False` once a terminal state fires.
 
 ### `lg.state -> str`
 
-Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`.
+Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`. The corresponding terminal `result.outcome` values are `converged`, `oscillating`, `diverged`, `stalled` (v0.2 trajectory mode only — STALLING terminating after 2 consecutive readings), `max_iterations`, or `in_progress`.
 
 ### `lg.eta -> int | None`
 
@@ -233,6 +270,32 @@ What is sent: state transitions, Aβ summary (min/max/median), gain margin, roll
 
 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.
 
+> **This is not the same as anonymous usage telemetry.** `send_telemetry` sends *your* loop data to *your* dashboard, and only when you call it. There's a separate, opt-in **funnel** telemetry described below. The two never share data or code.
+
+---
+
+## Anonymous funnel telemetry (opt-in, off by default)
+
+LoopGain can report **anonymous usage counts** so a solo maintainer can tell whether the library is actually being used — install → first `observe()` → recurring use. **It is opt-in and default-decline: nothing is sent unless you explicitly turn it on.**
+
+```bash
+loopgain telemetry --show       # status + exactly what would be sent
+loopgain telemetry --enable     # opt in   (or: export LOOPGAIN_TELEMETRY=1)
+loopgain telemetry --disable    # opt out  (or: export LOOPGAIN_TELEMETRY=0)
+```
+
+`DO_NOT_TRACK=1` is honored as a hard opt-out, and CI environments are auto-detected and declined silently. When enabled, payloads carry only a locally-generated random id (not derived from your machine), hour-bucketed timestamps, library/Python/OS versions, the adapter in use, and a coarse outcome count. **Prompts, outputs, error contents, keys, paths, and IPs are never collected.** Delivery is batched, async, https-only, and fail-silent — it can never break your loop. Full details and the privacy contract: **[TELEMETRY.md](TELEMETRY.md)**.
+
+---
+
+## Command-line interface
+
+```bash
+loopgain --version              # or: loopgain version
+loopgain telemetry --show       # inspect / control anonymous funnel telemetry
+python -m loopgain telemetry --show   # equivalent, without the console script
+```
+
 ---
 
 ## Framework adapters

{loopgain-0.2.0 → loopgain-0.4.0}/README.md

@@ -2,12 +2,12 @@
 
 **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.
+Replace `max_iterations=5` with a real-time trajectory classifier that reads four features off the loop's error series and routes it into one of five named states — knowing 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-119_passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-157_passing-brightgreen.svg)](tests/)
 
 **Home:** [loopgain.ai](https://loopgain.ai)
 
@@ -48,7 +48,7 @@ while lg.should_continue():
     output = reviser.revise(output, errors)
 
 result = lg.result
-print(result.outcome)              # "converged" | "oscillating" | "diverged" | "max_iterations"
+print(result.outcome)              # "converged" | "oscillating" | "diverged" | "stalled" | "max_iterations"
 print(result.best_output)          # the lowest-error iteration's output
 print(result.iterations_used)
 print(result.gain_margin)          # 1 / max(Aβ_smooth)
@@ -59,30 +59,56 @@ print(result.savings_vs_fixed_cap)
 
 ---
 
+## Defining your error signal
+
+The one thing you provide is the **error signal**: a single non-negative number, every iteration, that says how wrong the current output is. **Lower is better; zero means done.** LoopGain doesn't know what your loop does — it just watches that number's trajectory and decides whether to keep going, stop, or roll back.
+
+Your loop already has some way of knowing the output isn't good yet (or it wouldn't keep revising). Turn that into a number:
+
+| Loop | Error signal = |
+| --- | --- |
+| Agentic coding (write code → run tests) | number of **failing tests** (10 → 3 → 0) |
+| JSON / structured extraction | number of **schema violations** |
+| RAG with self-correction | number of **required facts still missing** |
+| Self-refinement with an LLM judge | judge's **gap to target** (e.g. `10 − quality_score`) |
+| Lint / format loop | **lint error count** |
+
+The only rules: non-negative, and **smaller as the output gets better**. Returning the raw list of problems works directly — `observe()` uses its length as the magnitude (e.g. hand it the list of failing tests).
+
+If your quality is fuzzy and has no natural "zero," run with `target_error=None`: LoopGain then stops when the number **stops improving**, wherever that plateau is, instead of waiting for an exact target.
+
+Every stop/continue decision is made from this one number, so **LoopGain is only as good as the error signal you give it** — pick one that genuinely tracks output quality.
+
+---
+
 ## How it works
 
-LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+LoopGain measures empirical loop gain (`Aβ = E(n) / E(n-1)`) at every iteration and exposes it as a smoothed time series for visualization. The decision engine, however, classifies the **full error trajectory** using four features:
 
 ```
-Aβ(n)     = E(n) / E(n-1)
-Aβ_smooth = EMA(Aβ, w=3)
+E_ratio   = E_current / E_first      # cumulative reduction
+slope_log = OLS slope of log10(E)    # geometric trend direction
+slope_p   = t-test p-value of slope  # statistical significance
+osc_std   = std of detrended log10(E) # oscillation magnitude
 ```
 
-It classifies `Aβ_smooth` into five named bands:
+It routes the trajectory into one of five named states:
 
-| `Aβ_smooth` range | State | Action |
+| State | Condition | Action |
 | --- | --- | --- |
-| `< 0.3` | `FAST_CONVERGE` | Continue, predict ETA |
-| `0.3 ≤ Aβ < 0.85` | `CONVERGING` | Continue, watch for upward drift |
-| `0.85 ≤ Aβ < 0.95` | `STALLING` | Warn — diminishing returns |
-| `0.95 ≤ Aβ ≤ 1.05` | `OSCILLATING` | Break — return best-so-far |
-| `> 1.05` | `DIVERGING` | Abort — roll back to best-so-far |
+| `FAST_CONVERGE` | cumulative reduction to ≤ 10% of E_first | Continue, predict ETA |
+| `CONVERGING` | negative slope with `p < 0.05`, OR cumulative ≤ 50% | Continue, watch for upward drift |
+| `STALLING` | no significant slope, no detectable oscillation | Stop after 2 consecutive readings — return best-so-far |
+| `OSCILLATING` | high residual variance with flat trend | Stop — return best-so-far |
+| `DIVERGING` | positive slope with `p < 0.05` AND cumulative > 110% | Abort — roll back to best-so-far |
 
 Plus a short-circuit: if observed error drops at or below `target_error`, the loop stops immediately with state `TARGET_MET`. The default `target_error=0.0` short-circuits on exactly zero error — the natural completion signal for verifier-driven loops. Pass `target_error=None` to disable the short-circuit and rely on stability detection alone.
 
-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.
+The decision is **conservative by design**: requiring both statistical significance and meaningful cumulative motion before terminating prevents false-positive aborts on noisy real-LLM error series. Validated at 98.8% macro-averaged accuracy across 5 regimes on N=1000 deterministic-mock trajectories (see `RESULTS_v2_classifier.md`). The STALLING ceiling of ~94% is the t-test's irreducible 5% type-I error rate, not a classifier weakness.
 
-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.
+**Recommended minimum: 6 iterations** for reliable trend significance. At n≤4 the t-test is severely underpowered (df=2 requires |t|>4.3 for p<0.05) — the classifier conservatively falls back to STALLING when evidence is thin. The thresholds are derived analytically (control theory + statistical convention), not fitted; tune them per domain via the `TrajectoryThresholds` argument once you have production traces.
+
+**Legacy single-feature classifier:** the original v0.1 single-Aβ-band classifier (thresholds 0.3 / 0.85 / 0.95 / 1.05) is still available via `LoopGain(classifier='legacy_bands')` for callers that have empirically tuned the bands to a specific workload.
 
 ---
 
@@ -112,16 +138,27 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ---
 
+## What LoopGain does and doesn't guarantee
+
+LoopGain saves money by stopping a loop once it stops improving — fewer iterations, fewer tokens. In our [public benchmark](https://github.com/loopgain-ai/loopgain-bench), that was a **93.5% median cut in API spend** vs `max_iterations=20`, with output quality preserved. Two honest limits:
+
+- **Savings depend on your workload.** Loops that usually succeed fast save the most (~96%); adversarial, failure-prone loops save less (~84%). The headline is a blend — run the benchmark on your own loops before quoting a number.
+- **LoopGain detects convergence, not correctness.** It stops when your error signal stops improving — which means more iterations won't help, *not* that the loop succeeded. On the benchmark this preserved quality (it rarely stopped early on a worse output; false-stop rate ≤3.5%), but a loop can stall with the error still above zero — a plateau at, say, 2 failing tests. So check `result.best_error` (or your own pass/fail) before you trust the output: if it plateaued short of your target, that's a quality gap LoopGain can't see, and a false stop that forces a rerun is the one way it eats into the savings. LoopGain decides *when to stop*; you decide *whether the answer is good enough*.
+
+---
+
 ## API reference
 
-### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, smoothing_window=3, assumed_fixed_cap=10)`
+### `LoopGain(target_error=0.0, max_iterations=50, thresholds=None, trajectory_thresholds=None, classifier='trajectory', smoothing_window=3, assumed_fixed_cap=10)`
 
 Construct the monitor.
 
 - `target_error` — Stop when an observed error drops at or below this. Default `0.0` short-circuits on exactly zero error (the natural completion signal for verifier-driven loops). Pass `None` to disable the short-circuit entirely.
-- `max_iterations` — Hard safety cap. Default `None` (rely on stability detection). Recommended ~20–50 for production.
-- `thresholds` — Custom `ThresholdBands` if defaults don't fit your domain.
-- `smoothing_window` — EMA window for the smoothed Aβ. Default 3.
+- `max_iterations` — Hard safety backstop. Default `50` so the loop can never run unbounded; a stability verdict normally terminates it well before this. Pass `None` to opt into a fully unbounded loop (only safe if your loop is guaranteed to reach `target_error` or a stop-state), or a smaller integer to cap tighter.
+- `thresholds` — Custom `ThresholdBands` for the legacy single-Aβ-band classifier. Ignored when `classifier='trajectory'`.
+- `trajectory_thresholds` — Custom `TrajectoryThresholds` for the multi-feature classifier (the default). Override only with workload-specific evidence.
+- `classifier` — `'trajectory'` (default, v0.2 multi-feature classifier) or `'legacy_bands'` (v0.1 single-Aβ-band classifier).
+- `smoothing_window` — EMA window for the smoothed Aβ series (always maintained for visualization, regardless of classifier choice). Default 3.
 - `assumed_fixed_cap` — Used to compute `savings_vs_fixed_cap`. Default 10.
 
 ### `lg.observe(errors, output=None) -> str`
@@ -134,7 +171,7 @@ Returns `False` once a terminal state fires.
 
 ### `lg.state -> str`
 
-Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`.
+Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`. The corresponding terminal `result.outcome` values are `converged`, `oscillating`, `diverged`, `stalled` (v0.2 trajectory mode only — STALLING terminating after 2 consecutive readings), `max_iterations`, or `in_progress`.
 
 ### `lg.eta -> int | None`
 
@@ -184,6 +221,32 @@ What is sent: state transitions, Aβ summary (min/max/median), gain margin, roll
 
 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.
 
+> **This is not the same as anonymous usage telemetry.** `send_telemetry` sends *your* loop data to *your* dashboard, and only when you call it. There's a separate, opt-in **funnel** telemetry described below. The two never share data or code.
+
+---
+
+## Anonymous funnel telemetry (opt-in, off by default)
+
+LoopGain can report **anonymous usage counts** so a solo maintainer can tell whether the library is actually being used — install → first `observe()` → recurring use. **It is opt-in and default-decline: nothing is sent unless you explicitly turn it on.**
+
+```bash
+loopgain telemetry --show       # status + exactly what would be sent
+loopgain telemetry --enable     # opt in   (or: export LOOPGAIN_TELEMETRY=1)
+loopgain telemetry --disable    # opt out  (or: export LOOPGAIN_TELEMETRY=0)
+```
+
+`DO_NOT_TRACK=1` is honored as a hard opt-out, and CI environments are auto-detected and declined silently. When enabled, payloads carry only a locally-generated random id (not derived from your machine), hour-bucketed timestamps, library/Python/OS versions, the adapter in use, and a coarse outcome count. **Prompts, outputs, error contents, keys, paths, and IPs are never collected.** Delivery is batched, async, https-only, and fail-silent — it can never break your loop. Full details and the privacy contract: **[TELEMETRY.md](TELEMETRY.md)**.
+
+---
+
+## Command-line interface
+
+```bash
+loopgain --version              # or: loopgain version
+loopgain telemetry --show       # inspect / control anonymous funnel telemetry
+python -m loopgain telemetry --show   # equivalent, without the console script
+```
+
 ---
 
 ## Framework adapters

{loopgain-0.2.0 → loopgain-0.4.0}/loopgain/__init__.py

@@ -10,6 +10,12 @@ Public API:
 """
 
 from loopgain._version import __version__
+from loopgain.classifier import (
+    TrajectoryFeatures,
+    TrajectoryThresholds,
+    classify_trajectory,
+    extract_features,
+)
 from loopgain.core import (
     LoopGain,
     LoopGainResult,
@@ -29,6 +35,10 @@ __all__ = [
     "LoopGain",
     "LoopGainResult",
     "ThresholdBands",
+    "TrajectoryThresholds",
+    "TrajectoryFeatures",
+    "classify_trajectory",
+    "extract_features",
     "INIT",
     "FAST_CONVERGE",
     "CONVERGING",

loopgain-0.4.0/loopgain/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m loopgain`` to invoke the CLI."""
+
+import sys
+
+from loopgain.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgain-0.4.0/loopgain/_version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for the package version.
+
+``loopgain/__init__.py``, ``loopgain/telemetry.py`` (product receiver), and
+``loopgain/funnel.py`` (opt-in funnel telemetry) all import ``__version__``
+from here so the value never drifts between ``__version__`` and the
+``library_version`` field on any telemetry payload. Update this file (and
+``pyproject.toml``) for each release.
+"""
+
+__version__ = "0.4.0"