loopgain 0.1.4__tar.gz → 0.1.7__tar.gz

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.4
+Version: 0.1.7
 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>
+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
@@ -24,6 +24,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.4; extra == "autogen"
+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"
 Dynamic: license-file
 
 # LoopGain
@@ -87,7 +97,14 @@ print(result.savings_vs_fixed_cap)
 
 ## How it works
 
-LoopGain measures empirical loop gain `Aβ = E(n) / E(n-1)` at every iteration. It smooths Aβ with a configurable EMA and classifies the result into five named bands:
+LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+
+```
+Aβ(n)     = E(n) / E(n-1)
+Aβ_smooth = EMA(Aβ, w=3)
+```
+
+It classifies `Aβ_smooth` into five named bands:
 
 | `Aβ_smooth` range | State | Action |
 | --- | --- | --- |
@@ -205,6 +222,107 @@ The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. Th
 
 ---
 
+## Framework adapters
+
+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
+```
+
+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).
+
+### LangGraph
+
+Drives `graph.stream(input, stream_mode="updates")`. Each update is one iteration.
+
+```python
+from loopgain import LoopGain
+from loopgain.integrations import LangGraphAdapter
+
+graph = build_my_verify_revise_graph().compile()
+lg = LoopGain(target_error=0.1, max_iterations=20)
+
+adapter = LangGraphAdapter(
+    lg=lg,
+    error_fn=lambda update: len(update.get("verifier", {}).get("errors", [])),
+)
+final_state = adapter.run(graph, {"draft": initial})
+
+lg.send_telemetry(
+    endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],
+    token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],
+    workload_id="rag-rewrite",
+    framework=adapter.framework_name,        # "langgraph", auto-stamped
+)
+```
+
+`adapter.stream(...)` yields each item if you want the full trace; `adapter.arun(...)` / `adapter.astream(...)` are the async counterparts and accept an async `error_fn`.
+
+### CrewAI
+
+Installs `step_callback` and/or `task_callback` on a Crew. Pick whichever granularity matches your loop — `step_error_fn` for refinement *within* a Task, `task_error_fn` for refinement *across* Tasks.
+
+```python
+from crewai import Crew
+from loopgain import LoopGain
+from loopgain.integrations import CrewAIAdapter
+
+lg = LoopGain(target_error=0.1, max_iterations=20)
+adapter = CrewAIAdapter(
+    lg=lg,
+    task_error_fn=lambda task_output: count_failed_checks(task_output.raw),
+)
+crew = Crew(agents=[...], tasks=[...])
+adapter.install(crew)
+result = crew.kickoff()
+adapter.uninstall()         # or use `with CrewAIAdapter(...) as a:` context
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "crewai"
+)
+```
+
+The adapter chains with any callback you already had installed — your existing instrumentation isn't overwritten.
+
+### AutoGen (v0.4+)
+
+Wraps `team.run_stream(task=...)`. In a verify-revise rotation, filter to the verifier's messages with `observe_sources={"verifier"}` so only it drives `observe()`.
+
+```python
+from autogen_agentchat.teams import RoundRobinGroupChat
+from loopgain import LoopGain
+from loopgain.integrations import AutoGenAdapter
+
+team = RoundRobinGroupChat(participants=[generator, verifier])
+lg = LoopGain(target_error=0.1, max_iterations=20)
+adapter = AutoGenAdapter(
+    lg=lg,
+    error_fn=lambda msg: parse_verifier_score(msg.content),
+    observe_sources={"verifier"},
+)
+result = await adapter.run(team, task="...")
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "autogen"
+)
+```
+
+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.
+
+### 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.
+
+---
+
 ## Status
 
 **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.

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

@@ -59,7 +59,14 @@ print(result.savings_vs_fixed_cap)
 
 ## How it works
 
-LoopGain measures empirical loop gain `Aβ = E(n) / E(n-1)` at every iteration. It smooths Aβ with a configurable EMA and classifies the result into five named bands:
+LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+
+```
+Aβ(n)     = E(n) / E(n-1)
+Aβ_smooth = EMA(Aβ, w=3)
+```
+
+It classifies `Aβ_smooth` into five named bands:
 
 | `Aβ_smooth` range | State | Action |
 | --- | --- | --- |
@@ -177,6 +184,107 @@ The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. Th
 
 ---
 
+## Framework adapters
+
+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
+```
+
+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).
+
+### LangGraph
+
+Drives `graph.stream(input, stream_mode="updates")`. Each update is one iteration.
+
+```python
+from loopgain import LoopGain
+from loopgain.integrations import LangGraphAdapter
+
+graph = build_my_verify_revise_graph().compile()
+lg = LoopGain(target_error=0.1, max_iterations=20)
+
+adapter = LangGraphAdapter(
+    lg=lg,
+    error_fn=lambda update: len(update.get("verifier", {}).get("errors", [])),
+)
+final_state = adapter.run(graph, {"draft": initial})
+
+lg.send_telemetry(
+    endpoint=os.environ["LOOPGAIN_TELEMETRY_ENDPOINT"],
+    token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],
+    workload_id="rag-rewrite",
+    framework=adapter.framework_name,        # "langgraph", auto-stamped
+)
+```
+
+`adapter.stream(...)` yields each item if you want the full trace; `adapter.arun(...)` / `adapter.astream(...)` are the async counterparts and accept an async `error_fn`.
+
+### CrewAI
+
+Installs `step_callback` and/or `task_callback` on a Crew. Pick whichever granularity matches your loop — `step_error_fn` for refinement *within* a Task, `task_error_fn` for refinement *across* Tasks.
+
+```python
+from crewai import Crew
+from loopgain import LoopGain
+from loopgain.integrations import CrewAIAdapter
+
+lg = LoopGain(target_error=0.1, max_iterations=20)
+adapter = CrewAIAdapter(
+    lg=lg,
+    task_error_fn=lambda task_output: count_failed_checks(task_output.raw),
+)
+crew = Crew(agents=[...], tasks=[...])
+adapter.install(crew)
+result = crew.kickoff()
+adapter.uninstall()         # or use `with CrewAIAdapter(...) as a:` context
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "crewai"
+)
+```
+
+The adapter chains with any callback you already had installed — your existing instrumentation isn't overwritten.
+
+### AutoGen (v0.4+)
+
+Wraps `team.run_stream(task=...)`. In a verify-revise rotation, filter to the verifier's messages with `observe_sources={"verifier"}` so only it drives `observe()`.
+
+```python
+from autogen_agentchat.teams import RoundRobinGroupChat
+from loopgain import LoopGain
+from loopgain.integrations import AutoGenAdapter
+
+team = RoundRobinGroupChat(participants=[generator, verifier])
+lg = LoopGain(target_error=0.1, max_iterations=20)
+adapter = AutoGenAdapter(
+    lg=lg,
+    error_fn=lambda msg: parse_verifier_score(msg.content),
+    observe_sources={"verifier"},
+)
+result = await adapter.run(team, task="...")
+
+lg.send_telemetry(
+    endpoint=...,
+    token=...,
+    framework=adapter.framework_name,        # "autogen"
+)
+```
+
+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.
+
+### 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.
+
+---
+
 ## Status
 
 **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.

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

