moda-claude-agent-sdk 0.1.0__tar.gz

moda_claude_agent_sdk-0.1.0/.gitignore

@@ -0,0 +1,188 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# compiled output
+dist
+tmp
+/out-tsc
+
+# dependencies
+node_modules
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+npm-debug.log
+yarn-error.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db
+
+.cache/
+reports/
+.vscode/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# NX
+.nx
+
+# Test artifcats
+chroma.sqlite3
+
+# Claude
+.claude
+
+# Development files
+packages/sample-app/sample_app/development/
+
+# VCR test cassettes
+**/tests/cassettes/

moda_claude_agent_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

moda_claude_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: moda-claude-agent-sdk
+Version: 0.1.0
+Summary: Moda Claude Agent SDK instrumentation for LLM observability
+Project-URL: Repository, https://github.com/ModaLabs/moda-python/tree/main/packages/moda-claude-agent-sdk
+Author-email: Moda Labs <support@moda.so>
+License-Expression: Apache-2.0
+Requires-Python: <4,>=3.10
+Requires-Dist: opentelemetry-api<2,>=1.38.0
+Requires-Dist: opentelemetry-instrumentation>=0.59b0
+Requires-Dist: opentelemetry-semantic-conventions-ai<0.5.0,>=0.4.13
+Requires-Dist: opentelemetry-semantic-conventions>=0.59b0
+Provides-Extra: instruments
+Requires-Dist: claude-agent-sdk; extra == 'instruments'
+Description-Content-Type: text/markdown
+
+# moda-claude-agent-sdk
+
+OpenTelemetry instrumentation for the Claude Agent SDK.

moda_claude_agent_sdk-0.1.0/README.md

@@ -0,0 +1,3 @@
+# moda-claude-agent-sdk
+
+OpenTelemetry instrumentation for the Claude Agent SDK.

moda_claude_agent_sdk-0.1.0/opentelemetry/instrumentation/claude_agent_sdk/__init__.py

