chatsee-claude-agent-sdk 0.1.0__tar.gz

chatsee_claude_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: chatsee-claude-agent-sdk
+Version: 0.1.0
+Summary: ChatSee connector for the Claude Agent SDK — capture every turn with one line.
+Maintainer-email: ChatSee <contact@chatsee.ai>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: chatsee-ai>=0.14.0
+Requires-Dist: claude-agent-sdk>=0.2.100
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: chatsee-connector-testing; extra == "dev"
+
+# chatsee-claude-agent-sdk
+
+ChatSee connector for the **Claude Agent SDK** — Anthropic's agent framework,
+the one that powers Claude Code.
+
+```bash
+pip install chatsee-claude-agent-sdk
+```
+
+```python
+from chatsee_claude_agent_sdk import instrument_claude_agent_sdk
+
+chatsee = instrument_claude_agent_sdk(agent_id="...", tenant_id="...")
+
+async for message in chatsee.query(prompt="where is my order", options=opts):
+    ...
+```
+
+`chatsee-ai` is installed for you as a dependency.
+
+## Not the same thing as `chatsee-anthropic`
+
+| | `chatsee-anthropic` | this |
+| --- | --- | --- |
+| Package it hooks | `anthropic` | `claude-agent-sdk` |
+| Who writes the agent loop | the customer | Anthropic |
+| What we hook | `client.messages.create` | the `query()` message stream |
+
+Use `chatsee-anthropic` when they call the Messages API and run their own
+tool-use loop. Use this when they call `query()` and let the SDK run it.
+
+## Why a handle rather than a one-liner
+
+There is no client object to patch — the entry point is a module-level
+`query()`. So `instrument_claude_agent_sdk` returns a handle whose `.query` is
+a drop-in: every message still reaches the caller, unchanged and in order,
+while the turn is assembled alongside.
+
+`claude_agent_sdk.query` is replaced too, so code calling it **through the
+module** needs no change. Code that did `from claude_agent_sdk import query`
+already holds its own reference to the original and cannot be reached that way
+— that code uses the handle.
+
+## What it captures
+
+Per turn: the prompt, the final answer, the system prompt, every tool call with
+its arguments and result, and **one model call per model**, with tokens, cached
+tokens and a real dollar cost.
+
+This SDK is the only one that states its own cost (`total_cost_usd`), so that
+figure is passed through rather than estimated. Nothing here invents a price,
+and a turn's cost is never divided across models — a split we made up would
+look like measurement.
+
+## Three things this framework does that nothing else does
+
+**The CLI's system prompt is enormous.** Claude Code injects roughly 21k cached
+tokens on every call, so a one-line "hello" costs around $0.027. Those land in
+`cache_read_input_tokens`, not `input_tokens` — both are captured, or the turn
+looks far cheaper than the bill.
+
+**The CLI calls its own tools.** It loads tools on demand and emits a
+`ToolSearch` tool-use alongside the agent's real one. Those are filtered: a
+support agent that never touched a search tool must not show one in its trace.
+
+**Tool names arrive MCP-qualified.** Custom tools reach the model as
+`mcp__<server>__<tool>`. The customer named it `get_order_status`, so the
+prefix is stripped and that is what the screens say.
+
+## Guarantees
+
+* **Fails open.** A failure inside capture is logged and swallowed.
+* **Never consumes the stream.** Every message is forwarded unchanged, in order.
+* **Idempotent.** Instrumenting twice does not capture twice.
+* **Concurrency-safe.** State is per `query()` call, not per handle.
+
+All four are enforced by the contract suite, not just intended.
+
+## Tests
+
+No network, no API key, no CLI subprocess — the SDK is stubbed, ChatSee is not.
+That matters more here than anywhere else: a real turn costs about $0.027, so
+finding a capture bug by running one would be slow and expensive.
+
+```bash
+pip install -e python/connectors/_shared
+pip install -e python/connectors/ai_sdk/claude_agent_sdk
+pytest python/connectors/ai_sdk/claude_agent_sdk/tests -q
+```
+
+## Known gap
+
+Turn-level `duration_ms` comes from the tracker's own wall clock, and all four
+tracker calls are made together once the turn is known to be complete — so it
+reads near zero. The honest latency is on the model call, from the SDK's
+`duration_api_ms`. Fixing it properly means letting `end_turn` accept a
+measured duration, which is a core-SDK change and not this connector's to make.