@@ -9,6 +9,7 @@ Public API:
     result = lg.result
 """
 
+from loopgain._version import __version__
 from loopgain.core import (
     LoopGain,
     LoopGainResult,
@@ -24,8 +25,6 @@ from loopgain.core import (
 )
 from loopgain.telemetry import build_payload as build_telemetry_payload
 
-__version__ = "0.1.4"
-
 __all__ = [
     "LoopGain",
     "LoopGainResult",

loopgain-0.1.7/loopgain/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for the package version.
+
+Both ``loopgain/__init__.py`` and ``loopgain/telemetry.py`` import
+``__version__`` from here so the value never drifts between
+``__version__`` and the ``library_version`` field on telemetry payloads.
+Update this file (and ``pyproject.toml``) for each release.
+"""
+
+__version__ = "0.1.7"

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

@@ -398,24 +398,41 @@ class LoopGain:
         token: str,
         workload_id: Optional[str] = None,
         timeout: float = 2.0,
+        allow_insecure: bool = False,
+        framework: Optional[str] = None,
+        loop_type: Optional[str] = None,
+        team: Optional[str] = None,
+        include_per_iteration: bool = True,
     ) -> bool:
         """Send anonymized telemetry to a receiver endpoint.
 
         Opt-in. Call once after the loop terminates. Sends only structural
-        statistics (state transitions, Aβ summary, gain margin, rollback
-        flag, library version, optional opaque workload label). Never sends
-        prompts, completions, error contents, or customer identity beyond
-        the bearer token.
+        statistics — Aβ values, error magnitudes, state transitions, gain
+        margin, rollback flag, library version, and optional opaque labels.
+        Never sends prompts, completions, error contents, or customer
+        identity beyond the bearer token.
 
         Best-effort: errors are swallowed; never raises. Safe to call from
         within an exception handler or finally block.
 
         Args:
-            endpoint: Telemetry receiver URL.
+            endpoint: Telemetry receiver URL. Must use ``https://``;
+                ``http://`` is rejected unless ``allow_insecure`` is ``True``.
             token: Bearer token issued by the receiver (rotatable).
             workload_id: Optional opaque label that groups related loops in
                 the dashboard. Never used to identify the customer.
             timeout: Per-request timeout in seconds. Default 2.0.
+            allow_insecure: If ``True``, permit ``http://`` endpoints (for
+                local development). Default ``False``.
+            framework: Optional classification — agent framework name
+                (``"langgraph"``, ``"crewai"``, etc.). Adapters auto-stamp.
+            loop_type: Optional classification — loop pattern name
+                (``"verify_revise"``, ``"rag_refine"``, etc.).
+            team: Optional classification — team or environment label.
+            include_per_iteration: If ``True`` (default), include the
+                per-iteration Aβ + error trajectories (capped) so the
+                dashboard's Loop Detail scrubber works. Set ``False`` to
+                send only aggregate summary stats.
 
         Returns:
             ``True`` on 2xx response, ``False`` otherwise.
@@ -429,9 +446,20 @@ class LoopGain:
             ...     endpoint="https://telemetry.loopgain.ai/v1/aggregate",
             ...     token="your-token-here",
             ...     workload_id="my-rag-pipeline",
+            ...     framework="langgraph",
+            ...     loop_type="verify_revise",
             ... )
         """
         from loopgain.telemetry import build_payload, send_payload
 
