ams-observability 0.1.0__py3-none-any.whl

ams/__init__.py

@@ -0,0 +1,38 @@
+"""AMS — a super simple monitoring system for Claude agents.
+
+Capture a whole Claude Agent SDK session end to end — every tool call, every
+subagent and why it was invoked, the model's reasoning, results, timing and
+cost — as one readable JSON object in blob storage.
+
+    from ams.claude import traced_query
+
+    async for message in traced_query(prompt="...", options=options):
+        ...
+"""
+
+from .schema import (
+    SCHEMA_VERSION,
+    Agent,
+    Event,
+    EventType,
+    Session,
+    Status,
+    Totals,
+    Usage,
+)
+from .tracer import Tracer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Tracer",
+    "Session",
+    "Event",
+    "EventType",
+    "Status",
+    "Totals",
+    "Usage",
+    "Agent",
+    "SCHEMA_VERSION",
+    "__version__",
+]

ams/claude.py

@@ -0,0 +1,46 @@
+"""Glue between AMS and `claude_agent_sdk`. This is the whole integration
+surface: swap `query` for `traced_query`, or merge `tracer.hooks()` into your
+options if you drive a ClaudeSDKClient yourself."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Optional
+
+from .tracer import Tracer
+
+
+def instrument_options(options: Any, tracer: Tracer) -> Any:
+    """Merge AMS hooks into an existing ClaudeAgentOptions, keeping any of yours."""
+    merged = dict(getattr(options, "hooks", None) or {})
+    for name, matchers in tracer.hooks().items():
+        merged[name] = list(merged.get(name, [])) + list(matchers)
+    options.hooks = merged
+    return options
+
+
+async def traced_query(
+    *,
+    prompt: Any,
+    options: Any = None,
+    tracer: Optional[Tracer] = None,
+    **tracer_kwargs: Any,
+) -> AsyncIterator[Any]:
+    """Drop-in replacement for `claude_agent_sdk.query` that records the session.
+
+        from ams.claude import traced_query
+
+        async for message in traced_query(prompt="...", options=options):
+            print(message)
+
+    Extra keyword args (storage, agent, environment, tags, metadata, redact)
+    are forwarded to `Tracer`. On stream completion the session is written to
+    storage automatically.
+    """
+    from claude_agent_sdk import ClaudeAgentOptions, query
+
+    tracer = tracer or Tracer(**tracer_kwargs)
+    options = options or ClaudeAgentOptions()
+    options = instrument_options(options, tracer)
+
+    async for message in tracer.watch(query(prompt=prompt, options=options)):
+        yield message

ams/pricing.py

@@ -0,0 +1,45 @@
+"""Token -> USD cost. The Claude Agent SDK already reports `total_cost_usd` on
+the result message, so AMS uses that for the session total. This table is a
+fallback for costing an individual LLM call from its token usage.
+
+Prices are USD per million tokens. Update as needed; matching is by substring so
+dated model ids (e.g. `claude-opus-4-8-20260101`) resolve to the right family.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .schema import Usage
+
+# (input, output, cache_write, cache_read) per million tokens
+_PRICES: dict[str, tuple[float, float, float, float]] = {
+    "claude-opus-4": (15.0, 75.0, 18.75, 1.5),
+    "claude-sonnet-4": (3.0, 15.0, 3.75, 0.3),
+    "claude-haiku-4": (1.0, 5.0, 1.25, 0.1),
+    "claude-3-5-haiku": (0.8, 4.0, 1.0, 0.08),
+}
+
+
+def _match(model: str) -> Optional[tuple[float, float, float, float]]:
+    model = model.lower()
+    for key, price in _PRICES.items():
+        if key in model:
+            return price
+    return None
+
+
+def cost_usd(model: Optional[str], usage: Optional[Usage]) -> Optional[float]:
+    if not model or usage is None:
+        return None
+    price = _match(model)
+    if price is None:
+        return None
+    p_in, p_out, p_cw, p_cr = price
+    total = (
+        usage.input_tokens * p_in
+        + usage.output_tokens * p_out
+        + usage.cache_creation_input_tokens * p_cw
+        + usage.cache_read_input_tokens * p_cr
+    )
+    return round(total / 1_000_000, 6)

ams/redact.py