@@ -0,0 +1,172 @@
+"""OpenTelemetry Claude Agent SDK instrumentation.
+
+Instruments the Claude Agent SDK (claude-agent-sdk) to capture agent execution
+spans. Since the Claude Agent SDK spawns Claude Code as a subprocess, standard
+Anthropic API instrumentation doesn't capture any calls. This instrumentor wraps
+the SDK's own methods to extract conversation data from the messages it yields.
+"""
+
+import logging
+from typing import Collection
+
+from opentelemetry.instrumentation.claude_agent_sdk.streaming import (
+    WrappedAgentStream,
+    _set_span_attribute,
+)
+from opentelemetry.instrumentation.claude_agent_sdk.version import __version__
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.utils import unwrap
+from opentelemetry.trace import SpanKind, get_tracer
+from wrapt import wrap_function_wrapper
+
+logger = logging.getLogger(__name__)
+
+_instruments = ("claude-agent-sdk",)
+
+WRAPPED_METHODS = [
+    {
+        "package": "claude_agent_sdk",
+        "object": "ClaudeSDKClient",
+        "method": "query",
+    },
+    {
+        "package": "claude_agent_sdk",
+        "object": "ClaudeSDKClient",
+        "method": "receive_response",
+    },
+]
+
+
+class ClaudeAgentSDKInstrumentor(BaseInstrumentor):
+    """OpenTelemetry instrumentor for the Claude Agent SDK."""
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        tracer_provider = kwargs.get("tracer_provider")
+        tracer = get_tracer(__name__, __version__, tracer_provider)
+
+        # Wrap query() — async method that sends the prompt
+        try:
+            wrap_function_wrapper(
+                "claude_agent_sdk",
+                "ClaudeSDKClient.query",
+                _wrap_query(tracer),
+            )
+        except Exception as e:
+            logger.debug(f"Failed to wrap ClaudeSDKClient.query: {e}")
+
+        # Wrap receive_response() — async generator method
+        try:
+            wrap_function_wrapper(
+                "claude_agent_sdk",
+                "ClaudeSDKClient.receive_response",
+                _wrap_receive_response(tracer),
+            )
+        except Exception as e:
+            logger.debug(f"Failed to wrap ClaudeSDKClient.receive_response: {e}")
+
+    def _uninstrument(self, **kwargs):
+        import claude_agent_sdk
+
+        for method_info in WRAPPED_METHODS:
+            try:
+                obj = getattr(claude_agent_sdk, method_info["object"])
+                unwrap(obj, method_info["method"])
+            except Exception as e:
+                logger.debug(f"Failed to unwrap {method_info['object']}.{method_info['method']}: {e}")
+
+
+def _wrap_query(tracer):
+    """Wrap ClaudeSDKClient.query() to capture the prompt on the instance."""
+
+    async def wrapper(wrapped, instance, args, kwargs):
+        # Store the prompt on the instance so receive_response wrapper can access it
+        prompt = args[0] if args else kwargs.get("prompt", "")
+        instance._moda_last_prompt = prompt
+        return await wrapped(*args, **kwargs)
+
+    return wrapper
+
+
+def _wrap_receive_response(tracer):
+    """Wrap ClaudeSDKClient.receive_response() to create a span and wrap the stream.
+
+    receive_response() is an async generator function. Our wrapper must also be
+    an async generator — we yield each message through a WrappedAgentStream that
+    accumulates token usage and finalizes the span when the stream is exhausted.
+    """
+
+    async def wrapper(wrapped, instance, args, kwargs):
+        # Get the model from instance options (defensive access)
+        model = _get_model(instance)
+
+        # Get conversation/user context from Moda context vars
+        conversation_id = None
+        user_id = None
+        try:
+            from traceloop.sdk.conversation import get_conversation_id, get_user_id
+
+            conversation_id = get_conversation_id()
+            user_id = get_user_id()
+        except ImportError:
+            pass
+
+        # Create span for this agent run
+        span = tracer.start_span(
+            "claude_agent.chat",
+            kind=SpanKind.CLIENT,
+            attributes={
+                "gen_ai.system": "Anthropic",
+                "llm.request_type": "chat",
+            },
+        )
+
+        # Set known attributes upfront
+        if model:
+            _set_span_attribute(span, "gen_ai.request.model", model)
+        if conversation_id:
+            _set_span_attribute(span, "moda.conversation_id", conversation_id)
+        if user_id:
+            _set_span_attribute(span, "moda.user_id", user_id)
+
+        # Capture the prompt if stored by query() wrapper
+        prompt = getattr(instance, "_moda_last_prompt", None)
+        if prompt:
+            _set_span_attribute(span, "gen_ai.prompt", str(prompt)[:1000])
+
+        # Call original async generator and wrap it
+        async_gen = wrapped(*args, **kwargs)
+        stream = WrappedAgentStream(async_gen, instance, span)
+
+        # Yield through — try/finally ensures span is finalized on early exit (break, cancel)
+        try:
+            async for msg in stream:
+                yield msg
+        finally:
+            stream._finalize()
+
+    return wrapper
+
+
+def _get_model(instance) -> str:
+    """Defensively extract the model name from a ClaudeSDKClient instance."""
+    # Try instance.options.model
+    options = getattr(instance, "options", None)
+    if options:
+        model = getattr(options, "model", None)
+        if model:
+            return str(model)
+
+    # Try instance.model
+    model = getattr(instance, "model", None)
+    if model:
+        return str(model)
+
+    # Try instance._model
+    model = getattr(instance, "_model", None)
+    if model:
+        return str(model)
+
+    return ""

moda_claude_agent_sdk-0.1.0/opentelemetry/instrumentation/claude_agent_sdk/streaming.py