-        payload = build_payload(self, workload_id=workload_id)
-        return send_payload(endpoint, token, payload, timeout=timeout)
+        payload = build_payload(
+            self,
+            workload_id=workload_id,
+            framework=framework,
+            loop_type=loop_type,
+            team=team,
+            include_per_iteration=include_per_iteration,
+        )
+        return send_payload(
+            endpoint, token, payload, timeout=timeout, allow_insecure=allow_insecure
+        )

loopgain-0.1.7/loopgain/integrations/__init__.py

@@ -0,0 +1,66 @@
+"""Framework integration adapters for LoopGain.
+
+Each adapter is a thin wrapper that drives the host framework's iteration,
+calls ``LoopGain.observe()`` on each step with an error magnitude derived
+from a user-provided ``error_fn``, and (optionally) sends telemetry on
+completion with ``framework="<name>"`` auto-stamped.
+
+Adapters are isolated submodules so the host frameworks (langgraph, crewai,
+autogen) remain *optional* dependencies. Importing this package does not
+import any framework — each adapter only imports its framework when its
+class is instantiated, and surfaces a clear ``ImportError`` if missing.
+
+Install adapter extras::
+
+    pip install 'loopgain[langgraph]'   # LangGraph
+    pip install 'loopgain[crewai]'      # CrewAI
+    pip install 'loopgain[autogen]'     # AutoGen v0.4+
+    pip install 'loopgain[all]'         # all of the above
+
+Common pattern::
+
+    from loopgain import LoopGain
+    from loopgain.integrations import LangGraphAdapter   # or CrewAIAdapter, AutoGenAdapter
+
+    lg = LoopGain(target_error=0.1, max_iterations=20)
+    adapter = LangGraphAdapter(
+        lg=lg,
+        error_fn=lambda update: len(update.get("verifier_errors") or []),
+    )
+    final_state = adapter.run(graph, input_state)
+
+    # Optional: ship telemetry with framework auto-stamped.
+    lg.send_telemetry(
+        endpoint="https://telemetry.loopgain.ai/v1/aggregate",
+        token=os.environ["LOOPGAIN_TELEMETRY_TOKEN"],
+        workload_id="rag-rewrite",
+        framework=adapter.framework_name,   # "langgraph"
+    )
+"""
+
+from __future__ import annotations
+
+# Adapters are imported lazily so importing this package does NOT pull in
+# langgraph / crewai / autogen. Each name resolves on first attribute access
+# and surfaces a clear ImportError if its host framework isn't installed.
+__all__ = [
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "AutoGenAdapter",
+]
+
+
+def __getattr__(name: str):
+    if name == "LangGraphAdapter":
+        from loopgain.integrations.langgraph import LangGraphAdapter
+
+        return LangGraphAdapter
+    if name == "CrewAIAdapter":
+        from loopgain.integrations.crewai import CrewAIAdapter
+
+        return CrewAIAdapter
+    if name == "AutoGenAdapter":
+        from loopgain.integrations.autogen import AutoGenAdapter
+
+        return AutoGenAdapter
+    raise AttributeError(f"module 'loopgain.integrations' has no attribute {name!r}")

