Phase 3: langchain/langgraph integration

Author: rcholic

examples/lang-chain/README.md

@@ -0,0 +1,14 @@
+### LangChain / LangGraph examples (Python)
+
+These examples show how to use Sentience as a **tool layer** inside LangChain and LangGraph.
+
+Install:
+
+```bash
+pip install sentienceapi[langchain]
+```
+
+Examples:
+- `langchain_tools_demo.py`: build a Sentience tool pack for LangChain
+- `langgraph_self_correcting_graph.py`: observe → act → verify → branch (retry) template
+

examples/lang-chain/langchain_tools_demo.py

@@ -0,0 +1,39 @@
+"""
+Example: Build Sentience LangChain tools (async-only).
+
+Install:
+  pip install sentienceapi[langchain]
+
+Run:
+  python examples/lang-chain/langchain_tools_demo.py
+
+Notes:
+- This example focuses on creating the tools. Hook them into your agent of choice.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from sentience import AsyncSentienceBrowser
+from sentience.integrations.langchain import SentienceLangChainContext, build_sentience_langchain_tools
+
+
+async def main() -> None:
+    browser = AsyncSentienceBrowser(headless=False)
+    await browser.start()
+    await browser.goto("https://example.com")
+
+    ctx = SentienceLangChainContext(browser=browser)
+    tools = build_sentience_langchain_tools(ctx)
+
+    print("Registered tools:")
+    for t in tools:
+        print(f"- {t.name}")
+
+    await browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/lang-chain/langgraph_self_correcting_graph.py

@@ -0,0 +1,81 @@
+"""
+LangGraph reference example: Sentience observe → act → verify → branch (self-correcting).
+
+Install:
+  pip install sentienceapi[langchain]
+
+Run:
+  python examples/lang-chain/langgraph_self_correcting_graph.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from sentience import AsyncSentienceBrowser
+from sentience.integrations.langchain import SentienceLangChainContext, SentienceLangChainCore
+
+
+@dataclass
+class State:
+    url: str | None = None
+    last_action: str | None = None
+    attempts: int = 0
+    done: bool = False
+
+
+async def main() -> None:
+    from langgraph.graph import END, StateGraph
+
+    browser = AsyncSentienceBrowser(headless=False)
+    await browser.start()
+
+    core = SentienceLangChainCore(SentienceLangChainContext(browser=browser))
+
+    async def observe(state: State) -> State:
+        s = await core.snapshot_state()
+        state.url = s.url
+        return state
+
+    async def act(state: State) -> State:
+        # Replace with an LLM decision node. For demo we just navigate once.
+        if state.attempts == 0:
+            await core.navigate("https://example.com")
+            state.last_action = "navigate"
+        else:
+            state.last_action = "noop"
+        state.attempts += 1
+        return state
+
+    async def verify(state: State) -> State:
+        out = await core.verify_url_matches(r"example\.com")
+        state.done = bool(out.passed)
+        return state
+
+    def branch(state: State) -> str:
+        if state.done:
+            return "done"
+        if state.attempts >= 3:
+            return "done"
+        return "retry"
+
+    g = StateGraph(State)
+    g.add_node("observe", observe)
+    g.add_node("act", act)
+    g.add_node("verify", verify)
+    g.set_entry_point("observe")
+    g.add_edge("observe", "act")
+    g.add_edge("act", "verify")
+    g.add_conditional_edges("verify", branch, {"retry": "observe", "done": END})
+    app = g.compile()
+
+    final = await app.ainvoke(State())
+    print(final)
+
+    await browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/langgraph/sentience_self_correcting_graph.py

@@ -0,0 +1,89 @@
+"""
+LangGraph reference example: Sentience observe → act → verify → branch (self-correcting).
+
+Install:
+  pip install sentienceapi[langchain]
+
+Run:
+  python examples/langgraph/sentience_self_correcting_graph.py
+
+Notes:
+- This is a template demonstrating control flow; you can replace the "decide" node
+  with an LLM step (LangChain) that chooses actions based on snapshot_state/read_page.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Optional
+
+from sentience import AsyncSentienceBrowser
+from sentience.integrations.langchain import SentienceLangChainContext, SentienceLangChainCore
+
+
+@dataclass
+class State:
+    url: str | None = None
+    last_action: str | None = None
+    attempts: int = 0
+    done: bool = False
+
+
+async def main() -> None:
+    # Lazy import so the file can exist without langgraph installed
+    from langgraph.graph import END, StateGraph
+
+    browser = AsyncSentienceBrowser(headless=False)
+    await browser.start()
+
+    core = SentienceLangChainCore(SentienceLangChainContext(browser=browser))
+
+    async def observe(state: State) -> State:
+        s = await core.snapshot_state()
+        state.url = s.url
+        return state
+
+    async def act(state: State) -> State:
+        # Replace this with an LLM-driven decision. For demo purposes, we just navigate once.
+        if state.attempts == 0:
+            await core.navigate("https://example.com")
+            state.last_action = "navigate"
+        else:
+            state.last_action = "noop"
+        state.attempts += 1
+        return state
+
+    async def verify(state: State) -> State:
+        # Guard condition: URL should contain example.com
+        out = await core.verify_url_matches(r"example\.com")
+        state.done = bool(out.passed)
+        return state
+
+    def should_continue(state: State) -> str:
+        # Self-correcting loop: retry observe→act→verify up to 3 attempts
+        if state.done:
+            return "done"
+        if state.attempts >= 3:
+            return "done"
+        return "retry"
+
+    g = StateGraph(State)
+    g.add_node("observe", observe)
+    g.add_node("act", act)
+    g.add_node("verify", verify)
+    g.set_entry_point("observe")
+    g.add_edge("observe", "act")
+    g.add_edge("act", "verify")
+    g.add_conditional_edges("verify", should_continue, {"retry": "observe", "done": END})
+    app = g.compile()
+
+    final = await app.ainvoke(State())
+    print(final)
+
+    await browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

sentience/integrations/langchain/__init__.py

@@ -0,0 +1,13 @@
+"""
+LangChain / LangGraph integration helpers (optional).
+
+This package is designed so the base SDK can be imported without LangChain installed.
+All LangChain imports are done lazily inside tool-builder functions.
+"""
+
+from .context import SentienceLangChainContext
+from .core import SentienceLangChainCore
+from .tools import build_sentience_langchain_tools
+
+__all__ = ["SentienceLangChainContext", "SentienceLangChainCore", "build_sentience_langchain_tools"]
+

sentience/integrations/langchain/context.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sentience.browser import AsyncSentienceBrowser
+from sentience.tracing import Tracer
+
+
+@dataclass
+class SentienceLangChainContext:
+    """
+    Context for LangChain/LangGraph integrations.
+
+    We keep this small and explicit; it mirrors the PydanticAI deps object.
+    """
+
+    browser: AsyncSentienceBrowser
+    tracer: Tracer | None = None
+