chatsee_claude_agent_sdk-0.1.0/README.md

@@ -0,0 +1,97 @@
+# chatsee-claude-agent-sdk
+
+ChatSee connector for the **Claude Agent SDK** — Anthropic's agent framework,
+the one that powers Claude Code.
+
+```bash
+pip install chatsee-claude-agent-sdk
+```
+
+```python
+from chatsee_claude_agent_sdk import instrument_claude_agent_sdk
+
+chatsee = instrument_claude_agent_sdk(agent_id="...", tenant_id="...")
+
+async for message in chatsee.query(prompt="where is my order", options=opts):
+    ...
+```
+
+`chatsee-ai` is installed for you as a dependency.
+
+## Not the same thing as `chatsee-anthropic`
+
+| | `chatsee-anthropic` | this |
+| --- | --- | --- |
+| Package it hooks | `anthropic` | `claude-agent-sdk` |
+| Who writes the agent loop | the customer | Anthropic |
+| What we hook | `client.messages.create` | the `query()` message stream |
+
+Use `chatsee-anthropic` when they call the Messages API and run their own
+tool-use loop. Use this when they call `query()` and let the SDK run it.
+
+## Why a handle rather than a one-liner
+
+There is no client object to patch — the entry point is a module-level
+`query()`. So `instrument_claude_agent_sdk` returns a handle whose `.query` is
+a drop-in: every message still reaches the caller, unchanged and in order,
+while the turn is assembled alongside.
+
+`claude_agent_sdk.query` is replaced too, so code calling it **through the
+module** needs no change. Code that did `from claude_agent_sdk import query`
+already holds its own reference to the original and cannot be reached that way
+— that code uses the handle.
+
+## What it captures
+
+Per turn: the prompt, the final answer, the system prompt, every tool call with
+its arguments and result, and **one model call per model**, with tokens, cached
+tokens and a real dollar cost.
+
+This SDK is the only one that states its own cost (`total_cost_usd`), so that
+figure is passed through rather than estimated. Nothing here invents a price,
+and a turn's cost is never divided across models — a split we made up would
+look like measurement.
+
+## Three things this framework does that nothing else does
+
+**The CLI's system prompt is enormous.** Claude Code injects roughly 21k cached
+tokens on every call, so a one-line "hello" costs around $0.027. Those land in
+`cache_read_input_tokens`, not `input_tokens` — both are captured, or the turn
+looks far cheaper than the bill.
+
+**The CLI calls its own tools.** It loads tools on demand and emits a
+`ToolSearch` tool-use alongside the agent's real one. Those are filtered: a
+support agent that never touched a search tool must not show one in its trace.
+
+**Tool names arrive MCP-qualified.** Custom tools reach the model as
+`mcp__<server>__<tool>`. The customer named it `get_order_status`, so the
+prefix is stripped and that is what the screens say.
+
+## Guarantees
+
+* **Fails open.** A failure inside capture is logged and swallowed.
+* **Never consumes the stream.** Every message is forwarded unchanged, in order.
+* **Idempotent.** Instrumenting twice does not capture twice.
+* **Concurrency-safe.** State is per `query()` call, not per handle.
+
+All four are enforced by the contract suite, not just intended.
+
+## Tests
+
+No network, no API key, no CLI subprocess — the SDK is stubbed, ChatSee is not.
+That matters more here than anywhere else: a real turn costs about $0.027, so
+finding a capture bug by running one would be slow and expensive.
+
+```bash
+pip install -e python/connectors/_shared
+pip install -e python/connectors/ai_sdk/claude_agent_sdk
+pytest python/connectors/ai_sdk/claude_agent_sdk/tests -q
+```
+
+## Known gap
+
+Turn-level `duration_ms` comes from the tracker's own wall clock, and all four
+tracker calls are made together once the turn is known to be complete — so it
+reads near zero. The honest latency is on the model call, from the SDK's
+`duration_api_ms`. Fixing it properly means letting `end_turn` accept a
+measured duration, which is a core-SDK change and not this connector's to make.

