loopgain 0.1.9__tar.gz → 0.3.0__tar.gz

{loopgain-0.1.9 → loopgain-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.9
+Version: 0.3.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
 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,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
+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,langchain,openai-agents,openai-agents-sdk,claude-agent-sdk,claude,anthropic,openai
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -30,10 +30,19 @@ Provides-Extra: crewai
 Requires-Dist: crewai>=0.30; extra == "crewai"
 Provides-Extra: autogen
 Requires-Dist: autogen-agentchat>=0.4; extra == "autogen"
+Provides-Extra: langchain
+Requires-Dist: langchain>=1.0; extra == "langchain"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == "openai-agents"
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2; extra == "claude-agent-sdk"
 Provides-Extra: all
 Requires-Dist: langgraph>=0.2; extra == "all"
 Requires-Dist: crewai>=0.30; extra == "all"
 Requires-Dist: autogen-agentchat>=0.4; extra == "all"
+Requires-Dist: langchain>=1.0; extra == "all"
+Requires-Dist: openai-agents>=0.1; extra == "all"
+Requires-Dist: claude-agent-sdk>=0.2; extra == "all"
 Provides-Extra: examples
 Requires-Dist: anthropic>=0.40.0; extra == "examples"
 Dynamic: license-file
@@ -42,16 +51,16 @@ 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)
 