@@ -0,0 +1,206 @@
+"""Wrapped async generator for Claude Agent SDK receive_response() streams."""
+
+import logging
+
+from opentelemetry.trace import Span
+from opentelemetry.trace.status import Status, StatusCode
+
+logger = logging.getLogger(__name__)
+
+
+def _set_span_attribute(span: Span, name: str, value):
+    """Set a span attribute only if value is not None."""
+    if value is not None and value != "":
+        try:
+            span.set_attribute(name, value)
+        except Exception:
+            pass
+
+
+def _get(obj, key, default=None):
+    """Get a value from an object that may be a dict or an object with attributes."""
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+class WrappedAgentStream:
+    """Async iterator proxy that wraps the Claude Agent SDK's receive_response() async generator.
+
+    Yields each message through while accumulating token usage, tool call counts,
+    and agent metadata. Finalizes the span when the stream is exhausted.
+
+    Token data comes from two possible sources:
+      1. ResultMessage.usage dict (primary — always present at end of run)
+      2. StreamEvent with message_start/message_delta (when include_partial_messages=True)
+    """
+
+    def __init__(self, async_gen, instance, span: Span):
+        self._async_gen = async_gen
+        self._instance = instance
+        self._span = span
+        self._finalized = False
+
+        # Accumulated data
+        self._input_tokens = 0
+        self._output_tokens = 0
+        self._tool_call_count = 0
+        self._num_turns = None
+        self._session_id = None
+        self._model = None
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        try:
+            msg = await self._async_gen.__anext__()
+        except StopAsyncIteration:
+            self._finalize()
+            raise
+        except Exception as e:
+            self._finalize(error=e)
+            raise
+
+        self._process_message(msg)
+        return msg
+
+    async def aclose(self):
+        """Finalize span when consumer exits the loop early (break, cancel, etc.)."""
+        self._finalize()
+        if hasattr(self._async_gen, 'aclose'):
+            await self._async_gen.aclose()
+
+    def _process_message(self, msg):
+        """Extract data from each message yielded by the agent stream."""
+        try:
+            msg_type = type(msg).__name__
+
+            # Type-name matching with duck-typing fallbacks for robustness
+            if msg_type == "ResultMessage" or (
+                hasattr(msg, "num_turns") and hasattr(msg, "usage")
+            ):
+                self._handle_result_message(msg)
+            elif msg_type == "AssistantMessage" or (
+                hasattr(msg, "model") and hasattr(msg, "content")
+            ):
+                self._handle_assistant_message(msg)
+            elif msg_type == "StreamEvent" or hasattr(msg, "event"):
+                self._handle_stream_event(msg)
+            # SystemMessage, UserMessage, etc. — ignored
+        except Exception as e:
+            logger.debug(f"Error processing agent message: {e}")
+
+    def _handle_result_message(self, msg):
+        """Extract token usage and metadata from the final ResultMessage.
+
+        ResultMessage.usage is a dict like:
+            {'input_tokens': 10, 'output_tokens': 91,
+             'cache_read_input_tokens': 1952, 'cache_creation_input_tokens': 0, ...}
+        """
+        self._num_turns = getattr(msg, "num_turns", None)
+        self._session_id = getattr(msg, "session_id", None)
+
+        # Token usage from ResultMessage.usage dict (primary source)
+        usage = getattr(msg, "usage", None)
+        if usage and isinstance(usage, dict):
+            input_tokens = usage.get("input_tokens", 0) or 0
+            cache_read = usage.get("cache_read_input_tokens", 0) or 0
+            cache_create = usage.get("cache_creation_input_tokens", 0) or 0
+            output_tokens = usage.get("output_tokens", 0) or 0
+
+            # Total input includes cache tokens
+            total_input = input_tokens + cache_read + cache_create
+
+            # Only override if we got real data (don't clobber StreamEvent accumulation)
+            if total_input > 0 or output_tokens > 0:
+                self._input_tokens = total_input
+                self._output_tokens = output_tokens
+
+    def _handle_assistant_message(self, msg):
+        """Extract model name and count tool calls from assistant messages."""
+        # Model name
+        model = getattr(msg, "model", None)
+        if model:
+            self._model = str(model)
+
+        # Count tool use blocks
+        content = getattr(msg, "content", None)
+        if not content:
+            return
+
+        if isinstance(content, list):
+            for block in content:
+                block_type = type(block).__name__
+                if block_type == "ToolUseBlock":
+                    self._tool_call_count += 1
+                elif hasattr(block, "type"):
+                    attr_type = getattr(block, "type", None)
+                    if attr_type == "tool_use":
+                        self._tool_call_count += 1
+
+    def _handle_stream_event(self, msg):
+        """Extract token usage from raw Anthropic streaming events.
+
+        Only present when include_partial_messages=True. The event field is a dict.
+        These are accumulated across turns; ResultMessage.usage takes precedence
+        if present (see _handle_result_message).
+        """
+        event = getattr(msg, "event", None)
+        if event is None:
+            return
+
+        event_type = _get(event, "type")
+
+        if event_type == "message_start":
+            message = _get(event, "message")
+            if message:
+                usage = _get(message, "usage")
+                if usage:
+                    input_tokens = _get(usage, "input_tokens", 0)
+                    if input_tokens:
+                        self._input_tokens += input_tokens
+                model = _get(message, "model")
+                if model:
+                    self._model = model
+
+        elif event_type == "message_delta":
+            usage = _get(event, "usage")
+            if usage:
+                output_tokens = _get(usage, "output_tokens", 0)
+                if output_tokens:
+                    self._output_tokens += output_tokens
+
+    def _finalize(self, error=None):
+        """Set accumulated attributes on the span and end it."""
+        if self._finalized:
+            return
+        self._finalized = True
+
+        try:
+            if error:
+                self._span.set_status(Status(StatusCode.ERROR, str(error)))
+                _set_span_attribute(self._span, "error.type", type(error).__name__)
+            else:
+                self._span.set_status(Status(StatusCode.OK))
+
+            # Model — only update response model; request model was set upfront
+            if self._model:
+                _set_span_attribute(self._span, "gen_ai.response.model", self._model)
+
+            # Token usage
+            _set_span_attribute(self._span, "gen_ai.usage.input_tokens", self._input_tokens)
+            _set_span_attribute(self._span, "gen_ai.usage.output_tokens", self._output_tokens)
+            _set_span_attribute(
+                self._span, "llm.usage.total_tokens", self._input_tokens + self._output_tokens
+            )
+
+            # Agent-specific attributes
+            _set_span_attribute(self._span, "claude_agent.num_turns", self._num_turns)
+            _set_span_attribute(self._span, "claude_agent.session_id", self._session_id)
+            _set_span_attribute(self._span, "claude_agent.tool_call_count", self._tool_call_count)
+
+        except Exception as e:
+            logger.debug(f"Error finalizing agent span: {e}")
+        finally:
+            self._span.end()