chatsee_claude_agent_sdk-0.1.0/chatsee_claude_agent_sdk/__init__.py

@@ -0,0 +1,232 @@
+"""
+ChatSee connector for the Claude Agent SDK.
+
+    from chatsee_claude_agent_sdk import instrument_claude_agent_sdk
+
+    chatsee = instrument_claude_agent_sdk(agent_id="...", tenant_id="...")
+
+    async for message in chatsee.query(prompt="where is my order", options=opts):
+        ...
+
+Unlike the Messages API connector, there is no client object to patch — the
+Agent SDK's entry point is a module-level ``query()``. So this returns a handle
+whose ``.query`` is a drop-in for it: every message still reaches the caller,
+unchanged and in order, while the turn is assembled alongside and sent when the
+terminal ``ResultMessage`` arrives.
+
+``claude_agent_sdk.query`` is also replaced, so code that calls it through the
+module is captured without changing a line. Code that did
+``from claude_agent_sdk import query`` already holds its own reference to the
+original function and cannot be reached that way — use the handle.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator, Optional
+
+from ._capture import (
+    FRAMEWORK,
+    TurnAccumulator,
+    UsageLedger,
+    model_calls_from,
+    system_prompt_of,
+)
+
+__version__ = "0.1.0"
+__all__ = ["instrument_claude_agent_sdk", "ChatseeClaudeAgentSDK", "__version__"]
+
+logger = logging.getLogger(__name__)
+
+_MARKER = "_chatsee_instrumented"
+
+
+def _framework_version() -> str:
+    try:
+        import claude_agent_sdk
+
+        return getattr(claude_agent_sdk, "__version__", "unknown")
+    except Exception:
+        return "unknown"
+
+
+def _attr(obj: Any, name: str, default: Any = None) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _is_result(message: Any) -> bool:
+    """The terminal message, identified by shape rather than by import.
+
+    Importing ResultMessage would make the connector unimportable without the
+    SDK installed, which the offline tests rely on not being the case.
+    """
+    return type(message).__name__ == "ResultMessage" or (
+        _attr(message, "subtype") is not None and _attr(message, "total_cost_usd") is not None
+    )
+
+
+def _kind(message: Any) -> str:
+    return type(message).__name__
+
+
+class ChatseeClaudeAgentSDK:
+    """Handle returned by :func:`instrument_claude_agent_sdk`."""
+
+    def __init__(self, tracker: Any, query_fn: Any, user_id: Optional[str] = None) -> None:
+        self._tracker = tracker
+        self._query = query_fn
+        self._user_id = user_id
+        # Per-session running totals, so cumulative figures become per-turn.
+        self._ledger = UsageLedger()
+
+    # -- the drop-in -------------------------------------------------------
+
+    def query(self, *args: Any, **kwargs: Any) -> AsyncIterator[Any]:
+        """A drop-in for the SDK's ``query()``."""
+        return self._stream(*args, **kwargs)
+
+    async def _stream(self, *args: Any, **kwargs: Any) -> AsyncIterator[Any]:
+        prompt = kwargs.get("prompt")
+        if prompt is None and args:
+            prompt = args[0]
+        options = kwargs.get("options")
+
+        # One accumulator per call, never shared, so concurrent queries cannot
+        # contaminate each other.
+        turn = TurnAccumulator()
+
+        async for message in self._query(*args, **kwargs):
+            try:
+                kind = _kind(message)
+                if kind == "AssistantMessage":
+                    turn.observe_assistant(message)
+                elif kind == "UserMessage":
+                    turn.observe_user(message)
+                elif _is_result(message):
+                    self._emit(prompt, options, turn, message)
+            except Exception as exc:  # noqa: BLE001 - never break the agent
+                logger.error("chatsee-claude-agent-sdk capture failed: %s", exc,
+                             exc_info=True)
+            yield message              # forwarded unchanged, in order
+
+    # -- emitting ----------------------------------------------------------
+
+    def _metadata(self) -> dict:
+        return {
+            "framework": FRAMEWORK,
+            "framework_version": _framework_version(),
+            "connector_version": __version__,
+        }
+
+    def _emit(self, prompt: Any, options: Any, turn: TurnAccumulator,
+              result_message: Any) -> None:
+        """All four tracker calls, together, when the turn is known to be over.
+
+        Emitted in one go rather than opening the turn when the stream starts:
+        the tracker holds a single turn at a time, so a start_turn left open
+        across an await would be clobbered by any concurrent query.
+        """
+        tracker = self._tracker
+        answer = _attr(result_message, "result") or ""
+
+        tracker.start_turn(
+            prompt if isinstance(prompt, str) else "",
+            metadata=self._metadata(),
+            system_prompt=system_prompt_of(options),
+            user_id=self._user_id,
+        )
+
+        for call in turn.resolved_tool_calls():
+            tracker.log_tool_call(call["tool_name"], call["arguments"],
+                                  result=call["result"])
+
+        # One entry per model the turn used. The SDK states a real dollar cost,
+        # so it is passed through rather than estimated -- nothing here invents
+        # a price. duration_api_ms is the time actually spent in the API, which
+        # is the honest per-call latency.
+        api_ms = _attr(result_message, "duration_api_ms")
+        session_id = _attr(result_message, "session_id")
+        calls, cumulative = model_calls_from(result_message)
+
+        # model_usage and total_cost_usd are running totals for the query()
+        # call, not this turn's share. One turn per call makes them the same
+        # number, which is why it never shows in the ordinary case; a
+        # streaming-input or resumed session runs several turns through one
+        # total, and recording it raw makes turn three report turns one, two
+        # and three.
+        if cumulative:
+            calls = self._ledger.per_turn_models(session_id, calls)
+            total_cost = None          # already carried per model
+        else:
+            # The aggregate usage is per-turn, but the cost beside it is not.
+            total_cost = self._ledger.per_turn_cost(
+                session_id, _attr(result_message, "total_cost_usd"))
+
+        for entry in calls:
+            tracker.log_model_call(
+                model=entry.get("model") or turn.model,
+                provider="anthropic",
+                prompt_tokens=entry.get("prompt_tokens"),
+                completion_tokens=entry.get("completion_tokens"),
+                cached_tokens=entry.get("cached_tokens"),
+                # A per-model cost when the SDK broke it down, otherwise the
+                # turn's cost on the single entry. Never divided up: a split
+                # we invented would look like measurement.
+                cost_usd=entry.get("cost_usd") if entry.get("cost_usd") is not None
+                else (total_cost if len(calls) == 1 else None),
+                duration_ms=api_ms if len(calls) == 1 else None,
+            )
+
+        if _attr(result_message, "is_error"):
+            tracker.log_exception(
+                "claude-agent-sdk reported subtype=%s" % _attr(result_message, "subtype")
+            )
+
+        tracker.end_turn(answer)
+
+
+def instrument_claude_agent_sdk(
+    agent_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    api_base_url: Optional[str] = None,
+    _tracker: Any = None,
+    _query: Any = None,
+) -> ChatseeClaudeAgentSDK:
+    """Capture every turn the Claude Agent SDK runs.
+
+    ``_tracker`` and ``_query`` are private and exist so the contract tests can
+    inject a fake tracker and a stub SDK. Customers never pass them.
+    """
+    if _tracker is None:
+        from chatsee import ChatseeTracker
+
+        if not agent_id or not tenant_id:
+            raise ValueError("agent_id and tenant_id are required.")
+        _tracker = ChatseeTracker(
+            agent_id=agent_id,
+            tenant_id=tenant_id,
+            user_id=user_id,
+            session_id=session_id,
+            api_base_url=api_base_url,
+        )
+
+    module = None
+    if _query is None:
+        import claude_agent_sdk as module
+
+        _query = getattr(module, _MARKER + "_original", None) or module.query
+
+    handle = ChatseeClaudeAgentSDK(_tracker, _query, user_id)
+
+    # Also replace the module-level query, so callers using
+    # `claude_agent_sdk.query(...)` need no change at all. Guarded, because
+    # instrumenting twice must not wrap twice.
+    if module is not None and not getattr(module, _MARKER, False):
+        setattr(module, _MARKER + "_original", _query)
+        module.query = handle.query
+        setattr(module, _MARKER, True)
+
+    return handle