memtrace-ai 0.2.0__tar.gz

memtrace_ai-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: memtrace-ai
+Version: 0.2.0
+Summary: OpenTelemetry-based tracing and observability SDK for AI agents
+Author: MemTrace Authors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/martia-es/memtrace
+Project-URL: Documentation, https://github.com/martia-es/memtrace/tree/main/docs-site
+Project-URL: Changelog, https://github.com/martia-es/memtrace/blob/main/sdk/python/CHANGELOG.md
+Keywords: observability,tracing,opentelemetry,llm,ai-agents,langchain,pydantic-ai,openai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+Provides-Extra: grpc
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "grpc"
+Provides-Extra: http
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Requires-Dist: langchain>=1.0.0; python_version >= "3.10" and extra == "langchain"
+Requires-Dist: opentelemetry-instrumentation-langchain<1,>=0.45.0; extra == "langchain"
+Requires-Dist: wrapt<2; python_version < "3.10" and extra == "langchain"
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=1.0.0; extra == "pydantic-ai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.2.0; extra == "openai-agents"
+Provides-Extra: pii
+Requires-Dist: presidio-analyzer>=2.2.35; extra == "pii"
+Requires-Dist: presidio-anonymizer>=2.2.35; extra == "pii"
+Requires-Dist: spacy>=3.7; extra == "pii"
+Provides-Extra: security
+Requires-Dist: detect-secrets>=1.5; extra == "security"
+Requires-Dist: presidio-analyzer>=2.2.35; extra == "security"
+Provides-Extra: eval
+Requires-Dist: httpx>=0.27; extra == "eval"
+Requires-Dist: anthropic>=0.30; extra == "eval"
+Provides-Extra: dev
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: langchain-core>=0.1.0; extra == "dev"
+Requires-Dist: langchain>=1.0.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: opentelemetry-instrumentation-langchain<1,>=0.45.0; extra == "dev"
+Requires-Dist: wrapt<2; python_version < "3.10" and extra == "dev"
+Requires-Dist: pydantic-ai-slim>=1.0.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: openai-agents>=0.2.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: anthropic>=0.30; extra == "dev"
+Requires-Dist: detect-secrets>=1.5; extra == "dev"
+Requires-Dist: presidio-analyzer>=2.2.35; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# memtrace-ai (Python SDK)
+
+Instruments AI agents and exports traces over OTLP (OpenTelemetry GenAI conventions). It does not know the storage: it only talks to the OTel Collector.
+
+> The package is named `memtrace-ai` (the Python import is `memtrace`). It is **not on PyPI yet**: install it from this repository.
+
+```bash
+pip install -e sdk/python          # from the repository root; PyPI publication is pending
+# extras (pip install -e "sdk/python[eval]"): grpc (OTLP/gRPC), langchain, eval, pydantic-ai, pii, dev
+```
+
+```python
+from memtrace import init_tracer, trace_step, trace_llm_call, shutdown
+
+init_tracer(service_name="my-agent")   # or MEMTRACE_* environment variables
+
+@trace_step(name="search", step_type="tool")
+def search(q: str) -> str: ...
+
+# LangChain / LangGraph - Option 1: manual callback handler
+from memtrace.langchain import MemTraceCallbackHandler
+chain.invoke(x, config={"callbacks": [MemTraceCallbackHandler()]})
+
+# LangChain / LangGraph - Option 2: automatic (pip install 'memtrace-ai[langchain]')
+# from memtrace.langchain import enable_langchain_instrumentation
+# enable_langchain_instrumentation()   # once, after init_tracer(); do not combine with option 1
+
+# Pydantic AI - automatic (pip install 'memtrace-ai[pydantic-ai]')
+# from memtrace.pydantic_ai import enable_pydantic_ai_instrumentation
+# enable_pydantic_ai_instrumentation()
+
+shutdown()  # optional: the OTel SDK also flushes at exit; use flush() in short scripts / serverless
+```
+
+**Error policy**: the tracing calls never raise into your code. The only exceptions are the `enable_*_instrumentation()` functions, which raise `ImportError` if their extra is not installed.
+
+**Conversations**: wrap each turn with `with memtrace.session("conversation-id"):` (or pass `thread_id` / `session_id` / `conversation_id` in LangChain's `metadata`) and the dashboard groups the traces into one conversation. The id must be stable across turns, unique per conversation and free of personal data (it shows up in URLs). Without it, every turn is a standalone trace. `session()` also applies to spans emitted by auto-instrumented libraries.
+
+Spans created inside a `@trace_step` (or inside `with memtrace.session("id")`) hang from it, including those of the LangChain handler and of auto-instrumented libraries.
+
+`trace_step`, `trace_step_context` and `trace_llm_call` accept `service=` (the value returned by `init_tracer`) to use an explicit tracer instead of the global one.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `MEMTRACE_ENABLED` | `true` | `false` disables everything (no-op) |
+| `MEMTRACE_SERVICE_NAME` | `default-agent` | `service.name` |
+| `MEMTRACE_SERVICE_VERSION`, `MEMTRACE_ENVIRONMENT` | - | Resource attributes |
+| `MEMTRACE_OTLP_ENDPOINT` | `http://localhost:4318` (http) / `:4317` (grpc) | any OTLP endpoint |
+| `MEMTRACE_OTLP_PROTOCOL` | `http/protobuf` | or `grpc` (extra `grpc`) |
+| `MEMTRACE_OTLP_HEADERS` | - | `k1=v1,k2=v2` |
+| `MEMTRACE_CAPTURE_CONTENT` | `false` | store prompts/completions/arguments (ADR-004); also gates the auto-instrumentations |
+| `MEMTRACE_MAX_CONTENT_LENGTH` | `16384` | truncation of captured content |
+| `MEMTRACE_REDACT_KEYS` | - | extra key names to mask, on top of the built-in list (ADR-021) |
+| `MEMTRACE_SPAN_TTL_SECONDS` | `3600` | closes orphaned spans |
+| `MEMTRACE_MAX_ACTIVE_RUNS` | `10000` | cap on in-flight spans |
+| `MEMTRACE_EXPORT_TIMEOUT_MS`, `MEMTRACE_BATCH_MAX_QUEUE_SIZE`, `MEMTRACE_BATCH_SCHEDULE_DELAY_MS`, `MEMTRACE_BATCH_MAX_EXPORT_SIZE` | 5000 / 2048 / 5000 / 512 | `BatchSpanProcessor` |
+
+**Redaction**: secrets are masked in every exported span, by key name (`api_key`, `password`, …) and by shape (`sk-…`, JWTs, `Bearer …`, URL credentials). Personal data (emails, names, IDs) is anonymized only if you opt in with the `pii` extra: `init_tracer(redact=presidio_redactor(language="es"))` (`from memtrace.pii import presidio_redactor`; also `python -m spacy download <model>`), or with your own `init_tracer(redact=fn)`.
+
+Self-signed TLS: `OTEL_EXPORTER_OTLP_CERTIFICATE` (standard OTel) with an `https://` endpoint.
+
+## Architecture
+
+Hexagonal (ADR-008): `domain` (pure) → `application` (`SpanPort` port + `TracingService`) ← `adapters/inbound` (decorators, LangChain, Pydantic AI) and `adapters/outbound` (OpenTelemetry, no-op). `dependency_container.py` is the composition root. The dependency rule is checked by `tests/test_architecture.py`. Auto-instrumentors receive MemTrace's tracer provider explicitly, never a global one, and every span passes through a redacting exporter before it leaves the process (ADR-021).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check memtrace tests && mypy memtrace && pytest
+```

memtrace_ai-0.2.0/README.md

@@ -0,0 +1,73 @@
+# memtrace-ai (Python SDK)
+
+Instruments AI agents and exports traces over OTLP (OpenTelemetry GenAI conventions). It does not know the storage: it only talks to the OTel Collector.
+
+> The package is named `memtrace-ai` (the Python import is `memtrace`). It is **not on PyPI yet**: install it from this repository.
+
+```bash
+pip install -e sdk/python          # from the repository root; PyPI publication is pending
+# extras (pip install -e "sdk/python[eval]"): grpc (OTLP/gRPC), langchain, eval, pydantic-ai, pii, dev
+```
+
+```python
+from memtrace import init_tracer, trace_step, trace_llm_call, shutdown
+
+init_tracer(service_name="my-agent")   # or MEMTRACE_* environment variables
+
+@trace_step(name="search", step_type="tool")
+def search(q: str) -> str: ...
+
+# LangChain / LangGraph - Option 1: manual callback handler
+from memtrace.langchain import MemTraceCallbackHandler
+chain.invoke(x, config={"callbacks": [MemTraceCallbackHandler()]})
+
+# LangChain / LangGraph - Option 2: automatic (pip install 'memtrace-ai[langchain]')
+# from memtrace.langchain import enable_langchain_instrumentation
+# enable_langchain_instrumentation()   # once, after init_tracer(); do not combine with option 1
+
+# Pydantic AI - automatic (pip install 'memtrace-ai[pydantic-ai]')
+# from memtrace.pydantic_ai import enable_pydantic_ai_instrumentation
+# enable_pydantic_ai_instrumentation()
+
+shutdown()  # optional: the OTel SDK also flushes at exit; use flush() in short scripts / serverless
+```
+
+**Error policy**: the tracing calls never raise into your code. The only exceptions are the `enable_*_instrumentation()` functions, which raise `ImportError` if their extra is not installed.
+
+**Conversations**: wrap each turn with `with memtrace.session("conversation-id"):` (or pass `thread_id` / `session_id` / `conversation_id` in LangChain's `metadata`) and the dashboard groups the traces into one conversation. The id must be stable across turns, unique per conversation and free of personal data (it shows up in URLs). Without it, every turn is a standalone trace. `session()` also applies to spans emitted by auto-instrumented libraries.
+
+Spans created inside a `@trace_step` (or inside `with memtrace.session("id")`) hang from it, including those of the LangChain handler and of auto-instrumented libraries.
+
+`trace_step`, `trace_step_context` and `trace_llm_call` accept `service=` (the value returned by `init_tracer`) to use an explicit tracer instead of the global one.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `MEMTRACE_ENABLED` | `true` | `false` disables everything (no-op) |
+| `MEMTRACE_SERVICE_NAME` | `default-agent` | `service.name` |
+| `MEMTRACE_SERVICE_VERSION`, `MEMTRACE_ENVIRONMENT` | - | Resource attributes |
+| `MEMTRACE_OTLP_ENDPOINT` | `http://localhost:4318` (http) / `:4317` (grpc) | any OTLP endpoint |
+| `MEMTRACE_OTLP_PROTOCOL` | `http/protobuf` | or `grpc` (extra `grpc`) |
+| `MEMTRACE_OTLP_HEADERS` | - | `k1=v1,k2=v2` |
+| `MEMTRACE_CAPTURE_CONTENT` | `false` | store prompts/completions/arguments (ADR-004); also gates the auto-instrumentations |
+| `MEMTRACE_MAX_CONTENT_LENGTH` | `16384` | truncation of captured content |
+| `MEMTRACE_REDACT_KEYS` | - | extra key names to mask, on top of the built-in list (ADR-021) |
+| `MEMTRACE_SPAN_TTL_SECONDS` | `3600` | closes orphaned spans |
+| `MEMTRACE_MAX_ACTIVE_RUNS` | `10000` | cap on in-flight spans |
+| `MEMTRACE_EXPORT_TIMEOUT_MS`, `MEMTRACE_BATCH_MAX_QUEUE_SIZE`, `MEMTRACE_BATCH_SCHEDULE_DELAY_MS`, `MEMTRACE_BATCH_MAX_EXPORT_SIZE` | 5000 / 2048 / 5000 / 512 | `BatchSpanProcessor` |
+
+**Redaction**: secrets are masked in every exported span, by key name (`api_key`, `password`, …) and by shape (`sk-…`, JWTs, `Bearer …`, URL credentials). Personal data (emails, names, IDs) is anonymized only if you opt in with the `pii` extra: `init_tracer(redact=presidio_redactor(language="es"))` (`from memtrace.pii import presidio_redactor`; also `python -m spacy download <model>`), or with your own `init_tracer(redact=fn)`.
+
+Self-signed TLS: `OTEL_EXPORTER_OTLP_CERTIFICATE` (standard OTel) with an `https://` endpoint.
+
+## Architecture
+
+Hexagonal (ADR-008): `domain` (pure) → `application` (`SpanPort` port + `TracingService`) ← `adapters/inbound` (decorators, LangChain, Pydantic AI) and `adapters/outbound` (OpenTelemetry, no-op). `dependency_container.py` is the composition root. The dependency rule is checked by `tests/test_architecture.py`. Auto-instrumentors receive MemTrace's tracer provider explicitly, never a global one, and every span passes through a redacting exporter before it leaves the process (ADR-021).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check memtrace tests && mypy memtrace && pytest
+```

memtrace_ai-0.2.0/memtrace/__init__.py

@@ -0,0 +1,31 @@
+from memtrace import prompts
+from memtrace._version import __version__
+from memtrace.adapters.inbound.manual import record_retrieved_chunks, trace_llm_call, trace_step, trace_step_context
+from memtrace.application.context import get_current_run_id, session, user
+from memtrace.dependency_container import flush, init_tracer, shutdown
+from memtrace.langchain import MemTraceCallbackHandler, enable_langchain_instrumentation
+from memtrace.openai_agents import enable_openai_agents_instrumentation
+from memtrace.pydantic_ai import enable_pydantic_ai_instrumentation
+from memtrace.user_feedback import current_trace_id, feedback, retract_feedback
+
+__all__ = [
+    "__version__",
+    "init_tracer",
+    "flush",
+    "shutdown",
+    "session",
+    "user",
+    "trace_step",
+    "trace_step_context",
+    "trace_llm_call",
+    "record_retrieved_chunks",
+    "get_current_run_id",
+    "current_trace_id",
+    "feedback",
+    "retract_feedback",
+    "prompts",
+    "MemTraceCallbackHandler",
+    "enable_langchain_instrumentation",
+    "enable_pydantic_ai_instrumentation",
+    "enable_openai_agents_instrumentation",
+]

memtrace_ai-0.2.0/memtrace/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

memtrace_ai-0.2.0/memtrace/adapters/inbound/asgi/__init__.py

@@ -0,0 +1,3 @@
+from memtrace.adapters.inbound.asgi.prompt_override import PromptOverrideMiddleware
+
+__all__ = ["PromptOverrideMiddleware"]

memtrace_ai-0.2.0/memtrace/adapters/inbound/asgi/prompt_override.py

@@ -0,0 +1,39 @@
+"""ASGI middleware that lets MemTrace's playground test a prompt version in this agent (ADR-071).
+
+MemTrace calls the agent's chat with the token of a short-lived override in the `x-memtrace-prompt-override` header. This
+middleware reads it and, for the duration of that request only, makes `handle.compile()` ask MemTrace for the version the
+token grants. It does nothing unless the agent opted in with `MEMTRACE_ALLOW_PROMPT_OVERRIDE=true`, and a token MemTrace
+does not recognize changes nothing.
+"""
+from typing import Any, Awaitable, Callable, MutableMapping
+
+from memtrace.application.prompt_override import use_override
+from memtrace.config import settings
+from memtrace.domain.prompt import PROMPT_OVERRIDE_HEADER, is_override_token
+
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+
+
+class PromptOverrideMiddleware:
+    """Pure ASGI (FastAPI, Starlette, Quart…): `app.add_middleware(PromptOverrideMiddleware)`."""
+
+    def __init__(self, app: Callable[[Scope, Receive, Send], Awaitable[None]]) -> None:
+        self.app = app
+        self._header = PROMPT_OVERRIDE_HEADER.encode("latin-1")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        token = self._token(scope) if scope.get("type") in ("http", "websocket") and settings.allow_prompt_override else None
+        if token is None:
+            await self.app(scope, receive, send)
+            return
+        with use_override(token):
+            await self.app(scope, receive, send)
+
+    def _token(self, scope: Scope) -> "str | None":
+        for name, value in scope.get("headers") or ():
+            if name.lower() == self._header:
+                candidate = value.decode("latin-1")
+                return candidate if is_override_token(candidate) else None
+        return None

memtrace_ai-0.2.0/memtrace/adapters/inbound/auto_instrumentation.py

@@ -0,0 +1,22 @@
+"""Shared plumbing for "auto" instrumentors (LangChain, Pydantic AI…): each just points a
+third-party library at the tracer provider configured by `init_tracer`, no callbacks needed.
+"""
+import logging
+from typing import Any, Optional, Tuple
+
+from memtrace.application.tracing_service import TracingService
+from memtrace.dependency_container import get_service
+
+logger = logging.getLogger("memtrace")
+
+
+def resolve_tracer_provider(feature: str, service: Optional[TracingService] = None) -> Tuple[TracingService, Optional[Any]]:
+    """The `(service, tracer_provider)` to instrument with, or `(service, None)` if tracing is off.
+
+    `feature`: human-readable name for the log line (e.g. "LangChain", "Pydantic AI").
+    """
+    service = service or get_service()
+    provider = service.tracer_provider
+    if provider is None:
+        logger.info("[MemTrace] Tracing is off; %s instrumentation not enabled.", feature)
+    return service, provider

memtrace_ai-0.2.0/memtrace/adapters/inbound/langchain/__init__.py

@@ -0,0 +1,5 @@
+from memtrace.adapters.inbound.langchain.auto import enable_langchain_instrumentation
+from memtrace.adapters.inbound.langchain.callback import MemTraceCallbackHandler
+from memtrace.adapters.inbound.langchain.prompt_middleware import prompt_middleware
+
+__all__ = ["MemTraceCallbackHandler", "enable_langchain_instrumentation", "prompt_middleware"]

memtrace_ai-0.2.0/memtrace/adapters/inbound/langchain/auto.py

@@ -0,0 +1,43 @@
+"""Automatic LangChain / LangGraph instrumentation through OpenTelemetry's instrumentor."""
+import logging
+import os
+from typing import Optional
+
+from memtrace.adapters.inbound.auto_instrumentation import resolve_tracer_provider
+from memtrace.application.tracing_service import TracingService
+
+logger = logging.getLogger("memtrace")
+
+_INSTALL_HINT = "pip install 'memtrace-ai[langchain]'"
+_CONTENT_ENV = "TRACELOOP_TRACE_CONTENT"  # honored by opentelemetry-instrumentation-langchain
+
+
+def enable_langchain_instrumentation(service: Optional[TracingService] = None) -> None:
+    """Enables automatic LangChain / LangGraph instrumentation (no callbacks needed).
+
+    Requires: pip install 'memtrace-ai[langchain]'. Raises ImportError if it is missing.
+
+    Spans go to the tracer configured by `init_tracer`, and prompts/completions are only
+    recorded when MEMTRACE_CAPTURE_CONTENT=true. Safe to call more than once. It is an alternative to
+    MemTraceCallbackHandler; use one of them, not both, or every run is traced twice.
+    """
+    try:
+        from opentelemetry.instrumentation.langchain import LangchainInstrumentor
+    except ImportError as exc:
+        raise ImportError(f"LangChain instrumentation requires: {_INSTALL_HINT}") from exc
+
+    # provider is process-wide, survives shutdown()/init_tracer()
+    service, provider = resolve_tracer_provider("LangChain", service)
+    if provider is None:
+        return
+
+    # Respect the privacy default of ADR-004 unless the user set the instrumentor's own switch
+    os.environ.setdefault(_CONTENT_ENV, "true" if service.captures_content else "false")
+
+    instrumentor = LangchainInstrumentor()
+    if instrumentor.is_instrumented_by_opentelemetry:
+        # Already bound to MemTrace's switchable provider, which follows init_tracer()/shutdown()
+        logger.debug("[MemTrace] LangChain auto-instrumentation was already enabled")
+        return
+    instrumentor.instrument(tracer_provider=provider)
+    logger.info("[MemTrace] LangChain auto-instrumentation enabled")

memtrace_ai-0.2.0/memtrace/adapters/inbound/langchain/callback.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from memtrace.adapters.inbound.langchain.mapping import (
+    generation_dicts,
+    message_dicts,
+    request_to_call,
+    response_to_call,
+    step_name,
+)
+from memtrace.application.retrieval_capture import note_retrieved
+from memtrace.application.tracing_service import TracingService
+from memtrace.dependency_container import get_service
+from memtrace.domain import semconv as sc
+from memtrace.domain.attributes import llm_attributes, retrieved_chunks
+from memtrace.domain.model import StepType
+from memtrace.domain.serialization import to_json
+
+logger = logging.getLogger("memtrace")
+
+_INSTALL_HINT = "pip install 'memtrace-ai[langchain]'"
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+except ImportError:
+    class BaseCallbackHandler:  # type: ignore[no-redef]
+        """Stand-in so importing this module never requires LangChain; instantiating does."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(f"MemTraceCallbackHandler requires LangChain: {_INSTALL_HINT}")
+
+
+class MemTraceCallbackHandler(BaseCallbackHandler):
+    """LangChain / LangGraph callback handler.
+
+    Usage: `chain.invoke(x, config={"callbacks": [MemTraceCallbackHandler()]})`.
+    Inside a `@trace_step`, its spans hang from it.
+    """
+
+    def __init__(self, service: Optional[TracingService] = None) -> None:
+        super().__init__()
+        self._service = service or get_service()
+
+    # ----- helpers -----
+
+    def _context_attrs(self, tags: Optional[List[str]], metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        md = metadata or {}
+        return {
+            sc.MEMTRACE_TAGS: [str(t) for t in tags] if tags else None,
+            sc.MEMTRACE_METADATA: to_json(md, self._service.max_content_length) if md else None,
+            # `thread_id` is the LangGraph conversation identifier
+            sc.GEN_AI_CONVERSATION_ID: md.get("session_id") or md.get("conversation_id") or md.get("thread_id"),
+            sc.ENDUSER_ID: md.get("user_id"),
+            # LangGraph injects `langgraph_node`/`langgraph_step` into each run's metadata (ADR-011)
+            # the graph's own root run has no `langgraph_*` keys, only `ls_integration` (ADR-011)
+            sc.MEMTRACE_FRAMEWORK: "langgraph" if md.get("ls_integration") == "langgraph" or any(k.startswith("langgraph_") for k in md) else "langchain",
+        }
+
+    def _start(self, name, step_type, run_id, parent_run_id, tags, metadata, extra=None) -> None:
+        attrs = {**self._context_attrs(tags, metadata), **(extra or {})}
+        self._service.start_run(name, step_type, run_id=run_id, parent_run_id=parent_run_id, attributes=attrs)
+
+    def _end(self, run_id, attrs=None, error=None) -> None:
+        self._service.end_run(run_id, error=error, attributes=attrs)
+
+    # ----- chains / agents -----
+
+    def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs) -> Any:
+        self._start(step_name(serialized, kwargs, "Chain"), StepType.CHAIN, run_id, parent_run_id, tags, metadata,
+                    {sc.MEMTRACE_INPUT: self._service.capture(inputs)})
+
+    def on_chain_end(self, outputs, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        self._end(run_id, {sc.MEMTRACE_OUTPUT: self._service.capture(outputs)})
+
+    def on_chain_error(self, error, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        self._end(run_id, error=error)
+
+    # ----- tools -----
+
+    def on_tool_start(self, serialized, input_str, *, run_id, parent_run_id=None, tags=None, metadata=None, inputs=None, **kwargs) -> Any:
+        name = step_name(serialized, kwargs, "Tool")
+        self._start(name, StepType.TOOL, run_id, parent_run_id, tags, metadata, {
+            sc.GEN_AI_TOOL_NAME: name,
+            sc.GEN_AI_TOOL_CALL_ID: kwargs.get("tool_call_id"),
+            sc.GEN_AI_TOOL_CALL_ARGUMENTS: self._service.capture(inputs if inputs is not None else input_str),
+        })
+
+    def on_tool_end(self, output, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        result = getattr(output, "content", output)  # ToolMessage or plain value
+        self._end(run_id, {sc.GEN_AI_TOOL_CALL_RESULT: self._service.capture(result)})
+
+    def on_tool_error(self, error, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        self._end(run_id, error=error)
+
+    # ----- retrievers -----
+
+    def on_retriever_start(self, serialized, query, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs) -> Any:
+        self._start(step_name(serialized, kwargs, "Retriever"), StepType.RETRIEVER, run_id, parent_run_id, tags, metadata,
+                    {sc.MEMTRACE_INPUT: self._service.capture(query)})
+
+    def on_retriever_end(self, documents, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        chunks = retrieved_chunks(documents)
+        note_retrieved(chunks)
+        self._end(run_id, {
+            sc.MEMTRACE_RETRIEVER_DOCUMENTS: len(documents or []),
+            sc.MEMTRACE_RETRIEVER_CHUNKS: self._service.capture(chunks),
+        })
+
+    def on_retriever_error(self, error, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        self._end(run_id, error=error)
+
+    # ----- LLMs -----
+
+    def _llm_start(self, serialized, run_id, parent_run_id, tags, metadata, invocation_params, kwargs, input_messages) -> None:
+        call = request_to_call(metadata, invocation_params or kwargs.get("invocation_params") or {})
+        base = step_name(serialized, {}, "llm")
+        self._start(
+            f"{base}: {call.model}" if call.model else base, StepType.LLM, run_id, parent_run_id, tags, metadata,
+            llm_attributes(call, self._service.capture(input_messages)),
+        )
+
+    def on_chat_model_start(self, serialized, messages, *, run_id, parent_run_id=None, tags=None, metadata=None, invocation_params=None, **kwargs) -> Any:
+        self._llm_start(serialized, run_id, parent_run_id, tags, metadata, invocation_params, kwargs,
+                        message_dicts(messages) if self._service.captures_content else None)
+
+    def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None, tags=None, metadata=None, invocation_params=None, **kwargs) -> Any:
+        self._llm_start(serialized, run_id, parent_run_id, tags, metadata, invocation_params, kwargs,
+                        [{"role": "user", "content": p} for p in prompts])
+
+    def on_llm_end(self, response, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        try:
+            output = generation_dicts(response) if self._service.captures_content else None
+            attrs = llm_attributes(response_to_call(response), output_messages=self._service.capture(output))
+        except Exception as exc:  # an unexpectedly shaped response must not lose the span
+            logger.warning("[MemTrace] Error extracting data from the LLM response: %s", exc)
+            attrs = None
+        self._end(run_id, attrs)
+
+    def on_llm_error(self, error, *, run_id, parent_run_id=None, **kwargs) -> Any:
+        self._end(run_id, error=error)

memtrace_ai-0.2.0/memtrace/adapters/inbound/langchain/mapping.py

@@ -0,0 +1,110 @@
+"""Pure translation of LangChain structures into domain concepts. No `TracingService`, no OTel."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from memtrace.domain.model import LlmCall
+
+
+def _get(obj: Any, key: str) -> Any:
+    return obj.get(key) if isinstance(obj, dict) else getattr(obj, key, None)
+
+
+def _as_int(val: Any) -> Optional[int]:
+    return val if isinstance(val, int) and not isinstance(val, bool) else None
+
+
+def _tokens(usage: Any) -> Tuple[Optional[int], Optional[int], Optional[int]]:
+    """(input, output, total) from `usage_metadata` (LangChain), `token_usage` (OpenAI) or `usage` (Anthropic)."""
+    if not usage:
+        return None, None, None
+    inp = _as_int(_get(usage, "input_tokens"))
+    inp = inp if inp is not None else _as_int(_get(usage, "prompt_tokens"))
+    out = _as_int(_get(usage, "output_tokens"))
+    out = out if out is not None else _as_int(_get(usage, "completion_tokens"))
+    return inp, out, _as_int(_get(usage, "total_tokens"))
+
+
+def response_to_call(response: Any) -> LlmCall:
+    """Response data of an `LLMResult` (duck-typed): messages first, `llm_output` as a fallback."""
+    inp = out = total = None
+    model = resp_id = None
+    finish: List[str] = []
+
+    for gens in getattr(response, "generations", None) or []:
+        for gen in gens or []:
+            msg = _get(gen, "message")
+            meta = _get(msg, "response_metadata") or {}
+            info = _get(gen, "generation_info") or {}
+            if inp is None and out is None:
+                inp, out, total = _tokens(_get(msg, "usage_metadata"))
+            model = model or _get(meta, "model_name") or _get(meta, "model")
+            resp_id = resp_id or _get(msg, "id") or _get(meta, "id")
+            reason = _get(info, "finish_reason") or _get(meta, "finish_reason") or _get(meta, "stop_reason")
+            if reason:
+                finish.append(str(reason))
+
+    llm_output = getattr(response, "llm_output", None) or {}
+    if inp is None and out is None:
+        inp, out, total = _tokens(_get(llm_output, "token_usage") or _get(llm_output, "usage"))
+    model = model or _get(llm_output, "model_name") or _get(llm_output, "model")
+    return LlmCall(
+        response_model=model, response_id=resp_id, finish_reasons=finish,
+        input_tokens=inp, output_tokens=out, total_tokens=total,
+    )
+
+
+def request_to_call(metadata: Optional[Dict[str, Any]], params: Dict[str, Any]) -> LlmCall:
+    md = metadata or {}
+    return LlmCall(
+        provider=md.get("ls_provider") or params.get("_type"),
+        model=md.get("ls_model_name") or params.get("model_name") or params.get("model") or params.get("model_id"),
+        temperature=md.get("ls_temperature", params.get("temperature")),
+        max_tokens=md.get("ls_max_tokens", params.get("max_tokens") or params.get("max_tokens_to_sample")),
+        top_p=params.get("top_p"),
+        frequency_penalty=params.get("frequency_penalty"),
+        presence_penalty=params.get("presence_penalty"),
+    )
+
+
+def step_name(serialized: Optional[Dict[str, Any]], kwargs: Dict[str, Any], default: str) -> str:
+    """`serialized` may be None (LangGraph, runnables); LangChain passes `name` as a kwarg."""
+    ser = serialized or {}
+    ident = ser.get("id")
+    return kwargs.get("name") or ser.get("name") or (ident[-1] if ident else None) or default
+
+
+def _tool_calls_of(msg: Any) -> Any:
+    """`tool_calls` of the model message (or of `additional_kwargs` for some providers)."""
+    calls = getattr(msg, "tool_calls", None)
+    if not calls:
+        calls = (getattr(msg, "additional_kwargs", None) or {}).get("tool_calls")
+    return calls or None
+
+
+def message_dicts(messages: List[List[Any]]) -> List[Dict[str, Any]]:
+    out = []
+    for batch in messages:
+        for m in batch:
+            d: Dict[str, Any] = {
+                "role": getattr(m, "type", None) or getattr(m, "role", None) or "user",
+                "content": getattr(m, "content", str(m)),
+            }
+            calls = _tool_calls_of(m)
+            if calls:
+                d["tool_calls"] = calls
+            out.append(d)
+    return out
+
+
+def generation_dicts(response: Any) -> List[Dict[str, Any]]:
+    out = []
+    for gens in getattr(response, "generations", None) or []:
+        for g in gens:
+            msg = getattr(g, "message", None)
+            d: Dict[str, Any] = {"role": getattr(msg, "type", "assistant"), "content": getattr(g, "text", "")}
+            calls = _tool_calls_of(msg)
+            if calls:
+                d["tool_calls"] = calls
+            out.append(d)
+    return out