loopgain 0.1.9__tar.gz → 0.2.0__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.1.9
+Version: 0.2.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
@@ -51,7 +60,7 @@ Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows
 
 **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.
 
@@ -231,10 +240,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 +333,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.2.0}/README.md

@@ -11,7 +11,7 @@ Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows
 
 **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.
 
@@ -191,10 +191,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 +284,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.2.0}/loopgain/_version.py

@@ -6,4 +6,4 @@ Both ``loopgain/__init__.py`` and ``loopgain/telemetry.py`` import
 Update this file (and ``pyproject.toml``) for each release.
 """
 
-__version__ = "0.1.9"
+__version__ = "0.2.0"

{loopgain-0.1.9 → loopgain-0.2.0}/loopgain/integrations/__init__.py

@@ -5,22 +5,26 @@ 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.
+Adapters are isolated submodules so the host frameworks (langgraph,
+crewai, autogen, langchain, openai-agents, claude-agent-sdk) 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
+    pip install 'loopgain[langgraph]'          # LangGraph
+    pip install 'loopgain[crewai]'             # CrewAI
+    pip install 'loopgain[autogen]'            # AutoGen v0.4+
+    pip install 'loopgain[langchain]'          # LangChain (create_agent or AgentExecutor)
+    pip install 'loopgain[openai-agents]'      # OpenAI Agents SDK
+    pip install 'loopgain[claude-agent-sdk]'   # Anthropic Claude Agent SDK
+    pip install 'loopgain[all]'                # all of the above
 
 Common pattern::
 
     from loopgain import LoopGain
-    from loopgain.integrations import LangGraphAdapter   # or CrewAIAdapter, AutoGenAdapter
+    from loopgain.integrations import LangGraphAdapter   # or any other adapter
 
     lg = LoopGain(target_error=0.1, max_iterations=20)
     adapter = LangGraphAdapter(
@@ -40,13 +44,16 @@ Common pattern::
 
 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.
+# Adapters are imported lazily so importing this package does NOT pull
+# in any framework. Each name resolves on first attribute access and
+# surfaces a clear ImportError if its host framework isn't installed.
 __all__ = [
     "LangGraphAdapter",
     "CrewAIAdapter",
     "AutoGenAdapter",
+    "LangChainAdapter",
+    "OpenAIAgentsAdapter",
+    "ClaudeAgentSDKAdapter",
 ]
 
 
@@ -63,4 +70,16 @@ def __getattr__(name: str):
         from loopgain.integrations.autogen import AutoGenAdapter
 
         return AutoGenAdapter
+    if name == "LangChainAdapter":
+        from loopgain.integrations.langchain import LangChainAdapter
+
+        return LangChainAdapter
+    if name == "OpenAIAgentsAdapter":
+        from loopgain.integrations.openai_agents import OpenAIAgentsAdapter
+
+        return OpenAIAgentsAdapter
+    if name == "ClaudeAgentSDKAdapter":
+        from loopgain.integrations.claude_agent_sdk import ClaudeAgentSDKAdapter
+
+        return ClaudeAgentSDKAdapter
     raise AttributeError(f"module 'loopgain.integrations' has no attribute {name!r}")

loopgain-0.2.0/loopgain/integrations/claude_agent_sdk.py

@@ -0,0 +1,206 @@
+"""Claude Agent SDK adapter for LoopGain.
+
+Wraps Anthropic's ``claude_agent_sdk`` with a LoopGain monitor. The SDK
+is async-only: ``query(prompt=..., options=...)`` returns an async
+iterator of messages, each of which is one of:
+
+- ``UserMessage`` — the user-supplied prompt echoed back
+- ``AssistantMessage`` — model output with content blocks (``TextBlock``,
+  ``ToolUseBlock``)
+- ``SystemMessage`` — system events
+- ``ResultMessage`` — terminal message with summary fields (cost, usage)
+
+The natural iteration unit for an agent loop is one ``AssistantMessage``
+(or one full tool-call → tool-result round-trip). The user's
+``error_fn`` decides which messages carry an error signal — typically
+by inspecting ``AssistantMessage.content`` for self-reported state or
+counting unresolved ``ToolUseBlock`` entries.
+
+The adapter accepts either:
+
+- a ``prompt`` (string) and optional ``options`` — the adapter
+  constructs the ``query(...)`` iterator itself; or
+- a pre-constructed ``message_iterator`` (e.g. from
+  ``ClaudeSDKClient.receive_messages()`` or ``receive_response()``) —
+  the adapter just drives it.
+
+By default the adapter only forwards ``AssistantMessage`` instances to
+``error_fn`` (since user/system messages don't typically carry an error
+signal). Override with ``observe_message_types=None`` to observe every
+message, or pass a tuple of types to widen the filter.
+
+Reference: https://github.com/anthropics/claude-agent-sdk-python
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, AsyncIterator, Awaitable, Callable, Optional, Tuple
+
+if TYPE_CHECKING:
+    from loopgain.core import LoopGain
+
+
+MessageErrorFn = Callable[[Any], Optional[float]]
+AsyncMessageErrorFn = Callable[[Any], Awaitable[Optional[float]]]
+
+
+def _default_observe_types() -> Tuple[type, ...]:
+    """Default observation filter: ``AssistantMessage`` only.
+
+    Imported lazily so the adapter module itself stays importable
+    without ``claude_agent_sdk`` installed (importing the package is
+    what raises ``ImportError`` from ``run()`` if it's missing).
+    """
+    from claude_agent_sdk import AssistantMessage
+
+    return (AssistantMessage,)
+
+
+class ClaudeAgentSDKAdapter:
+    """Drive a Claude Agent SDK ``query`` or ``ClaudeSDKClient`` message
+    stream with a LoopGain monitor.
+
+    Args:
+        lg: A ``LoopGain`` instance to drive.
+        error_fn: Maps one yielded message to an error magnitude. Both
+            sync and async callables are accepted. Return ``None`` to
+            skip a message. Only messages of a type in
+            ``observe_message_types`` are forwarded to ``error_fn``;
+            others are yielded but not observed.
+        observe_message_types: Tuple of message classes to forward to
+            ``error_fn``. Defaults to ``(AssistantMessage,)``. Pass
+            ``None`` to observe every message regardless of type. The
+            tuple is resolved lazily on first stream so the module
+            stays importable without ``claude_agent_sdk`` installed.
+
+    Example::
+
+        from claude_agent_sdk import ClaudeAgentOptions, AssistantMessage, TextBlock
+        from loopgain import LoopGain
+        from loopgain.integrations import ClaudeAgentSDKAdapter
+
+        def error_fn(message):
+            # Count `FAIL:` markers the verifier-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,
+        )
+    """
+
+    framework_name = "claude-agent-sdk"
+
+    def __init__(
+        self,
+        lg: "LoopGain",
+        error_fn: MessageErrorFn,
+        observe_message_types: Optional[Tuple[type, ...]] = (),
+    ) -> None:
+        self.lg = lg
+        self.error_fn = error_fn
+        # Sentinel: empty tuple → use defaults on first stream.
+        # ``None`` → observe everything. Otherwise the user-supplied
+        # tuple is honored verbatim.
+        self._observe_types_arg = observe_message_types
+        self._resolved_observe_types: Optional[Tuple[type, ...]] = None
+
+    def _resolve_observe_types(self) -> Optional[Tuple[type, ...]]:
+        if self._observe_types_arg is None:
+            return None
+        if self._resolved_observe_types is None:
+            if self._observe_types_arg == ():
+                self._resolved_observe_types = _default_observe_types()
+            else:
+                self._resolved_observe_types = tuple(self._observe_types_arg)
+        return self._resolved_observe_types
+
+    async def run(
+        self,
+        prompt: Optional[Any] = None,
+        *,
+        options: Optional[Any] = None,
+        message_iterator: Optional[AsyncIterator[Any]] = None,
+    ) -> list:
+        """Drive a message stream to completion, returning the full
+        list of yielded messages.
+
+        Exactly one of ``prompt`` (with optional ``options``) or
+        ``message_iterator`` must be supplied:
+
+        - With ``prompt``, the adapter constructs the iterator via
+          ``claude_agent_sdk.query(prompt=..., options=...)``.
+        - With ``message_iterator``, the adapter drives whatever async
+          iterator is passed — e.g. ``ClaudeSDKClient.receive_messages()``.
+        """
+        out: list = []
+        async for message in self.stream(
+            prompt=prompt, options=options, message_iterator=message_iterator
+        ):
+            out.append(message)
+        return out
+
+    async def stream(
+        self,
+        prompt: Optional[Any] = None,
+        *,
+        options: Optional[Any] = None,
+        message_iterator: Optional[AsyncIterator[Any]] = None,
+    ) -> AsyncIterator[Any]:
+        """Yield each message from the underlying stream while driving
+        LoopGain. Stops iterating as soon as LoopGain reaches a
+        terminal state.
+        """
+        if (prompt is None) == (message_iterator is None):
+            raise ValueError(
+                "ClaudeAgentSDKAdapter.stream/run requires exactly one of "
+                "`prompt` or `message_iterator`."
+            )
+
+        if message_iterator is None:
+            from claude_agent_sdk import query
+
+            message_iterator = query(prompt=prompt, options=options)
+
+        observe_types = self._resolve_observe_types()
+
+        async for message in message_iterator:
+            yield message
+
+            if observe_types is not None and not isinstance(message, observe_types):
+                continue
+
+            magnitude = self.error_fn(message)
+            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():
+                # The SDK has no caller-facing cancel for a query()
+                # iterator; breaking out drops our subscription and
+                # the underlying transport tears down on garbage
+                # collection. ClaudeSDKClient users should call
+                # ``client.disconnect()`` after the stream returns.
+                break
+
+    def run_sync(
+        self,
+        prompt: Optional[Any] = None,
+        *,
+        options: Optional[Any] = None,
+    ) -> list:
+        """Synchronous wrapper around ``run`` for the ``prompt`` form.
+        Calls ``asyncio.run`` — do not call from inside a running event
+        loop. The bidirectional ``message_iterator`` form is async-only.
+        """
+        return asyncio.run(self.run(prompt=prompt, options=options))