agento11y-langgraph 0.10.0__py3-none-any.whl

agento11y_langgraph/__init__.py

@@ -0,0 +1,51 @@
+"""Public exports for Sigil LangGraph callback handlers."""
+
+from typing import Any
+
+from agento11y import Client
+
+from .handler import Agento11yAsyncLangGraphHandler, Agento11yLangGraphHandler
+
+
+def create_agento11y_langgraph_handler(
+    *,
+    client: Client,
+    async_handler: bool = False,
+    **handler_kwargs: Any,
+) -> Agento11yLangGraphHandler | Agento11yAsyncLangGraphHandler:
+    """Create a LangGraph Sigil callback handler for sync or async flows."""
+    if async_handler:
+        return Agento11yAsyncLangGraphHandler(client=client, **handler_kwargs)
+    return Agento11yLangGraphHandler(client=client, **handler_kwargs)
+
+
+def with_agento11y_langgraph_callbacks(
+    config: dict[str, Any] | None,
+    *,
+    client: Client,
+    async_handler: bool = False,
+    **handler_kwargs: Any,
+) -> dict[str, Any]:
+    """Append a Sigil callback handler to a LangGraph invocation config."""
+    merged = dict(config or {})
+    existing = merged.get("callbacks")
+    if isinstance(existing, list):
+        callbacks = list(existing)
+    elif existing is None:
+        callbacks = []
+    else:
+        callbacks = [existing]
+    if not any(isinstance(item, (Agento11yLangGraphHandler, Agento11yAsyncLangGraphHandler)) for item in callbacks):
+        callbacks.append(
+            create_agento11y_langgraph_handler(client=client, async_handler=async_handler, **handler_kwargs)
+        )
+    merged["callbacks"] = callbacks
+    return merged
+
+
+__all__ = [
+    "Agento11yLangGraphHandler",
+    "Agento11yAsyncLangGraphHandler",
+    "create_agento11y_langgraph_handler",
+    "with_agento11y_langgraph_callbacks",
+]

agento11y_langgraph/handler.py