-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. **Pre-built adapters for [LangGraph](#langgraph), [CrewAI](#crewai), and [AutoGen](#autogen-v04)**; drop-in via the raw API for **Claude Agent SDK** and any custom stack. Pure Python, no runtime dependencies.
+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. **Pre-built adapters for [LangGraph](#langgraph), [CrewAI](#crewai), [AutoGen](#autogen-v04), [LangChain](#langchain), [OpenAI Agents SDK](#openai-agents-sdk), and [Claude Agent SDK](#claude-agent-sdk)**; drop-in via the raw API for any custom stack. 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.
 
@@ -88,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)
@@ -101,28 +110,32 @@ print(result.savings_vs_fixed_cap)
 
 ## 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.
 
 ---
 
@@ -154,14 +167,16 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ## 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=None, 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.
+- `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`
@@ -174,7 +189,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`
 
@@ -224,6 +239,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
@@ -231,10 +272,13 @@ The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. Th
 Thin wrappers under `loopgain.integrations` drive each major agent framework's iteration with a `LoopGain` monitor and auto-stamp `framework="<name>"` on telemetry. The frameworks themselves are **optional dependencies** — install the extra you need:
 
 ```bash
-pip install 'loopgain[langgraph]'   # LangGraph
-pip install 'loopgain[crewai]'      # CrewAI
-pip install 'loopgain[autogen]'     # AutoGen v0.4+
-pip install 'loopgain[all]'         # all three
+pip install 'loopgain[langgraph]'          # LangGraph
+pip install 'loopgain[crewai]'             # CrewAI
+pip install 'loopgain[autogen]'            # AutoGen v0.4+
+pip install 'loopgain[langchain]'          # LangChain (create_agent / AgentExecutor)
+pip install 'loopgain[openai-agents]'      # OpenAI Agents SDK
+pip install 'loopgain[claude-agent-sdk]'   # Anthropic Claude Agent SDK
+pip install 'loopgain[all]'                # all six
 ```
 
 All adapters take a `LoopGain` instance plus an `error_fn` you provide — the framework doesn't know what your error signal is, so the adapter doesn't either. `error_fn` returns a non-negative number (or `None` to skip an iteration).
@@ -321,15 +365,120 @@ lg.send_telemetry(
 
 Pass a `cancellation_token` to `adapter.run(...)` and the adapter will cancel it when LoopGain reaches a terminal state (target met, oscillation, divergence). The legacy v0.2 `ConversableAgent.initiate_chat` API is **not** supported — use the v0.4 event-driven runtime.
 
+### LangChain
+
+Duck-types against any LangChain agent that exposes `.stream(input, **kwargs)` / `.astream(input, **kwargs)` — both the current `langchain.agents.create_agent()` (v1+) and the legacy `AgentExecutor`. The adapter forwards `**stream_kwargs` verbatim, so the chunk shape your `error_fn` sees is the one your agent emits.
+
+```python
+from langchain.agents import create_agent
+from loopgain import LoopGain
+from loopgain.integrations import LangChainAdapter
+
+agent = create_agent(model="gpt-5-nano", tools=[get_weather])
+lg = LoopGain(target_error=0.0, max_iterations=20)
+
+def error_fn(chunk):
+    if chunk.get("type") != "updates":
+        return None
+    # Count unresolved tool calls; drops to 0 once the agent stops calling tools.
+    return sum(
+        1 for _, update in chunk["data"].items()
+        if getattr(update.get("messages", [None])[-1], "tool_calls", None)
+    )
+
+adapter = LangChainAdapter(lg=lg, error_fn=error_fn)
+final = adapter.run(
+    agent,
+    {"messages": [{"role": "user", "content": "What's the weather?"}]},
+    stream_mode="updates",
+    version="v2",
+)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "langchain"
+)
+```
+
+For legacy `AgentExecutor`: just drop the `stream_mode` / `version` kwargs; each yielded chunk is an `AddableDict` per step (parse `intermediate_steps` or the terminal `output` key in your `error_fn`).
+
+### OpenAI Agents SDK
+
+Wraps `Runner.run_streamed(agent, input).stream_events()`. The SDK is async-first; the adapter mirrors that. A `run_sync` helper wraps the async path with `asyncio.run` for synchronous callers.
+
+```python
+from agents import Agent, function_tool
+from loopgain import LoopGain
+from loopgain.integrations import OpenAIAgentsAdapter
+
+agent = Agent(name="Reviser", instructions="...", tools=[...])
+
+lg = LoopGain(target_error=0.0, max_iterations=20)
+
+def error_fn(event):
+    # Default observes only run_item_stream_event; pull the verifier's
+    # reported failure count off tool outputs.
+    if event.item.type == "tool_call_output_item":
+        return float(event.item.output.get("failures", 0))
+    return None
+
+adapter = OpenAIAgentsAdapter(lg=lg, error_fn=error_fn)
+result = await adapter.run(agent, input="Fix the bug.")
+print(result.final_output)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "openai-agents"
+)
+```
+
+By default the adapter only forwards `run_item_stream_event` to `error_fn` — pass `observe_event_types=None` to see every event (including raw token deltas and agent-handoff notifications). When LoopGain reaches a terminal state, the adapter best-effort calls `.cancel()` on the underlying `RunResultStreaming`.
+
+### Claude Agent SDK
+
+Wraps Anthropic's `claude_agent_sdk.query(prompt=..., options=...)` async iterator. By default observes only `AssistantMessage` (skips `UserMessage` / `SystemMessage` / `ResultMessage`); override with `observe_message_types=None` or a custom tuple.
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, TextBlock
+from loopgain import LoopGain
+from loopgain.integrations import ClaudeAgentSDKAdapter
+
+def error_fn(message):
+    # Count `FAIL:` markers a self-verifying persona emits.
+    for block in getattr(message, "content", []):
+        if isinstance(block, TextBlock):
+            return float(block.text.count("FAIL:"))
+    return None
+
+lg = LoopGain(target_error=0.0, max_iterations=20)
+adapter = ClaudeAgentSDKAdapter(lg=lg, error_fn=error_fn)
+
+options = ClaudeAgentOptions(system_prompt="Self-verify each draft.")
+result = await adapter.run(
+    prompt="Write a haiku about feedback loops.",
+    options=options,
+)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "claude-agent-sdk"
+)
+```
+
+For the bidirectional `ClaudeSDKClient` use case, pass `message_iterator=client.receive_messages()` instead of `prompt=...`.
+
 ### Custom integrations
 
-For frameworks without an adapter, the raw `LoopGain.observe()` API works against any iterable. The adapters are 100-200 lines each — copy one of `loopgain/integrations/{langgraph,crewai,autogen}.py` as a starting point.
+For frameworks without an adapter, the raw `LoopGain.observe()` API works against any iterable. The adapters are 100-200 lines each — copy one of `loopgain/integrations/{langgraph,crewai,autogen,langchain,openai_agents,claude_agent_sdk}.py` as a starting point.
 
 ---
 
 ## Status
 