moda_claude_agent_sdk-0.1.0/opentelemetry/instrumentation/claude_agent_sdk/version.py

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

moda_claude_agent_sdk-0.1.0/project.json

@@ -0,0 +1,77 @@
+{
+  "name": "opentelemetry-instrumentation-claude-agent-sdk",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/moda-claude-agent-sdk/opentelemetry",
+  "targets": {
+    "lock": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "uv lock",
+        "cwd": "packages/moda-claude-agent-sdk"
+      }
+    },
+    "add": {
+      "executor": "@nxlv/python:add",
+      "options": {}
+    },
+    "update": {
+      "executor": "@nxlv/python:update",
+      "options": {}
+    },
+    "remove": {
+      "executor": "@nxlv/python:remove",
+      "options": {}
+    },
+    "build": {
+      "executor": "@nxlv/python:build",
+      "outputs": [
+        "{projectRoot}/dist"
+      ],
+      "options": {
+        "outputPath": "packages/moda-claude-agent-sdk/dist",
+        "publish": false,
+        "lockedVersions": true,
+        "bundleLocalDependencies": true
+      }
+    },
+    "install": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "uv sync --all-groups",
+        "cwd": "packages/moda-claude-agent-sdk"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "uv run ruff check .",
+        "cwd": "packages/moda-claude-agent-sdk"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "outputs": [
+        "{workspaceRoot}/reports/packages/moda-claude-agent-sdk/unittests",
+        "{workspaceRoot}/coverage/packages/moda-claude-agent-sdk"
+      ],
+      "options": {
+        "command": "uv run pytest tests/",
+        "cwd": "packages/moda-claude-agent-sdk"
+      }
+    },
+    "build-release": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          "chmod +x ../../scripts/build-release.sh",
+          "../../scripts/build-release.sh"
+        ],
+        "cwd": "packages/moda-claude-agent-sdk"
+      }
+    }
+  },
+  "tags": [
+    "instrumentation"
+  ]
+}