aerograph-langchain 0.2.0__tar.gz

aerograph_langchain-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+node_modules/
+dist/
+build/
+.vite/
+coverage/
+*.log
+.env*
+.specify/
+apps/collector/data/
+.DS_Store
+.github/agents
+.github/prompts
+.github/copilot-instructions.md
+Thumbs.db
+.agents/
+apps/collector/data/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+Thumbs.db
+*.tmp
+*.swp
+.vscode/
+.idea/
+specs/
+docs/architecture
+.vscode/
+AGENTS.md
+uv.lock

aerograph_langchain-0.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: aerograph-langchain
+Version: 0.2.0
+Summary: LangChain callback adapter for AeroGraph — automatically record LangChain traces.
+Project-URL: Homepage, https://github.com/SGcpu/AeroGraph
+Project-URL: Repository, https://github.com/SGcpu/AeroGraph
+Project-URL: Issues, https://github.com/SGcpu/AeroGraph/issues
+License: Apache-2.0
+Keywords: aerograph,agent,ai,langchain,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: aerograph-sdk>=0.2.0
+Requires-Dist: langchain-core>=0.2.0
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
+Requires-Dist: langchain>=0.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# aerograph-langchain
+
+LangChain callback adapter for [AeroGraph](https://github.com/SGcpu/AeroGraph).
+
+Automatically records LangChain chain, LLM, tool, and retriever events as AeroGraph trace events.
+
+## Installation
+
+When published, you can install the adapter via pip:
+
+```bash
+pip install aerograph-langchain
+```
+
+For local testing or development, install the packages in editable mode from the repository root:
+
+```bash
+# Install the core SDK first
+pip install -e python/aerograph-sdk
+
+# Install the LangChain adapter
+pip install -e python/aerograph-langchain
+```
+
+## Usage
+
+Integrating `AeroGraphCallbackHandler` into your existing LangChain codebase is simple. Setup a `FlightRecorder`, initialize the handler, and pass it to your chain or model invocations.
+
+### Basic Example
+
+```python
+import asyncio
+from langchain_core.messages import HumanMessage
+from langchain_openai import ChatOpenAI
+from aerograph_sdk.recorder import FlightRecorder
+from aerograph_langchain.handler import AeroGraphCallbackHandler
+
+async def main():
+    # 1. Initialize the FlightRecorder pointing to your collector
+    recorder = FlightRecorder(
+        endpoint="http://localhost:4317",
+        actor={"id": "my-agent", "name": "TravelPlanner"}
+    )
+
+    # 2. Initialize the AeroGraph callback handler
+    handler = AeroGraphCallbackHandler(recorder)
+
+    # 3. Create your LangChain chat model
+    model = ChatOpenAI(model="gpt-4o")
+
+    # 4. Invoke the model and pass the handler in callbacks
+    response = await model.ainvoke(
+        [HumanMessage(content="What are 3 fun things to do in San Francisco?")],
+        config={"callbacks": [handler]}
+    )
+    print(response.content)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Advanced Usage with Chains and RAG
+
+You can attach the callback handler at the chain execution level. LangChain automatically propagates the callbacks down to all sub-chains, LLMs, retrievers, and tool invocations.
+
+```python
+# Pass the handler to the chain invoke call
+result = rag_chain.invoke(
+    "How do I configure the server?",
+    config={"callbacks": [handler]}
+)
+```
+
+## Features and Event Mapping
+
+The callback adapter automatically intercepts LangChain execution signals and translates them to canonical AeroGraph `TraceEvent` types:
+
+- **LLM/Chat Starts** (`on_llm_start`, `on_chat_model_start`) $\rightarrow$ `PromptEvent`
+- **LLM Ends** (`on_llm_end`) $\rightarrow$ `ResponseEvent` (includes streaming telemetry completion metrics: TTFT and tokens/sec when tokens are streamed)
+- **Tool Starts** (`on_tool_start`) $\rightarrow$ `ToolCallEvent`
+- **Tool Ends** (`on_tool_end`) $\rightarrow$ `ToolResultEvent`
+- **Retriever Runs** (`on_retriever_start`, `on_retriever_end`) $\rightarrow$ `RetrieverEvent` (captures source documents, queries, and metadata)
+- **Errors** (`on_llm_error`, `on_tool_error`, `on_chain_error`) $\rightarrow$ `ErrorEvent`
+- **Custom Events** (`on_custom_event`) $\rightarrow$ `StateSnapshotEvent` and `CheckpointEvent` for LangGraph nodes
+
+## License
+
+Apache-2.0

aerograph_langchain-0.2.0/README.md

@@ -0,0 +1,88 @@
+# aerograph-langchain
+
+LangChain callback adapter for [AeroGraph](https://github.com/SGcpu/AeroGraph).
+
+Automatically records LangChain chain, LLM, tool, and retriever events as AeroGraph trace events.
+
+## Installation
+
+When published, you can install the adapter via pip:
+
+```bash
+pip install aerograph-langchain
+```
+
+For local testing or development, install the packages in editable mode from the repository root:
+
+```bash
+# Install the core SDK first
+pip install -e python/aerograph-sdk
+
+# Install the LangChain adapter
+pip install -e python/aerograph-langchain
+```
+
+## Usage
+
+Integrating `AeroGraphCallbackHandler` into your existing LangChain codebase is simple. Setup a `FlightRecorder`, initialize the handler, and pass it to your chain or model invocations.
+
+### Basic Example
+
+```python
+import asyncio
+from langchain_core.messages import HumanMessage
+from langchain_openai import ChatOpenAI
+from aerograph_sdk.recorder import FlightRecorder
+from aerograph_langchain.handler import AeroGraphCallbackHandler
+
+async def main():
+    # 1. Initialize the FlightRecorder pointing to your collector
+    recorder = FlightRecorder(
+        endpoint="http://localhost:4317",
+        actor={"id": "my-agent", "name": "TravelPlanner"}
+    )
+
+    # 2. Initialize the AeroGraph callback handler
+    handler = AeroGraphCallbackHandler(recorder)
+
+    # 3. Create your LangChain chat model
+    model = ChatOpenAI(model="gpt-4o")
+
+    # 4. Invoke the model and pass the handler in callbacks
+    response = await model.ainvoke(
+        [HumanMessage(content="What are 3 fun things to do in San Francisco?")],
+        config={"callbacks": [handler]}
+    )
+    print(response.content)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Advanced Usage with Chains and RAG
+
+You can attach the callback handler at the chain execution level. LangChain automatically propagates the callbacks down to all sub-chains, LLMs, retrievers, and tool invocations.
+
+```python
+# Pass the handler to the chain invoke call
+result = rag_chain.invoke(
+    "How do I configure the server?",
+    config={"callbacks": [handler]}
+)
+```
+
+## Features and Event Mapping
+
+The callback adapter automatically intercepts LangChain execution signals and translates them to canonical AeroGraph `TraceEvent` types:
+
+- **LLM/Chat Starts** (`on_llm_start`, `on_chat_model_start`) $\rightarrow$ `PromptEvent`
+- **LLM Ends** (`on_llm_end`) $\rightarrow$ `ResponseEvent` (includes streaming telemetry completion metrics: TTFT and tokens/sec when tokens are streamed)
+- **Tool Starts** (`on_tool_start`) $\rightarrow$ `ToolCallEvent`
+- **Tool Ends** (`on_tool_end`) $\rightarrow$ `ToolResultEvent`
+- **Retriever Runs** (`on_retriever_start`, `on_retriever_end`) $\rightarrow$ `RetrieverEvent` (captures source documents, queries, and metadata)
+- **Errors** (`on_llm_error`, `on_tool_error`, `on_chain_error`) $\rightarrow$ `ErrorEvent`
+- **Custom Events** (`on_custom_event`) $\rightarrow$ `StateSnapshotEvent` and `CheckpointEvent` for LangGraph nodes
+
+## License
+
+Apache-2.0

aerograph_langchain-0.2.0/examples/langchain_demo.py

@@ -0,0 +1,53 @@
+import asyncio
+from langchain_core.messages import HumanMessage
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.outputs import ChatGeneration, ChatResult
+
+from aerograph_sdk.recorder import FlightRecorder
+from aerograph_langchain.handler import AeroGraphCallbackHandler
+
+
+class MockChatModel(BaseChatModel):
+    """A mock chat model for demonstration without an API key."""
+
+    @property
+    def _llm_type(self) -> str:
+        return "mock-chat"
+
+    def _generate(self, messages, stop=None, run_manager=None, **kwargs):
+        text = "This is a mock response to demonstrate AeroGraph tracing."
+        message = ChatGeneration(text=text, message={"content": text, "type": "ai"})
+        return ChatResult(generations=[message])
+
+    async def _agenerate(self, messages, stop=None, run_manager=None, **kwargs):
+        return self._generate(messages, stop, run_manager, **kwargs)
+
+
+async def main():
+    # 1. Initialize the flight recorder
+    # By default, it connects to http://localhost:4000
+    recorder = FlightRecorder(api_url="http://localhost:4000")
+
+    # 2. Create the AeroGraph LangChain callback handler
+    aerograph_handler = AeroGraphCallbackHandler(recorder)
+
+    # 3. Create a model (mocked here, but typically ChatOpenAI etc)
+    model = MockChatModel()
+
+    print(f"Starting trace: {aerograph_handler.trace_id}")
+
+    # 4. Invoke with the callback
+    messages = [HumanMessage(content="Tell me about AeroGraph observability.")]
+
+    print("Invoking model...")
+    response = await model.ainvoke(messages, config={"callbacks": [aerograph_handler]})
+
+    print("Response received:", response)
+
+    # Wait a moment for background events to flush
+    await asyncio.sleep(0.5)
+    print("Done. Check the AeroGraph UI to view the trace.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aerograph_langchain-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aerograph-langchain"
+version = "0.2.0"
+description = "LangChain callback adapter for AeroGraph — automatically record LangChain traces."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+keywords = ["ai", "agent", "tracing", "langchain", "aerograph"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "aerograph-sdk>=0.2.0",
+  "langchain-core>=0.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "langchain>=0.2.0",
+  "langchain-core>=0.2.0",
+]
+langgraph = [
+  "langgraph>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SGcpu/AeroGraph"
+Repository = "https://github.com/SGcpu/AeroGraph"
+Issues = "https://github.com/SGcpu/AeroGraph/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aerograph_langchain"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "integration: marks tests as integration tests (requires external services)",
+]
+
+[tool.uv.sources]
+aerograph-sdk = { path = "../aerograph-sdk", editable = true }

aerograph_langchain-0.2.0/src/aerograph_langchain/__init__.py

@@ -0,0 +1,5 @@
+"""
+LangChain callback adapter for AeroGraph.
+"""
+
+__version__ = "0.2.0"

aerograph_langchain-0.2.0/src/aerograph_langchain/handler.py

@@ -0,0 +1,252 @@
+import uuid
+from typing import Any, Dict, List, Optional
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.outputs import LLMResult
+from langchain_core.messages import BaseMessage
+from langchain_core.documents import Document
+
+from aerograph_sdk.recorder import FlightRecorder
+from aerograph_sdk.ids import new_trace_id
+
+from .mapping import map_llm_start, map_llm_end, map_tool_start, map_tool_end, map_error
+from .streaming import StreamingTracker
+from .retriever import RetrieverTracker
+from .langgraph import map_state_snapshot, map_checkpoint
+
+
+class AeroGraphCallbackHandler(BaseCallbackHandler):
+    """Callback Handler that records LangChain runs to AeroGraph."""
+
+    def __init__(
+        self, recorder: FlightRecorder, trace_id: Optional[str] = None
+    ) -> None:
+        super().__init__()
+        self.recorder = recorder
+        self.trace_id = trace_id or new_trace_id()
+        self.streaming_tracker = StreamingTracker()
+        self.retriever_tracker = RetrieverTracker()
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_llm_start(
+            serialized=serialized,
+            prompts=prompts,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            trace_id=self.trace_id,
+        )
+        self.recorder.emit(event)
+        self.streaming_tracker.on_llm_start(run_id)
+
+    def on_chat_model_start(
+        self,
+        serialized: Dict[str, Any],
+        messages: List[List[BaseMessage]],
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_llm_start(
+            serialized=serialized,
+            messages=messages,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            trace_id=self.trace_id,
+        )
+        self.recorder.emit(event)
+        self.streaming_tracker.on_llm_start(run_id)
+
+    def on_llm_new_token(
+        self,
+        token: str,
+        *,
+        chunk: Optional[Any] = None,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        self.streaming_tracker.on_llm_new_token(run_id)
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_llm_end(
+            serialized={
+                "name": "LLM"
+            },  # Best effort, LangChain doesn't pass serialized to end
+            response=response,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            trace_id=self.trace_id,
+        )
+        telemetry = self.streaming_tracker.on_llm_end(run_id)
+        if telemetry:
+            # We recreate the payload with telemetry
+            event.payload.streamingTelemetry = telemetry
+        self.recorder.emit(event)
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_tool_start(
+            serialized=serialized,
+            input_str=input_str,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            trace_id=self.trace_id,
+            inputs=inputs,
+        )
+        self.recorder.emit(event)
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_tool_end(
+            serialized={"name": "Tool"},  # Best effort
+            output=output,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            trace_id=self.trace_id,
+        )
+        self.recorder.emit(event)
+
+    def on_retriever_start(
+        self,
+        serialized: Dict[str, Any],
+        query: str,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        self.retriever_tracker.on_retriever_start(run_id, query, serialized)
+
+    def on_retriever_end(
+        self,
+        documents: List[Document],
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = self.retriever_tracker.on_retriever_end(
+            run_id=run_id,
+            documents=documents,
+            trace_id=self.trace_id,
+            parent_run_id=parent_run_id,
+        )
+        if event:
+            self.recorder.emit(event)
+
+    def on_custom_event(
+        self,
+        name: str,
+        data: Any,
+        *,
+        run_id: uuid.UUID,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Handle custom events, particularly LangGraph state emissions if mapped here."""
+        if name == "langgraph_state_snapshot":
+            event = map_state_snapshot(
+                run_id=run_id,
+                trace_id=self.trace_id,
+                node_name=data.get("node_name", "unknown"),
+                state_hash=data.get("state_hash", ""),
+                state_diff=data.get("state_diff", {}),
+                full_state=data.get("full_state", {}),
+                removed_keys=data.get("removed_keys", []),
+            )
+            self.recorder.emit(event)
+        elif name == "langgraph_checkpoint":
+            event = map_checkpoint(
+                run_id=run_id,
+                trace_id=self.trace_id,
+                checkpoint_id=data.get("checkpoint_id", ""),
+                reason=data.get("reason", ""),
+                state=data.get("state", {}),
+            )
+            self.recorder.emit(event)
+
+    def on_llm_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_error(
+            error=error,
+            run_id=run_id,
+            trace_id=self.trace_id,
+            parent_run_id=parent_run_id
+        )
+        self.recorder.emit(event)
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_error(
+            error=error,
+            run_id=run_id,
+            trace_id=self.trace_id,
+            parent_run_id=parent_run_id
+        )
+        self.recorder.emit(event)
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: uuid.UUID,
+        parent_run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        event = map_error(
+            error=error,
+            run_id=run_id,
+            trace_id=self.trace_id,
+            parent_run_id=parent_run_id
+        )
+        self.recorder.emit(event)

aerograph_langchain-0.2.0/src/aerograph_langchain/langgraph.py

@@ -0,0 +1,56 @@
+import uuid
+from typing import Any, Dict, List, Optional
+
+from aerograph_sdk.events import build_state_snapshot_event, build_checkpoint_event
+from aerograph_sdk.contracts.generated import StateSnapshotEvent, CheckpointEvent
+from aerograph_langchain.span_ids import derive_span_id
+
+
+def map_state_snapshot(
+    run_id: uuid.UUID,
+    trace_id: str,
+    node_name: str,
+    state_hash: str,
+    state_diff: Dict[str, Any],
+    full_state: Dict[str, Any],
+    removed_keys: Optional[List[str]] = None,
+    parent_run_id: Optional[uuid.UUID] = None,
+) -> StateSnapshotEvent:
+    span_id = derive_span_id(run_id)
+    parent_span_id = derive_span_id(parent_run_id) if parent_run_id else None
+
+    return build_state_snapshot_event(
+        trace_id=trace_id,
+        span_id=span_id,
+        parent_span_id=parent_span_id,
+        actor_id="langgraph",
+        actor_name="LangGraph",
+        node_name=node_name,
+        state_hash=state_hash,
+        state_diff=state_diff,
+        full_state=full_state,
+        removed_keys=removed_keys or [],
+    )
+
+
+def map_checkpoint(
+    run_id: uuid.UUID,
+    trace_id: str,
+    checkpoint_id: str,
+    reason: str,
+    state: Dict[str, Any],
+    parent_run_id: Optional[uuid.UUID] = None,
+) -> CheckpointEvent:
+    span_id = derive_span_id(run_id)
+    parent_span_id = derive_span_id(parent_run_id) if parent_run_id else None
+
+    return build_checkpoint_event(
+        trace_id=trace_id,
+        span_id=span_id,
+        parent_span_id=parent_span_id,
+        actor_id="langgraph",
+        actor_name="LangGraph",
+        checkpoint_id=checkpoint_id,
+        reason=reason,
+        state=state,
+    )