@@ -0,0 +1,349 @@
+"""LangGraph callback handlers for Sigil generation recording."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from agento11y import Client
+from agento11y.framework_handler import Agento11yFrameworkHandlerBase, ProviderResolver
+
+try:
+    from langchain_core.callbacks import AsyncCallbackHandler, BaseCallbackHandler
+except ModuleNotFoundError:  # pragma: no cover - handled by package dependency in normal installs
+
+    class BaseCallbackHandler:  # type: ignore[no-redef]
+        """Fallback base class when langchain-core is unavailable."""
+
+    class AsyncCallbackHandler:  # type: ignore[no-redef]
+        """Fallback async base class when langchain-core is unavailable."""
+
+
+_framework_name = "langgraph"
+_framework_source = "handler"
+_framework_language = "python"
+_framework_instrumentation_name = "github.com/grafana/sigil/sdks/python-frameworks/langgraph"
+
+
+def _merge_callback_kwargs(
+    kwargs: dict[str, Any],
+    *,
+    tags: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    run_name: str | None = None,
+) -> dict[str, Any]:
+    callback_kwargs = dict(kwargs)
+    if tags is not None:
+        callback_kwargs["tags"] = tags
+    if metadata is not None:
+        callback_kwargs["metadata"] = metadata
+    if run_name is not None and run_name.strip() != "":
+        callback_kwargs["run_name"] = run_name
+    return callback_kwargs
+
+
+class _Agento11yLangGraphBase(Agento11yFrameworkHandlerBase):
+    def __init__(
+        self,
+        *,
+        client: Client,
+        agent_name: str = "",
+        agent_version: str = "",
+        provider_resolver: ProviderResolver = "auto",
+        provider: str = "",
+        capture_inputs: bool = True,
+        capture_outputs: bool = True,
+        capture_workflow_steps: bool = False,
+        conversation_title: str = "",
+        extra_tags: dict[str, str] | None = None,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            client=client,
+            framework_name=_framework_name,
+            framework_source=_framework_source,
+            framework_language=_framework_language,
+            framework_instrumentation_name=_framework_instrumentation_name,
+            agent_name=agent_name,
+            agent_version=agent_version,
+            provider_resolver=provider_resolver,
+            provider=provider,
+            capture_inputs=capture_inputs,
+            capture_outputs=capture_outputs,
+            capture_workflow_steps=capture_workflow_steps,
+            conversation_title=conversation_title,
+            extra_tags=extra_tags,
+            extra_metadata=extra_metadata,
+        )
+
+
+class Agento11yLangGraphHandler(_Agento11yLangGraphBase, BaseCallbackHandler):
+    """Sync LangGraph callback handler that records Sigil generations."""
+
+    def on_llm_start(
+        self,
+        serialized: dict[str, Any] | None,
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        invocation_params: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_llm_start(
+            serialized=serialized,
+            prompts=prompts,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            invocation_params=invocation_params,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any] | None,
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        invocation_params: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_chat_model_start(
+            serialized=serialized,
+            messages=messages,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            invocation_params=invocation_params,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    def on_llm_new_token(self, token: str, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_new_token(token=token, run_id=run_id)
+
+    def on_llm_end(self, response: Any, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_end(response=response, run_id=run_id)
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_error(error=error, run_id=run_id)
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any] | None,
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_tool_start(
+            serialized=serialized,
+            input_str=input_str,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_tool_end(output=output, run_id=run_id)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_tool_error(error=error, run_id=run_id)
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any] | None,
+        inputs: dict[str, Any] | None,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_type: str | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_chain_start(
+            serialized=serialized,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            run_type=run_type or "chain",
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+            inputs=inputs,
+        )
+
+    def on_chain_end(self, outputs: dict[str, Any] | None, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_chain_end(run_id=run_id, outputs=outputs)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_chain_error(error=error, run_id=run_id)
+
+    def on_retriever_start(
+        self,
+        serialized: dict[str, Any] | None,
+        _query: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_retriever_start(
+            serialized=serialized,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    def on_retriever_end(self, _documents: list[Any], *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_retriever_end(run_id=run_id)
+
+    def on_retriever_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_retriever_error(error=error, run_id=run_id)
+
+
+class Agento11yAsyncLangGraphHandler(_Agento11yLangGraphBase, AsyncCallbackHandler):
+    """Async LangGraph callback handler that records Sigil generations."""
+
+    async def on_llm_start(
+        self,
+        serialized: dict[str, Any] | None,
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        invocation_params: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_llm_start(
+            serialized=serialized,
+            prompts=prompts,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            invocation_params=invocation_params,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    async def on_chat_model_start(
+        self,
+        serialized: dict[str, Any] | None,
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        invocation_params: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_chat_model_start(
+            serialized=serialized,
+            messages=messages,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            invocation_params=invocation_params,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    async def on_llm_new_token(self, token: str, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_new_token(token=token, run_id=run_id)
+
+    async def on_llm_end(self, response: Any, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_end(response=response, run_id=run_id)
+
+    async def on_llm_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_llm_error(error=error, run_id=run_id)
+
+    async def on_tool_start(
+        self,
+        serialized: dict[str, Any] | None,
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_tool_start(
+            serialized=serialized,
+            input_str=input_str,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    async def on_tool_end(self, output: Any, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_tool_end(output=output, run_id=run_id)
+
+    async def on_tool_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_tool_error(error=error, run_id=run_id)
+
+    async def on_chain_start(
+        self,
+        serialized: dict[str, Any] | None,
+        inputs: dict[str, Any] | None,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_type: str | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_chain_start(
+            serialized=serialized,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            run_type=run_type or "chain",
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+            inputs=inputs,
+        )
+
+    async def on_chain_end(self, outputs: dict[str, Any] | None, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_chain_end(run_id=run_id, outputs=outputs)
+
+    async def on_chain_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_chain_error(error=error, run_id=run_id)
+
+    async def on_retriever_start(
+        self,
+        serialized: dict[str, Any] | None,
+        _query: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        run_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._on_retriever_start(
+            serialized=serialized,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            callback_kwargs=_merge_callback_kwargs(kwargs, tags=tags, metadata=metadata, run_name=run_name),
+        )
+
+    async def on_retriever_end(self, _documents: list[Any], *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_retriever_end(run_id=run_id)
+
+    async def on_retriever_error(self, error: BaseException, *, run_id: UUID, **_kwargs: Any) -> None:
+        self._on_retriever_error(error=error, run_id=run_id)

agento11y_langgraph-0.10.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agento11y-langgraph
+Version: 0.10.0
+Summary: LangGraph callback handlers for the Grafana Agent Observability Python SDK
+License: SPDX-License-Identifier: Apache-2.0
+        
+        See /LICENSE at repository root for full license text.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agento11y>=0.10.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langgraph>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Dynamic: license-file
+
+# Sigil Python Framework Module: LangGraph
+
+`agento11y-langgraph` provides callback handlers that map LangGraph lifecycle events into Sigil generation recorder lifecycles.
+
+## Installation
+
+```bash
+pip install agento11y agento11y-langgraph
+pip install langgraph langchain-openai
+```
+
+## Usage
+
+```python
+from agento11y import Client
+from agento11y_langgraph import with_agento11y_langgraph_callbacks
+
+client = Client()
+config = with_agento11y_langgraph_callbacks(None, client=client, provider_resolver="auto")
+```
+
+## End-to-end example (graph invoke + stream)
+
+```python
+from typing import TypedDict
+
+from langchain_core.runnables import RunnableConfig
+from langchain_openai import ChatOpenAI
+from langgraph.graph import END, StateGraph
+from agento11y import Client
+from agento11y_langgraph import with_agento11y_langgraph_callbacks
+
+
+class GraphState(TypedDict):
+    prompt: str
+    answer: str
+
+
+client = Client()
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+
+def run_model(state: GraphState, config: RunnableConfig) -> GraphState:
+    response = llm.invoke(
+        state["prompt"],
+        config=config,
+    )
+    return {"prompt": state["prompt"], "answer": str(response.content).strip()}
+
+
+workflow = StateGraph(GraphState)
+workflow.add_node("model", run_model)
+workflow.set_entry_point("model")
+workflow.add_edge("model", END)
+graph = workflow.compile()
+
+agento11y_config = with_agento11y_langgraph_callbacks(
+    None,
+    client=client,
+    provider_resolver="auto",
+    agent_name="langgraph-example",
+    agent_version="1.0.0",
+)
+
+# Non-stream graph invocation.
+out = graph.invoke(
+    {"prompt": "Explain SLO burn rate in one paragraph.", "answer": ""},
+    config=agento11y_config,
+)
+print(out["answer"])
+
+# Streamed graph events.
+for _event in graph.stream(
+    {"prompt": "List three practical alerting tips.", "answer": ""},
+    config=agento11y_config,
+):
+    pass
+
+client.shutdown()
+```
+
+## Workflow step capture
+
+Enable `capture_workflow_steps=True` to record each graph node as a Sigil workflow step.
+This enables the **Workflow** tab in the conversation detail view, showing node execution order,
+duration, input/output state, and which LLM generations ran inside each node. The **Dependencies**
+tab remains available for the generation-level DAG built from `parent_generation_ids`.
+
+Always set `conversation_title` to a short human-readable label — it appears as the conversation
+name in the Sigil UI. Without it, the title falls back to an opaque auto-generated ID.
+
+```python
+from agento11y import Client
+from agento11y_langgraph import Agento11yLangGraphHandler
+
+client = Client()
+handler = Agento11yLangGraphHandler(
+    client=client,
+    agent_name="my-pipeline",
+    conversation_title="My Pipeline Run",
+    capture_workflow_steps=True,
+)
+
+# Reuse the `graph` from the end-to-end example above. The node must pass its
+# received `config` into `llm.invoke(...)` so generations link to the workflow step.
+result = graph.invoke(
+    {"prompt": "Explain why my dashboard is slow.", "answer": ""},
+    config={"callbacks": [handler]},
+)
+client.shutdown()
+```
+
+The handler automatically:
+- Detects graph root and direct-child nodes
+- Creates a workflow step per node with `input_state`, `output_state`, and timestamps
+- Links LLM generation IDs to their parent step via `linked_generation_ids`
+- Tracks sequential `parent_step_ids` so the DAG edges are correct
+
+## Persistent thread example (LangGraph checkpointer)
+
+```python
+from langgraph.checkpoint.memory import MemorySaver
+
+checkpointer = MemorySaver()
+graph = workflow.compile(checkpointer=checkpointer)
+
+thread_config = {
+    **with_agento11y_langgraph_callbacks(None, client=client, provider_resolver="auto"),
+    "configurable": {"thread_id": "customer-42"},
+}
+
+graph.invoke({"prompt": "Remember that my timezone is UTC+1.", "answer": ""}, config=thread_config)
+graph.invoke({"prompt": "What timezone did I just give you?", "answer": ""}, config=thread_config)
+
+# Advanced usage: explicit handler wiring remains supported.
+_ = graph.invoke(
+    {"prompt": "manual handler wiring", "answer": ""},
+    config={"callbacks": [handler]},
+)
+```
+
+When `thread_id` is present, the handler records:
+
+- `conversation_id=<thread_id>`
+- `metadata["agento11y.framework.run_id"]=<run id>`
+- `metadata["agento11y.framework.thread_id"]=<thread id>`
+- generation span attributes `agento11y.framework.run_id` and `agento11y.framework.thread_id`
+
+## Behavior
+
+- Lifecycle mapping:
+  - `on_llm_start` / `on_chat_model_start` -> generation recorder
+  - `on_tool_start` / `on_tool_end` / `on_tool_error` -> `start_tool_execution`
+  - `on_chain_start` / `on_chain_end` / `on_chain_error` -> framework chain spans
+  - `on_retriever_start` / `on_retriever_end` / `on_retriever_error` -> framework retriever spans
+  - `on_llm_new_token` -> first-token timestamp for stream mode
+- Mode mapping: non-stream -> `SYNC`, stream -> `STREAM`.
+- Provider resolver parity:
+  - explicit provider metadata when available
+  - model-name inference (`gpt-`/`o1`/`o3`/`o4` -> `openai`, `claude-` -> `anthropic`, `gemini-` -> `gemini`)
+  - fallback -> `custom`
+- Framework tags/metadata are always set:
+  - `agento11y.framework.name=langgraph`
+  - `agento11y.framework.source=handler`
+  - `agento11y.framework.language=python`
+  - `metadata["agento11y.framework.run_id"]=<run id>`
+  - `metadata["agento11y.framework.thread_id"]=<thread id>` (when present in callback metadata/config)
+  - `metadata["agento11y.framework.parent_run_id"]` (when available)
+  - `metadata["agento11y.framework.component_name"]` (serialized component identity)
+  - `metadata["agento11y.framework.run_type"]` (`llm`, `chat`, `tool`, `chain`, `retriever`)
+  - `metadata["agento11y.framework.tags"]` (normalized callback tags)
+  - `metadata["agento11y.framework.retry_attempt"]` (when available)
+  - `metadata["agento11y.framework.langgraph.node"]` (when callback context exposes node identity)
+  - generation span attributes mirror low-cardinality framework metadata keys
+
+Call `client.shutdown()` during teardown to flush buffered telemetry.

agento11y_langgraph-0.10.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+agento11y_langgraph/__init__.py,sha256=pF2bmP71RisDZiFZ01gC7EDiqcrSYMZocrUR1ka-d9s,1616
+agento11y_langgraph/handler.py,sha256=uDaGg2kPbKZBMfSeeZh_QeXjNzx2sfontjOYXlZ1Xj0,12607
+agento11y_langgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agento11y_langgraph-0.10.0.dist-info/licenses/LICENSE,sha256=L8b58whU_6MH2fW8ptr80ew_FRBkaPhSi82_uYAOglI,92
+agento11y_langgraph-0.10.0.dist-info/METADATA,sha256=eotS5ybfAT4yPGnWpf1lU87YvdgDLDGvcgWh7Vur8Yc,6623
+agento11y_langgraph-0.10.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agento11y_langgraph-0.10.0.dist-info/top_level.txt,sha256=oIseh5WhMiqWd5zCXUTjnmBStExewwMQrtFbPsMfM6o,20
+agento11y_langgraph-0.10.0.dist-info/RECORD,,

agento11y_langgraph-0.10.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agento11y_langgraph-0.10.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+SPDX-License-Identifier: Apache-2.0
+
+See /LICENSE at repository root for full license text.

agento11y_langgraph-0.10.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agento11y_langgraph