@@ -0,0 +1,31 @@
+"""Optional PII redaction. Off by default — AMS captures full detail unless you
+opt in. Turn it on with `Tracer(redact=True)` or `AMS_REDACT=1` when sessions
+may contain sensitive caller data (phone numbers, emails, cards)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_PATTERNS = [
+    (re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"), "[email]"),
+    (re.compile(r"\+?\d[\d\s().-]{7,}\d"), "[phone]"),
+    (re.compile(r"\b(?:\d[ -]*?){13,16}\b"), "[card]"),
+    (re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), "[ssn]"),
+]
+
+
+def redact_text(text: str) -> str:
+    for pattern, replacement in _PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def redact(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, dict):
+        return {k: redact(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [redact(v) for v in value]
+    return value

ams/schema.py

@@ -0,0 +1,168 @@
+"""The AMS session schema. This file is the data contract.
+
+One session = one JSON object. The shape is deliberately flat and typed so a
+session is easy to read by a human and easy to filter by a machine. Field names
+are aligned with the OpenTelemetry GenAI semantic conventions (`gen_ai.*`) where
+a natural equivalent exists, so the data can later be re-emitted as OTLP without
+renaming. See docs/schema.md.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+SCHEMA_VERSION = "1.0"
+
+
+class EventType(str, Enum):
+    USER_PROMPT = "user_prompt"
+    LLM_MESSAGE = "llm_message"
+    TOOL_CALL = "tool_call"
+    SUBAGENT = "subagent"
+    NOTIFICATION = "notification"
+    COMPACTION = "compaction"
+    ERROR = "error"
+
+
+class Status(str, Enum):
+    OK = "ok"
+    ERROR = "error"
+    RUNNING = "running"
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+
+    def add(self, other: "Usage") -> "Usage":
+        return Usage(
+            input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+            cache_read_input_tokens=self.cache_read_input_tokens
+            + other.cache_read_input_tokens,
+            cache_creation_input_tokens=self.cache_creation_input_tokens
+            + other.cache_creation_input_tokens,
+        )
+
+    @classmethod
+    def from_sdk(cls, usage: Optional[dict[str, Any]]) -> "Usage":
+        usage = usage or {}
+        return cls(
+            input_tokens=usage.get("input_tokens", 0) or 0,
+            output_tokens=usage.get("output_tokens", 0) or 0,
+            cache_read_input_tokens=usage.get("cache_read_input_tokens", 0) or 0,
+            cache_creation_input_tokens=usage.get("cache_creation_input_tokens", 0) or 0,
+        )
+
+
+class LLMDetail(BaseModel):
+    model: Optional[str] = None
+    stop_reason: Optional[str] = None
+    text: Optional[str] = None
+    thinking: Optional[str] = None
+    message_id: Optional[str] = None
+    usage: Optional[Usage] = None
+
+
+class ToolDetail(BaseModel):
+    name: str
+    tool_use_id: Optional[str] = None
+    input: Any = None
+    result: Any = None
+    is_error: bool = False
+
+
+class SubagentDetail(BaseModel):
+    agent_id: str
+    agent_type: Optional[str] = None
+    transcript_path: Optional[str] = None
+    invocation_prompt: Optional[str] = None
+    invocation_event_id: Optional[str] = None
+    usage: Optional[Usage] = None
+
+
+class ErrorDetail(BaseModel):
+    type: Optional[str] = None
+    message: Optional[str] = None
+
+
+class Event(BaseModel):
+    id: str
+    seq: int
+    parent_id: Optional[str] = None
+    type: EventType
+    name: str
+    start_time: str
+    end_time: Optional[str] = None
+    duration_ms: Optional[int] = None
+    status: Status = Status.OK
+
+    prompt: Optional[str] = None
+    llm: Optional[LLMDetail] = None
+    tool: Optional[ToolDetail] = None
+    subagent: Optional[SubagentDetail] = None
+    error: Optional[ErrorDetail] = None
+    note: Optional[str] = None
+
+
+class Totals(BaseModel):
+    usage: Usage = Field(default_factory=Usage)
+    cost_usd: Optional[float] = None
+    llm_calls: int = 0
+    tool_calls: int = 0
+    subagents: int = 0
+    errors: int = 0
+    num_turns: Optional[int] = None
+    duration_ms: Optional[int] = None
+    duration_api_ms: Optional[int] = None
+
+
+class Agent(BaseModel):
+    name: Optional[str] = None
+    version: Optional[str] = None
+
+
+class Session(BaseModel):
+    schema_version: str = SCHEMA_VERSION
+    session_id: str
+    trace_id: str
+    agent: Agent = Field(default_factory=Agent)
+    environment: Optional[str] = None
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    start_time: str
+    end_time: Optional[str] = None
+    duration_ms: Optional[int] = None
+    status: Status = Status.OK
+
+    totals: Totals = Field(default_factory=Totals)
+    events: list[Event] = Field(default_factory=list)
+
+    def summary(self) -> dict[str, Any]:
+        """A compact, filterable record for a sessions index — no payloads."""
+        return {
+            "schema_version": self.schema_version,
+            "session_id": self.session_id,
+            "trace_id": self.trace_id,
+            "agent": self.agent.model_dump(exclude_none=True),
+            "environment": self.environment,
+            "tags": self.tags,
+            "metadata": self.metadata,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration_ms": self.duration_ms,
+            "status": self.status.value,
+            "input_tokens": self.totals.usage.input_tokens,
+            "output_tokens": self.totals.usage.output_tokens,
+            "cost_usd": self.totals.cost_usd,
+            "llm_calls": self.totals.llm_calls,
+            "tool_calls": self.totals.tool_calls,
+            "subagents": self.totals.subagents,
+            "errors": self.totals.errors,
+        }