-**Initial public release.** Core library shipped (current version: see the PyPI badge at the top). Framework adapters (LangGraph, CrewAI, AutoGen) are installable as optional extras. The cloud-aggregator [telemetry receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are live as separate open-source repos. 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, LangChain, OpenAI Agents SDK, Claude Agent SDK) are installable as optional extras. The cloud-aggregator [telemetry receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are live as separate open-source repos. 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.
 

{loopgain-0.1.9 → loopgain-0.3.0}/README.md

@@ -2,16 +2,16 @@
 
 **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)
 
-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. **Pre-built adapters for [LangGraph](#langgraph), [CrewAI](#crewai), and [AutoGen](#autogen-v04)**; drop-in via the raw API for **Claude Agent SDK** and any custom stack. Pure Python, no runtime dependencies.
+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. **Pre-built adapters for [LangGraph](#langgraph), [CrewAI](#crewai), [AutoGen](#autogen-v04), [LangChain](#langchain), [OpenAI Agents SDK](#openai-agents-sdk), and [Claude Agent SDK](#claude-agent-sdk)**; drop-in via the raw API for any custom stack. 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.
 
@@ -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)
@@ -61,28 +61,32 @@ print(result.savings_vs_fixed_cap)
 
 ## 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.
 
 ---
 
@@ -114,14 +118,16 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ## 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=None, 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.
+- `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 +140,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 +190,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
@@ -191,10 +223,13 @@ The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. Th
 Thin wrappers under `loopgain.integrations` drive each major agent framework's iteration with a `LoopGain` monitor and auto-stamp `framework="<name>"` on telemetry. The frameworks themselves are **optional dependencies** — install the extra you need:
 
 ```bash
-pip install 'loopgain[langgraph]'   # LangGraph
-pip install 'loopgain[crewai]'      # CrewAI
-pip install 'loopgain[autogen]'     # AutoGen v0.4+
-pip install 'loopgain[all]'         # all three
+pip install 'loopgain[langgraph]'          # LangGraph
+pip install 'loopgain[crewai]'             # CrewAI
+pip install 'loopgain[autogen]'            # AutoGen v0.4+
+pip install 'loopgain[langchain]'          # LangChain (create_agent / AgentExecutor)
+pip install 'loopgain[openai-agents]'      # OpenAI Agents SDK
+pip install 'loopgain[claude-agent-sdk]'   # Anthropic Claude Agent SDK
+pip install 'loopgain[all]'                # all six
 ```
 
 All adapters take a `LoopGain` instance plus an `error_fn` you provide — the framework doesn't know what your error signal is, so the adapter doesn't either. `error_fn` returns a non-negative number (or `None` to skip an iteration).
@@ -281,15 +316,120 @@ lg.send_telemetry(
 
 Pass a `cancellation_token` to `adapter.run(...)` and the adapter will cancel it when LoopGain reaches a terminal state (target met, oscillation, divergence). The legacy v0.2 `ConversableAgent.initiate_chat` API is **not** supported — use the v0.4 event-driven runtime.
 
+### LangChain
+
+Duck-types against any LangChain agent that exposes `.stream(input, **kwargs)` / `.astream(input, **kwargs)` — both the current `langchain.agents.create_agent()` (v1+) and the legacy `AgentExecutor`. The adapter forwards `**stream_kwargs` verbatim, so the chunk shape your `error_fn` sees is the one your agent emits.
+
+```python
+from langchain.agents import create_agent
+from loopgain import LoopGain
+from loopgain.integrations import LangChainAdapter
+
+agent = create_agent(model="gpt-5-nano", tools=[get_weather])
+lg = LoopGain(target_error=0.0, max_iterations=20)
+
+def error_fn(chunk):
+    if chunk.get("type") != "updates":
+        return None
+    # Count unresolved tool calls; drops to 0 once the agent stops calling tools.
+    return sum(
+        1 for _, update in chunk["data"].items()
+        if getattr(update.get("messages", [None])[-1], "tool_calls", None)
+    )
+
+adapter = LangChainAdapter(lg=lg, error_fn=error_fn)
+final = adapter.run(
+    agent,
+    {"messages": [{"role": "user", "content": "What's the weather?"}]},
+    stream_mode="updates",
+    version="v2",
+)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "langchain"
+)
+```
+
+For legacy `AgentExecutor`: just drop the `stream_mode` / `version` kwargs; each yielded chunk is an `AddableDict` per step (parse `intermediate_steps` or the terminal `output` key in your `error_fn`).
+
+### OpenAI Agents SDK
+
+Wraps `Runner.run_streamed(agent, input).stream_events()`. The SDK is async-first; the adapter mirrors that. A `run_sync` helper wraps the async path with `asyncio.run` for synchronous callers.
+
+```python
+from agents import Agent, function_tool
+from loopgain import LoopGain
+from loopgain.integrations import OpenAIAgentsAdapter
+
+agent = Agent(name="Reviser", instructions="...", tools=[...])
+
+lg = LoopGain(target_error=0.0, max_iterations=20)
+
+def error_fn(event):
+    # Default observes only run_item_stream_event; pull the verifier's
+    # reported failure count off tool outputs.
+    if event.item.type == "tool_call_output_item":
+        return float(event.item.output.get("failures", 0))
+    return None
+
+adapter = OpenAIAgentsAdapter(lg=lg, error_fn=error_fn)
+result = await adapter.run(agent, input="Fix the bug.")
+print(result.final_output)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "openai-agents"
+)
+```
+
+By default the adapter only forwards `run_item_stream_event` to `error_fn` — pass `observe_event_types=None` to see every event (including raw token deltas and agent-handoff notifications). When LoopGain reaches a terminal state, the adapter best-effort calls `.cancel()` on the underlying `RunResultStreaming`.
+
+### Claude Agent SDK
+
+Wraps Anthropic's `claude_agent_sdk.query(prompt=..., options=...)` async iterator. By default observes only `AssistantMessage` (skips `UserMessage` / `SystemMessage` / `ResultMessage`); override with `observe_message_types=None` or a custom tuple.
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, TextBlock
+from loopgain import LoopGain
+from loopgain.integrations import ClaudeAgentSDKAdapter
+
+def error_fn(message):
+    # Count `FAIL:` markers a self-verifying persona emits.
+    for block in getattr(message, "content", []):
+        if isinstance(block, TextBlock):
+            return float(block.text.count("FAIL:"))
+    return None
+
+lg = LoopGain(target_error=0.0, max_iterations=20)
+adapter = ClaudeAgentSDKAdapter(lg=lg, error_fn=error_fn)
+
+options = ClaudeAgentOptions(system_prompt="Self-verify each draft.")
+result = await adapter.run(
+    prompt="Write a haiku about feedback loops.",
+    options=options,
+)
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "claude-agent-sdk"
+)
+```
+
+For the bidirectional `ClaudeSDKClient` use case, pass `message_iterator=client.receive_messages()` instead of `prompt=...`.
+
 ### Custom integrations
 
-For frameworks without an adapter, the raw `LoopGain.observe()` API works against any iterable. The adapters are 100-200 lines each — copy one of `loopgain/integrations/{langgraph,crewai,autogen}.py` as a starting point.
+For frameworks without an adapter, the raw `LoopGain.observe()` API works against any iterable. The adapters are 100-200 lines each — copy one of `loopgain/integrations/{langgraph,crewai,autogen,langchain,openai_agents,claude_agent_sdk}.py` as a starting point.
 
 ---
 
 ## Status
 
-**Initial public release.** Core library shipped (current version: see the PyPI badge at the top). Framework adapters (LangGraph, CrewAI, AutoGen) are installable as optional extras. The cloud-aggregator [telemetry receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are live as separate open-source repos. 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, LangChain, OpenAI Agents SDK, Claude Agent SDK) are installable as optional extras. The cloud-aggregator [telemetry receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are live as separate open-source repos. 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.
 

{loopgain-0.1.9 → loopgain-0.3.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.3.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.3.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.3.0"