agento11y-langchain 0.10.0__tar.gz

agento11y_langchain-0.10.0/LICENSE

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

agento11y_langchain-0.10.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: agento11y-langchain
+Version: 0.10.0
+Summary: LangChain 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
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Dynamic: license-file
+
+# Sigil Python Framework Module: LangChain
+
+`agento11y-langchain` provides callback handlers that map LangChain lifecycle events into Sigil generation recorder lifecycles.
+
+## Installation
+
+```bash
+pip install agento11y agento11y-langchain
+pip install langchain-openai
+```
+
+## Usage
+
+```python
+from agento11y import Client
+from agento11y_langchain import with_agento11y_langchain_callbacks
+
+client = Client()
+config = with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto")
+```
+
+## End-to-end example (invoke + stream)
+
+```python
+from langchain_openai import ChatOpenAI
+from agento11y import Client
+from agento11y_langchain import Agento11yLangChainHandler, with_agento11y_langchain_callbacks
+
+client = Client()
+handler = Agento11yLangChainHandler(
+    client=client,
+    provider_resolver="auto",
+    agent_name="langchain-example",
+    agent_version="1.0.0",
+)
+
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+# Non-stream call -> SYNC generation mode.
+result = llm.invoke(
+    "Summarize why retry budgets matter.",
+    config=with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto"),
+)
+print(result.content)
+
+# Stream call -> STREAM generation mode + TTFT tracking.
+for chunk in llm.stream(
+    "Give me three short reliability tips.",
+    config=with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto"),
+):
+    if chunk.content:
+        print(chunk.content, end="", flush=True)
+print()
+
+# Advanced usage: explicit handler wiring remains supported.
+_ = llm.invoke("manual handler wiring", config={"callbacks": [handler]})
+
+client.shutdown()
+```
+
+## 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=langchain`
+  - `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)
+  - generation span attributes mirror low-cardinality framework metadata keys
+
+Call `client.shutdown()` during teardown to flush buffered telemetry.

agento11y_langchain-0.10.0/README.md

@@ -0,0 +1,87 @@
+# Sigil Python Framework Module: LangChain
+
+`agento11y-langchain` provides callback handlers that map LangChain lifecycle events into Sigil generation recorder lifecycles.
+
+## Installation
+
+```bash
+pip install agento11y agento11y-langchain
+pip install langchain-openai
+```
+
+## Usage
+
+```python
+from agento11y import Client
+from agento11y_langchain import with_agento11y_langchain_callbacks
+
+client = Client()
+config = with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto")
+```
+
+## End-to-end example (invoke + stream)
+
+```python
+from langchain_openai import ChatOpenAI
+from agento11y import Client
+from agento11y_langchain import Agento11yLangChainHandler, with_agento11y_langchain_callbacks
+
+client = Client()
+handler = Agento11yLangChainHandler(
+    client=client,
+    provider_resolver="auto",
+    agent_name="langchain-example",
+    agent_version="1.0.0",
+)
+
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+# Non-stream call -> SYNC generation mode.
+result = llm.invoke(
+    "Summarize why retry budgets matter.",
+    config=with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto"),
+)
+print(result.content)
+
+# Stream call -> STREAM generation mode + TTFT tracking.
+for chunk in llm.stream(
+    "Give me three short reliability tips.",
+    config=with_agento11y_langchain_callbacks(None, client=client, provider_resolver="auto"),
+):
+    if chunk.content:
+        print(chunk.content, end="", flush=True)
+print()
+
+# Advanced usage: explicit handler wiring remains supported.
+_ = llm.invoke("manual handler wiring", config={"callbacks": [handler]})
+
+client.shutdown()
+```
+
+## 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=langchain`
+  - `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)
+  - generation span attributes mirror low-cardinality framework metadata keys
+
+Call `client.shutdown()` during teardown to flush buffered telemetry.

agento11y_langchain-0.10.0/agento11y_langchain/__init__.py

@@ -0,0 +1,51 @@
+"""Public exports for Sigil LangChain callback handlers."""
+
+from typing import Any
+
+from agento11y import Client
+
+from .handler import Agento11yAsyncLangChainHandler, Agento11yLangChainHandler
+
+
+def create_agento11y_langchain_handler(
+    *,
+    client: Client,
+    async_handler: bool = False,
+    **handler_kwargs: Any,
+) -> Agento11yLangChainHandler | Agento11yAsyncLangChainHandler:
+    """Create a LangChain Sigil callback handler for sync or async flows."""
+    if async_handler:
+        return Agento11yAsyncLangChainHandler(client=client, **handler_kwargs)
+    return Agento11yLangChainHandler(client=client, **handler_kwargs)
+
+
+def with_agento11y_langchain_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 LangChain runnable 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, (Agento11yLangChainHandler, Agento11yAsyncLangChainHandler)) for item in callbacks):
+        callbacks.append(
+            create_agento11y_langchain_handler(client=client, async_handler=async_handler, **handler_kwargs)
+        )
+    merged["callbacks"] = callbacks
+    return merged
+
+
+__all__ = [
+    "Agento11yLangChainHandler",
+    "Agento11yAsyncLangChainHandler",
+    "create_agento11y_langchain_handler",
+    "with_agento11y_langchain_callbacks",
+]

agento11y_langchain-0.10.0/agento11y_langchain/handler.py

@@ -0,0 +1,349 @@
+"""LangChain 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 = "langchain"
+_framework_source = "handler"
+_framework_language = "python"
+_framework_instrumentation_name = "github.com/grafana/sigil/sdks/python-frameworks/langchain"
+
+
+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 _Agento11yLangChainBase(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 Agento11yLangChainHandler(_Agento11yLangChainBase, BaseCallbackHandler):
+    """Sync LangChain 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 Agento11yAsyncLangChainHandler(_Agento11yLangChainBase, AsyncCallbackHandler):
+    """Async LangChain 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)