ams/storage/__init__.py

@@ -0,0 +1,30 @@
+"""Pluggable storage. A backend just needs to accept a finished Session."""
+
+from __future__ import annotations
+
+import os
+from typing import Protocol, runtime_checkable
+
+from ..schema import Session
+from .local import LocalStorage
+from .s3 import S3Storage
+
+
+@runtime_checkable
+class Storage(Protocol):
+    def put_session(self, session: Session) -> str: ...
+
+
+def from_env() -> Storage:
+    """Pick a backend from the environment.
+
+    Defaults to S3-compatible blob storage. Set `AMS_STORAGE=local` (or leave
+    `AMS_S3_BUCKET` unset) to write JSON to a local directory instead.
+    """
+    backend = os.environ.get("AMS_STORAGE", "").lower()
+    if backend == "local" or (not backend and not os.environ.get("AMS_S3_BUCKET")):
+        return LocalStorage.from_env()
+    return S3Storage.from_env()
+
+
+__all__ = ["Storage", "S3Storage", "LocalStorage", "from_env"]

ams/storage/local.py

@@ -0,0 +1,35 @@
+"""Local-disk storage. Mirrors the S3 layout under a directory so the same
+frontend code can read either. Useful for development and demos."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from ..schema import Session
+
+
+class LocalStorage:
+    def __init__(self, root: str = "./ams-data"):
+        self.root = Path(root)
+
+    @classmethod
+    def from_env(cls) -> "LocalStorage":
+        return cls(root=os.environ.get("AMS_LOCAL_DIR", "./ams-data"))
+
+    def put_session(self, session: Session) -> str:
+        date = session.start_time[:10].replace("-", "/")
+        session_path = (
+            self.root / "sessions" / date / f"{session.session_id}.json"
+        )
+        index_path = self.root / "index" / f"{session.session_id}.json"
+        session_path.parent.mkdir(parents=True, exist_ok=True)
+        index_path.parent.mkdir(parents=True, exist_ok=True)
+        session_path.write_text(
+            session.model_dump_json(exclude_none=True, indent=2), encoding="utf-8"
+        )
+        index_path.write_text(
+            json.dumps(session.summary(), indent=2), encoding="utf-8"
+        )
+        return str(session_path)

ams/storage/s3.py

@@ -0,0 +1,78 @@
+"""S3-compatible storage. Works against AWS S3, Cloudflare R2, MinIO, etc. —
+anything that speaks the S3 API. Point `AMS_S3_ENDPOINT_URL` at your provider.
+
+Layout under the bucket:
+    {prefix}/sessions/{YYYY}/{MM}/{DD}/{session_id}.json   full session
+    {prefix}/index/{session_id}.json                        compact summary
+
+The frontend lists the small `index/` objects to build a searchable session
+list, then fetches a full session on demand.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from ..schema import Session
+
+
+class S3Storage:
+    def __init__(
+        self,
+        bucket: str,
+        prefix: str = "ams",
+        endpoint_url: Optional[str] = None,
+        region_name: Optional[str] = None,
+        client=None,
+    ):
+        self.bucket = bucket
+        self.prefix = prefix.strip("/")
+        if client is not None:
+            self._client = client
+        else:
+            import boto3  # imported lazily so `ams` stays importable without it
+
+            self._client = boto3.client(
+                "s3", endpoint_url=endpoint_url, region_name=region_name
+            )
+
+    @classmethod
+    def from_env(cls) -> "S3Storage":
+        bucket = os.environ.get("AMS_S3_BUCKET")
+        if not bucket:
+            raise RuntimeError(
+                "AMS_S3_BUCKET is not set. Set it (and optionally "
+                "AMS_S3_ENDPOINT_URL / AMS_S3_PREFIX / AMS_S3_REGION) or use "
+                "LocalStorage."
+            )
+        return cls(
+            bucket=bucket,
+            prefix=os.environ.get("AMS_S3_PREFIX", "ams"),
+            endpoint_url=os.environ.get("AMS_S3_ENDPOINT_URL"),
+            region_name=os.environ.get("AMS_S3_REGION")
+            or os.environ.get("AWS_REGION"),
+        )
+
+    def _session_key(self, session: Session) -> str:
+        date = session.start_time[:10].replace("-", "/")
+        return f"{self.prefix}/sessions/{date}/{session.session_id}.json"
+
+    def _index_key(self, session: Session) -> str:
+        return f"{self.prefix}/index/{session.session_id}.json"
+
+    def put_session(self, session: Session) -> str:
+        body = session.model_dump_json(exclude_none=True, indent=2)
+        session_key = self._session_key(session)
+        self._put(session_key, body)
+        self._put(self._index_key(session), json.dumps(session.summary(), indent=2))
+        return f"s3://{self.bucket}/{session_key}"
+
+    def _put(self, key: str, body: str) -> None:
+        self._client.put_object(
+            Bucket=self.bucket,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )

ams/tracer.py

@@ -0,0 +1,399 @@
+"""Tracer records one Claude Agent SDK session into one Session object.
+
+It gets its data from two places, because no single source has all of it:
+
+  * Hooks (PreToolUse / PostToolUse / SubagentStart / ... ) give every tool
+    call, every subagent invocation, prompts, and their timing.
+  * The message stream (AssistantMessage / ResultMessage) gives the model's
+    reasoning (thinking blocks), assistant text, token usage and cost.
+
+A Tracer instance is one session. Create a fresh one per run (or per
+ClaudeSDKClient). See claude.py for the one-call `traced_query` wrapper.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, AsyncIterator, Optional
+
+from . import pricing
+from .redact import redact as _redact
+from .schema import (
+    Agent,
+    ErrorDetail,
+    Event,
+    EventType,
+    LLMDetail,
+    Session,
+    Status,
+    SubagentDetail,
+    ToolDetail,
+    Totals,
+    Usage,
+)
+
+logger = logging.getLogger("ams")
+
+_SUBAGENT_TOOLS = {"Task", "Agent"}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _attr(obj: Any, name: str, default: Any = None) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+class Tracer:
+    def __init__(
+        self,
+        storage=None,
+        *,
+        agent: Optional[Agent] = None,
+        environment: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        redact: Optional[bool] = None,
+        capture_thinking: bool = True,
+    ):
+        self._storage = storage
+        self.agent = agent or Agent()
+        self.environment = environment
+        self.tags = tags or []
+        self.metadata = metadata or {}
+        if redact is None:
+            import os
+
+            redact = os.environ.get("AMS_REDACT", "").lower() in ("1", "true", "yes")
+        self.redact = redact
+        self.capture_thinking = capture_thinking
+
+        self.trace_id = uuid.uuid4().hex
+        self.session_id: Optional[str] = None
+        self.start_time = _now_iso()
+        self._t0 = time.monotonic()
+
+        self._events: list[Event] = []
+        self._seq = 0
+        self._open_tools: dict[str, tuple[Event, float]] = {}
+        self._open_subagents: dict[str, Event] = {}
+        self._pending_invocations: list[Event] = []
+        self._result: Optional[Any] = None
+        self._finished: Optional[Session] = None
+
+    @property
+    def storage(self):
+        if self._storage is None:
+            from .storage import from_env
+
+            self._storage = from_env()
+        return self._storage
+
+    # ---- helpers -----------------------------------------------------------
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    def _clean(self, value: Any) -> Any:
+        return _redact(value) if self.redact else value
+
+    def _see_session_id(self, obj: Any) -> None:
+        if self.session_id is None:
+            sid = _attr(obj, "session_id")
+            if sid:
+                self.session_id = sid
+
+    # ---- hooks -------------------------------------------------------------
+
+    def hooks(self) -> dict[str, list[Any]]:
+        """Hook config to merge into ClaudeAgentOptions(hooks=...).
+
+        Captures tool calls, subagents and prompts. Pair with `watch()` (or
+        feed messages to `record_message`) to also capture reasoning and cost.
+        """
+        from claude_agent_sdk import HookMatcher
+
+        events = [
+            "PreToolUse",
+            "PostToolUse",
+            "PostToolUseFailure",
+            "SubagentStart",
+            "SubagentStop",
+            "UserPromptSubmit",
+            "Notification",
+        ]
+        return {name: [HookMatcher(hooks=[self._hook])] for name in events}
+
+    async def _hook(self, hook_input: Any, tool_use_id: Optional[str], context: Any):
+        try:
+            self._see_session_id(hook_input)
+            name = _attr(hook_input, "hook_event_name")
+            handler = {
+                "PreToolUse": self._on_pre_tool,
+                "PostToolUse": self._on_post_tool,
+                "PostToolUseFailure": self._on_tool_failure,
+                "SubagentStart": self._on_subagent_start,
+                "SubagentStop": self._on_subagent_stop,
+                "UserPromptSubmit": self._on_user_prompt,
+                "Notification": self._on_notification,
+            }.get(name)
+            if handler:
+                handler(hook_input)
+        except Exception:  # never let monitoring break the agent
+            logger.exception("ams: hook recording failed")
+        return {}
+
+    def _on_pre_tool(self, hi: Any) -> None:
+        tool_name = _attr(hi, "tool_name", "")
+        tool_use_id = _attr(hi, "tool_use_id")
+        agent_id = _attr(hi, "agent_id")
+        parent = self._open_subagents.get(agent_id) if agent_id else None
+        event = Event(
+            id=uuid.uuid4().hex,
+            seq=self._next_seq(),
+            parent_id=parent.id if parent else None,
+            type=EventType.TOOL_CALL,
+            name=f"tool:{tool_name}",
+            start_time=_now_iso(),
+            status=Status.RUNNING,
+            tool=ToolDetail(
+                name=tool_name,
+                tool_use_id=tool_use_id,
+                input=self._clean(_attr(hi, "tool_input")),
+            ),
+        )
+        if tool_name in _SUBAGENT_TOOLS:
+            ti = _attr(hi, "tool_input") or {}
+            event.note = "subagent invocation"
+            event.tool.input = self._clean(ti)
+            self._pending_invocations.append(event)
+        if tool_use_id:
+            self._open_tools[tool_use_id] = (event, time.monotonic())
+        self._events.append(event)
+
+    def _close_tool(self, hi: Any) -> Optional[tuple[Event, float]]:
+        tool_use_id = _attr(hi, "tool_use_id")
+        return self._open_tools.pop(tool_use_id, None) if tool_use_id else None
+
+    def _on_post_tool(self, hi: Any) -> None:
+        found = self._close_tool(hi)
+        if not found:
+            return
+        event, t0 = found
+        event.end_time = _now_iso()
+        event.duration_ms = int((time.monotonic() - t0) * 1000)
+        event.status = Status.OK
+        if event.tool:
+            event.tool.result = self._clean(_attr(hi, "tool_response"))
+
+    def _on_tool_failure(self, hi: Any) -> None:
+        found = self._close_tool(hi)
+        if not found:
+            return
+        event, t0 = found
+        event.end_time = _now_iso()
+        event.duration_ms = int((time.monotonic() - t0) * 1000)
+        event.status = Status.ERROR
+        if event.tool:
+            event.tool.is_error = True
+        event.error = ErrorDetail(type="tool_error", message=_attr(hi, "error"))
+
+    def _on_subagent_start(self, hi: Any) -> None:
+        agent_id = _attr(hi, "agent_id")
+        agent_type = _attr(hi, "agent_type")
+        invocation = self._pop_invocation(agent_type)
+        detail = SubagentDetail(agent_id=agent_id, agent_type=agent_type)
+        if invocation:
+            detail.invocation_event_id = invocation.id
+            ti = invocation.tool.input if invocation.tool else None
+            if isinstance(ti, dict):
+                detail.invocation_prompt = ti.get("prompt") or ti.get("description")
+        event = Event(
+            id=uuid.uuid4().hex,
+            seq=self._next_seq(),
+            type=EventType.SUBAGENT,
+            name=f"subagent:{agent_type or 'agent'}",
+            start_time=_now_iso(),
+            status=Status.RUNNING,
+            subagent=detail,
+        )
+        if agent_id:
+            self._open_subagents[agent_id] = event
+        self._events.append(event)
+
+    def _pop_invocation(self, agent_type: Optional[str]) -> Optional[Event]:
+        for i, ev in enumerate(self._pending_invocations):
+            ti = ev.tool.input if ev.tool else None
+            if isinstance(ti, dict) and ti.get("subagent_type") == agent_type:
+                return self._pending_invocations.pop(i)
+        return self._pending_invocations.pop(0) if self._pending_invocations else None
+
+    def _on_subagent_stop(self, hi: Any) -> None:
+        agent_id = _attr(hi, "agent_id")
+        event = self._open_subagents.pop(agent_id, None) if agent_id else None
+        if not event or not event.subagent:
+            return
+        event.end_time = _now_iso()
+        if event.start_time and event.end_time:
+            event.status = Status.OK
+        event.subagent.transcript_path = _attr(hi, "agent_transcript_path")
+
+    def _on_user_prompt(self, hi: Any) -> None:
+        ts = _now_iso()
+        self._events.append(
+            Event(
+                id=uuid.uuid4().hex,
+                seq=self._next_seq(),
+                type=EventType.USER_PROMPT,
+                name="user_prompt",
+                start_time=ts,
+                end_time=ts,
+                prompt=self._clean(_attr(hi, "prompt")),
+            )
+        )
+
+    def _on_notification(self, hi: Any) -> None:
+        ts = _now_iso()
+        self._events.append(
+            Event(
+                id=uuid.uuid4().hex,
+                seq=self._next_seq(),
+                type=EventType.NOTIFICATION,
+                name="notification",
+                start_time=ts,
+                end_time=ts,
+                note=_attr(hi, "message"),
+            )
+        )
+
+    # ---- message stream ----------------------------------------------------
+
+    def record_message(self, msg: Any) -> None:
+        try:
+            self._see_session_id(msg)
+            kind = type(msg).__name__
+            if kind == "AssistantMessage":
+                self._on_assistant(msg)
+            elif kind == "ResultMessage":
+                self._result = msg
+        except Exception:
+            logger.exception("ams: message recording failed")
+
+    def _on_assistant(self, msg: Any) -> None:
+        text_parts: list[str] = []
+        thinking_parts: list[str] = []
+        for block in _attr(msg, "content", []) or []:
+            block_kind = type(block).__name__
+            if block_kind == "TextBlock":
+                text_parts.append(_attr(block, "text", "") or "")
+            elif block_kind == "ThinkingBlock" and self.capture_thinking:
+                thinking_parts.append(_attr(block, "thinking", "") or "")
+        text = "\n".join(p for p in text_parts if p) or None
+        thinking = "\n".join(p for p in thinking_parts if p) or None
+        if text is None and thinking is None and _attr(msg, "usage") is None:
+            return
+        usage = Usage.from_sdk(_attr(msg, "usage"))
+        ts = _now_iso()
+        self._events.append(
+            Event(
+                id=uuid.uuid4().hex,
+                seq=self._next_seq(),
+                type=EventType.LLM_MESSAGE,
+                name="assistant",
+                start_time=ts,
+                end_time=ts,
+                llm=LLMDetail(
+                    model=_attr(msg, "model"),
+                    stop_reason=_attr(msg, "stop_reason"),
+                    text=self._clean(text) if text else None,
+                    thinking=self._clean(thinking) if thinking else None,
+                    message_id=_attr(msg, "message_id"),
+                    usage=usage,
+                ),
+            )
+        )
+
+    async def watch(self, stream: AsyncIterator[Any]) -> AsyncIterator[Any]:
+        """Pass messages through unchanged while recording them; finalize at end."""
+        try:
+            async for msg in stream:
+                self.record_message(msg)
+                yield msg
+        finally:
+            self.finish()
+
+    # ---- finalize ----------------------------------------------------------
+
+    def finish(self, status: Optional[Status] = None) -> Session:
+        if self._finished is not None:
+            return self._finished
+
+        events = sorted(self._events, key=lambda e: e.seq)
+        totals = self._compute_totals(events)
+        wall_ms = int((time.monotonic() - self._t0) * 1000)
+        if status is None:
+            errored = any(e.status == Status.ERROR for e in events)
+            if self._result is not None and _attr(self._result, "is_error"):
+                errored = True
+            status = Status.ERROR if errored else Status.OK
+
+        session = Session(
+            session_id=self.session_id or self.trace_id,
+            trace_id=self.trace_id,
+            agent=self.agent,
+            environment=self.environment,
+            tags=self.tags,
+            metadata=self.metadata,
+            start_time=self.start_time,
+            end_time=_now_iso(),
+            duration_ms=totals.duration_ms or wall_ms,
+            status=status,
+            totals=totals,
+            events=events,
+        )
+        self._finished = session
+        try:
+            location = self.storage.put_session(session)
+            logger.info("ams: wrote session %s -> %s", session.session_id, location)
+        except Exception:
+            logger.exception("ams: failed to persist session %s", session.session_id)
+        return session
+
+    def _compute_totals(self, events: list[Event]) -> Totals:
+        totals = Totals()
+        summed = Usage()
+        fallback_cost = 0.0
+        have_cost = False
+        for e in events:
+            if e.type == EventType.TOOL_CALL:
+                totals.tool_calls += 1
+            elif e.type == EventType.SUBAGENT:
+                totals.subagents += 1
+            elif e.type == EventType.LLM_MESSAGE and e.llm:
+                totals.llm_calls += 1
+                if e.llm.usage:
+                    summed = summed.add(e.llm.usage)
+                    c = pricing.cost_usd(e.llm.model, e.llm.usage)
+                    if c is not None:
+                        fallback_cost += c
+                        have_cost = True
+            if e.status == Status.ERROR:
+                totals.errors += 1
+
+        if self._result is not None:
+            totals.usage = Usage.from_sdk(_attr(self._result, "usage"))
+            totals.cost_usd = _attr(self._result, "total_cost_usd")
+            totals.num_turns = _attr(self._result, "num_turns")
+            totals.duration_ms = _attr(self._result, "duration_ms")
+            totals.duration_api_ms = _attr(self._result, "duration_api_ms")
+        else:
+            totals.usage = summed
+            totals.cost_usd = round(fallback_cost, 6) if have_cost else None
+        return totals

ams_observability-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: ams-observability
+Version: 0.1.0
+Summary: A super simple monitoring system for Claude agents — full session traces as JSON in blob storage.
+Project-URL: Homepage, https://github.com/mathu97/ams
+Project-URL: Repository, https://github.com/mathu97/ams
+Author: mathu97
+License: MIT
+License-File: LICENSE
+Keywords: agents,claude,llm,monitoring,observability,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.28
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AMS — Agent Monitoring System
+
+A **super simple** monitoring system for [Claude agents](https://docs.claude.com/en/api/agent-sdk/overview). Capture a whole Claude Agent SDK session end to end — every tool call, every subagent and *why* it was invoked, the model's reasoning, results, timing, and cost — as **one readable JSON object** in blob storage.
+
+No collector, no database, no agent. One JSON file per session in S3-compatible storage. Built to be trivially easy to read and filter (the things that make Arize and friends painful).
+
+```python
+from ams.claude import traced_query
+
+async for message in traced_query(prompt="Cancel my membership", options=options):
+    ...
+# session written to storage automatically when the stream ends
+```
+
+That's the whole integration. Swap `query` for `traced_query`.
+
+## Why
+
+We monitor our Claude agents with Arize today, but it's hard to read, and hard to search/filter for a single session. AMS keeps the data model deliberately flat and typed so a session is obvious to a human and easy to query by a machine. Field names follow the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (`gen_ai.*`) where there's a natural equivalent, so the data can later be re-emitted as OTLP without renaming.
+
+## What it captures
+
+A session is one trace of ordered **events**:
+
+| Event | Source | Detail captured |
+|---|---|---|
+| `user_prompt` | `UserPromptSubmit` hook | the prompt |
+| `llm_message` | message stream | model, **thinking / chain-of-thought**, assistant text, token usage |
+| `tool_call` | `PreToolUse` + `PostToolUse` / `PostToolUseFailure` hooks | tool name, input, result, error, **timing** |
+| `subagent` | `SubagentStart` / `SubagentStop` hooks | agent type, **why it was invoked** (the prompt), transcript path; child tool calls nest underneath |
+| `notification` | `Notification` hook | message |
+
+Plus session **totals**: token usage (incl. cache read/write), cost (USD), turn count, tool/subagent/error counts, and wall-clock + API duration.
+
+The Claude Agent SDK has **no built-in OpenTelemetry** — AMS captures everything through hooks and the message stream, which together are the only place this data lives.
+
+## Install
+
+```bash
+pip install ams-observability     # published name; you import it as `ams`
+```
+
+Or from a local checkout: `pip install -e .`. S3-compatible storage (boto3) is included by default.
+
+Requires Python 3.10+ and the [`claude-agent-sdk`](https://pypi.org/project/claude-agent-sdk/) in your project.
+
+## Configure storage
+
+S3-compatible storage is the default. Works against **AWS S3, Cloudflare R2, MinIO** — anything speaking the S3 API.
+
+```bash
+export AMS_S3_BUCKET=my-agent-traces
+export AMS_S3_PREFIX=ams                 # optional, default "ams"
+export AMS_S3_ENDPOINT_URL=https://<account>.r2.cloudflarestorage.com   # omit for AWS S3
+export AMS_S3_REGION=auto
+# credentials via the standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
+```
+
+Or write to local disk for development:
+
+```bash
+export AMS_STORAGE=local
+export AMS_LOCAL_DIR=./ams-data          # optional
+```
+
+### Layout in the bucket
+
+```
+{prefix}/sessions/{YYYY}/{MM}/{DD}/{session_id}.json   full session
+{prefix}/index/{session_id}.json                        compact summary (for listing/filtering)
+```
+
+The small `index/` objects let a frontend build a searchable session list without opening every full session.
+
+## Usage
+
+### One-call (drop-in for `query`)
+
+```python
+from ams import Agent
+from ams.claude import traced_query
+
+async for message in traced_query(
+    prompt="...",
+    options=options,                       # your ClaudeAgentOptions
+    agent=Agent(name="support-bot", version="2026.06"),
+    environment="prod",
+    tags=["voice", "cancellation"],
+    metadata={"team_id": "t_42"},
+):
+    print(message)
+```
+
+### With `ClaudeSDKClient`
+
+Merge AMS hooks into your options, feed messages to the tracer, and `finish()` when done:
+
+```python
+from ams import Tracer
+from ams.claude import instrument_options
+
+tracer = Tracer(environment="prod", tags=["chat"])
+options = instrument_options(my_options, tracer)
+
+async with ClaudeSDKClient(options=options) as client:
+    await client.query("...")
+    async for message in client.receive_response():
+        tracer.record_message(message)
+
+session = tracer.finish()
+```
+
+### Custom storage
+
+Pass any object with `put_session(session) -> str`:
+
+```python
+tracer = Tracer(storage=MyStorage())
+```
+
+## Options
+
+| Tracer arg / env | Default | Notes |
+|---|---|---|
+| `storage` / `AMS_STORAGE` | S3 | `local` to write to disk |
+| `agent` | — | `Agent(name=..., version=...)` |
+| `environment` | — | e.g. `prod`, `staging` |
+| `tags`, `metadata` | — | free-form, promoted into the index for filtering |
+| `capture_thinking` | `True` | record the model's reasoning blocks |
+| `redact` / `AMS_REDACT` | `False` | opt-in PII redaction (email / phone / card / SSN) |
+
+AMS never throws into your agent: hook and storage failures are logged, not raised.
+
+## How it works
+
+See [`docs/architecture.md`](docs/architecture.md) for the module map and the two-channel design (hooks + message stream) that AMS fuses into one session.
+
+## Schema
+
+See [`docs/schema.md`](docs/schema.md) for the full session JSON schema with an example. The contract lives in one file: [`ams/schema.py`](ams/schema.py).
+
+## Frontend
+
+A simple frontend to browse and filter sessions is planned (not built yet). See [`docs/frontend-notes.md`](docs/frontend-notes.md) for the intended design — it reads the `index/` summaries to list sessions and fetches a full session JSON on click.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

ams_observability-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+ams/__init__.py,sha256=GfPzrumwb6d5TixSVQoKCX8yCAC8trYOEdJhSiN8r_M,750
+ams/claude.py,sha256=ixfLxNTVI-1ktMc_AMfnxNYirXTu1z2wXIkOUjCZn5w,1572
+ams/pricing.py,sha256=6LDQLE4dqzrHqyTZ-udJa8hnToW0o16dsPtgn74PI6I,1460
+ams/redact.py,sha256=gcCJ0C5Oy293Lz-Tv_vRmPeHSFbqasiZ2gXmWuuAa9I,983
+ams/schema.py,sha256=XjeM4tMaCgEmpcJwZUIwdnF5df7SF8lc8SWWWtnNuK0,5065
+ams/tracer.py,sha256=G7_E17YHTHSTo8zRqL0vcVlSzDBY1oT5sVefm9Xhs8c,14433
+ams/storage/__init__.py,sha256=aI2jSi4VIuBb0Xzv17VrFLjzJdSZ98-z3FBLO-UF0tw,867
+ams/storage/local.py,sha256=ju73073qIQ0JfoUMz0AiYLN9uuvMiDrkv4cYl-lffu8,1174
+ams/storage/s3.py,sha256=vESblWED3QV03hYZsIaBaiSFXLZh1EyywceoTd2tDuA,2656
+ams_observability-0.1.0.dist-info/METADATA,sha256=4vVqgwpR3xVk8vj15TMmpoN65-Q2f792sYkA9qBQsxw,6635
+ams_observability-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ams_observability-0.1.0.dist-info/licenses/LICENSE,sha256=9e1x1uOFAuYHnoFNI80KuVFdQkwqgM4UiJQzoIV6FdQ,1064
+ams_observability-0.1.0.dist-info/RECORD,,

ams_observability-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ams_observability-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mathu97
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.