loopgain-0.1.7/loopgain/integrations/autogen.py

@@ -0,0 +1,156 @@
+"""AutoGen v0.4+ adapter for LoopGain.
+
+AutoGen v0.4 reorganized around an event-driven async runtime: a Team
+(``RoundRobinGroupChat``, ``SocietyOfMindAgent``, ``Swarm``, etc.) exposes
+``run_stream(task=...)`` which yields ``BaseAgentEvent | BaseChatMessage``
+items per message, terminating with a ``TaskResult``.
+
+In a verify-revise pattern the Team is typically a 2-agent rotation
+(generator → verifier → generator → ...). The verifier's most recent
+message carries the error signal; the user's ``error_fn`` extracts it
+and the adapter feeds it to LoopGain.
+
+Reference: https://microsoft.github.io/autogen/stable/_modules/autogen_agentchat/teams/_group_chat/_base_group_chat.html
+
+The adapter does NOT support the legacy v0.2 ``ConversableAgent.initiate_chat``
+API. v0.2 is in maintenance mode upstream; users on the old runtime
+should upgrade or fall back to the raw ``LoopGain.observe()`` loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, AsyncIterator, Awaitable, Callable, List, Optional
+
+if TYPE_CHECKING:
+    from loopgain.core import LoopGain
+
+
+AsyncMessageErrorFn = Callable[[Any], Awaitable[Optional[float]]]
+MessageErrorFn = Callable[[Any], Optional[float]]
+
+
+class AutoGenAdapter:
+    """Drive an AutoGen v0.4+ Team with a LoopGain monitor.
+
+    Args:
+        lg: A ``LoopGain`` instance to drive.
+        error_fn: Maps one streamed message/event to an error magnitude.
+            Return ``None`` to skip (e.g. for non-verifier messages).
+            Both sync and async callables are accepted; if async, await
+            in the function body — the adapter will detect and handle.
+        observe_sources: Optional set of agent ``source`` names to observe.
+            If provided, messages from other sources are passed through
+            without invoking ``error_fn``. Useful when only the verifier
+            agent's messages carry an error signal.
+
+    Example::
+
+        from autogen_agentchat.teams import RoundRobinGroupChat
+        from loopgain import LoopGain
+        from loopgain.integrations import AutoGenAdapter
+
+        team = RoundRobinGroupChat(participants=[generator, verifier])
+        lg = LoopGain(target_error=0.1, max_iterations=20)
+        adapter = AutoGenAdapter(
+            lg=lg,
+            error_fn=lambda msg: parse_verifier_score(msg.content),
+            observe_sources={"verifier"},
+        )
+        result = await adapter.run(team, task="Write a haiku about loops.")
+    """
+
+    framework_name = "autogen"
+
+    def __init__(
+        self,
+        lg: "LoopGain",
+        error_fn: MessageErrorFn,
+        observe_sources: Optional[set[str]] = None,
+    ) -> None:
+        self.lg = lg
+        self.error_fn = error_fn
+        self.observe_sources = observe_sources
+
+    async def run(
+        self,
+        team: Any,
+        task: Any,
+        cancellation_token: Optional[Any] = None,
+    ) -> List[Any]:
+        """Drive ``team.run_stream(task=...)`` to completion, returning
+        the full list of yielded messages/events (including the terminal
+        ``TaskResult``).
+
+        If LoopGain reaches a terminal state mid-stream, the team is
+        cancelled via the supplied ``cancellation_token`` (if one was
+        provided) — AutoGen has no way to interrupt a stream from outside
+        the cancellation-token mechanism.
+        """
+        out: List[Any] = []
+        async for item in self.stream(team, task, cancellation_token=cancellation_token):
+            out.append(item)
+        return out
+
+    async def stream(
+        self,
+        team: Any,
+        task: Any,
+        cancellation_token: Optional[Any] = None,
+    ) -> AsyncIterator[Any]:
+        """Yield each message/event from ``team.run_stream`` while driving
+        LoopGain. Cancels the team's cancellation_token when LoopGain
+        signals a terminal state, then breaks out of the iteration.
+
+        AutoGen's runtime raises ``asyncio.CancelledError`` from its own
+        internal tasks once the token is cancelled. The adapter catches
+        that error iff *we* initiated the cancellation, so callers see a
+        clean termination instead of an exception they didn't ask for."""
+        kwargs: dict[str, Any] = {"task": task}
+        if cancellation_token is not None:
+            kwargs["cancellation_token"] = cancellation_token
+
+        we_cancelled = False
+        iterator = team.run_stream(**kwargs).__aiter__()
+        while True:
+            try:
+                message = await iterator.__anext__()
+            except StopAsyncIteration:
+                break
+            except asyncio.CancelledError:
+                if we_cancelled:
+                    break
+                raise
+
+            yield message
+
+            # Don't observe the terminal TaskResult — it's a wrapper, not
+            # a per-iteration event. Detect by duck-typing on the
+            # `messages` + `stop_reason` attributes (AutoGen's TaskResult
+            # shape) so we don't have to import the framework.
+            if hasattr(message, "messages") and hasattr(message, "stop_reason"):
+                continue
+
+            # Source-filter: skip messages we're not configured to observe.
+            if self.observe_sources is not None:
+                source = getattr(message, "source", None)
+                if source not in self.observe_sources:
+                    continue
+
+            magnitude = self.error_fn(message)
+            # Allow the user to write either a sync or async error_fn.
+            if hasattr(magnitude, "__await__"):
+                magnitude = await magnitude  # type: ignore[assignment]
+
+            if magnitude is not None:
+                self.lg.observe(magnitude, output=message)
+
+            if not self.lg.should_continue() and cancellation_token is not None:
+                # Best-effort: AutoGen uses the cancellation token to abort.
+                cancel = getattr(cancellation_token, "cancel", None)
+                if callable(cancel):
+                    cancel()
+                    we_cancelled = True
+                    # Stop pulling from the iterator. The next __anext__
+                    # would raise CancelledError once the runtime tears down.
+                    break