spanlight 0.1.1__tar.gz → 0.1.2__tar.gz

{spanlight-0.1.1 → spanlight-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spanlight
-Version: 0.1.1
+Version: 0.1.2
 Summary: Python SDK for Spanlight, open-source observability for LLM applications.
 Author: Dheeraj
 License-Expression: MIT
@@ -294,17 +294,19 @@ run makes real provider calls. In a GitHub workflow use the
 
 For every LLM call:
 
-| Field                       | Source                                                                                                                            |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`                  | `openai` / `anthropic`                                                                                                            |
-| `model`                     | Model from the response (for example `gpt-4o-mini-2024-07-18`). Falls back to the requested model.                                |
-| `usage.input_tokens`        | Total prompt tokens, **including** cached tokens. For Anthropic this is input + cache reads + cache writes.                       |
-| `usage.output_tokens`       | Completion tokens                                                                                                                 |
-| `usage.cached_tokens`       | Prompt tokens served from the provider's prompt cache                                                                             |
-| `time_to_first_token_ms`    | Streaming calls only                                                                                                              |
-| `input`                     | Request parameters such as `messages`, `system` and `temperature`. API keys, headers, `extra_*` and `timeout` are never recorded. |
-| `output`                    | The assistant message, including tool calls                                                                                       |
-| `status` / `status_message` | `error` plus the provider's message when the call fails                                                                           |
+| Field                         | Source                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`                    | `openai` / `anthropic`                                                                                                                                                    |
+| `model`                       | Model from the response (for example `gpt-4o-mini-2024-07-18`). Falls back to the requested model.                                                                        |
+| `usage.input_tokens`          | Total prompt tokens, **including** cached tokens. For Anthropic this is input + cache reads + cache writes.                                                               |
+| `usage.output_tokens`         | Completion tokens                                                                                                                                                         |
+| `usage.cached_tokens`         | Prompt tokens served from the provider's prompt cache                                                                                                                     |
+| `usage.cache_write_tokens`    | Prompt tokens written to the prompt cache (Anthropic `cache_creation_input_tokens`). Sent only when the provider reports it.                                              |
+| `usage.cache_write_1h_tokens` | The part of `cache_write_tokens` written with Anthropic's 1-hour TTL (`cache_creation.ephemeral_1h_input_tokens`); the rest are 5-minute writes. Sent only when reported. |
+| `time_to_first_token_ms`      | Streaming calls only                                                                                                                                                      |
+| `input`                       | Request parameters such as `messages`, `system` and `temperature`. API keys, headers, `extra_*` and `timeout` are never recorded.                                         |
+| `output`                      | The assistant message, including tool calls                                                                                                                               |
+| `status` / `status_message`   | `error` plus the provider's message when the call fails                                                                                                                   |
 
 The Spanlight server also redacts common secret patterns from
 payloads on ingestion. Set `capture_payloads = false` on a project to drop
@@ -362,7 +364,8 @@ with spanlight.span("rerank", kind="retrieval") as span:
 
 `Span` methods: `set_input`, `set_output`, `set_attribute`, `set_attributes`,
 `set_model(model, provider=...)`, `set_usage(input_tokens=, output_tokens=,
-cached_tokens=)`, `set_finish_reason(reason)`, `set_request_hash(hash)`,
+cached_tokens=, cache_write_tokens=, cache_write_1h_tokens=)`,
+`set_finish_reason(reason)`, `set_request_hash(hash)`,
 `mark_first_token()` and `record_error(exc_or_message)`. An
 exception that escapes the block marks the span as failed and is re-raised
 unchanged.

{spanlight-0.1.1 → spanlight-0.1.2}/README.md

@@ -267,17 +267,19 @@ run makes real provider calls. In a GitHub workflow use the
 
 For every LLM call:
 
-| Field                       | Source                                                                                                                            |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`                  | `openai` / `anthropic`                                                                                                            |
-| `model`                     | Model from the response (for example `gpt-4o-mini-2024-07-18`). Falls back to the requested model.                                |
-| `usage.input_tokens`        | Total prompt tokens, **including** cached tokens. For Anthropic this is input + cache reads + cache writes.                       |
-| `usage.output_tokens`       | Completion tokens                                                                                                                 |
-| `usage.cached_tokens`       | Prompt tokens served from the provider's prompt cache                                                                             |
-| `time_to_first_token_ms`    | Streaming calls only                                                                                                              |
-| `input`                     | Request parameters such as `messages`, `system` and `temperature`. API keys, headers, `extra_*` and `timeout` are never recorded. |
-| `output`                    | The assistant message, including tool calls                                                                                       |
-| `status` / `status_message` | `error` plus the provider's message when the call fails                                                                           |
+| Field                         | Source                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`                    | `openai` / `anthropic`                                                                                                                                                    |
+| `model`                       | Model from the response (for example `gpt-4o-mini-2024-07-18`). Falls back to the requested model.                                                                        |
+| `usage.input_tokens`          | Total prompt tokens, **including** cached tokens. For Anthropic this is input + cache reads + cache writes.                                                               |
+| `usage.output_tokens`         | Completion tokens                                                                                                                                                         |
+| `usage.cached_tokens`         | Prompt tokens served from the provider's prompt cache                                                                                                                     |
+| `usage.cache_write_tokens`    | Prompt tokens written to the prompt cache (Anthropic `cache_creation_input_tokens`). Sent only when the provider reports it.                                              |
+| `usage.cache_write_1h_tokens` | The part of `cache_write_tokens` written with Anthropic's 1-hour TTL (`cache_creation.ephemeral_1h_input_tokens`); the rest are 5-minute writes. Sent only when reported. |
+| `time_to_first_token_ms`      | Streaming calls only                                                                                                                                                      |
+| `input`                       | Request parameters such as `messages`, `system` and `temperature`. API keys, headers, `extra_*` and `timeout` are never recorded.                                         |
+| `output`                      | The assistant message, including tool calls                                                                                                                               |
+| `status` / `status_message`   | `error` plus the provider's message when the call fails                                                                                                                   |
 
 The Spanlight server also redacts common secret patterns from
 payloads on ingestion. Set `capture_payloads = false` on a project to drop
@@ -335,7 +337,8 @@ with spanlight.span("rerank", kind="retrieval") as span:
 
 `Span` methods: `set_input`, `set_output`, `set_attribute`, `set_attributes`,
 `set_model(model, provider=...)`, `set_usage(input_tokens=, output_tokens=,
-cached_tokens=)`, `set_finish_reason(reason)`, `set_request_hash(hash)`,
+cached_tokens=, cache_write_tokens=, cache_write_1h_tokens=)`,
+`set_finish_reason(reason)`, `set_request_hash(hash)`,
 `mark_first_token()` and `record_error(exc_or_message)`. An
 exception that escapes the block marks the span as failed and is re-raised
 unchanged.

{spanlight-0.1.1 → spanlight-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spanlight"
-version = "0.1.1"
+version = "0.1.2"
 description = "Python SDK for Spanlight, open-source observability for LLM applications."
 readme = "README.md"
 license = "MIT"

{spanlight-0.1.1 → spanlight-0.1.2}/src/spanlight/_span.py

@@ -143,6 +143,8 @@ class Span:
         self.input_tokens: int | None = None
         self.output_tokens: int | None = None
         self.cached_tokens: int | None = None
+        self.cache_write_tokens: int | None = None
+        self.cache_write_1h_tokens: int | None = None
         self.time_to_first_token_ms: float | None = None
         self.request_hash: str | None = None
         self.finish_reason: str | None = None
@@ -206,11 +208,17 @@ class Span:
         input_tokens: int | None = None,
         output_tokens: int | None = None,
         cached_tokens: int | None = None,
+        cache_write_tokens: int | None = None,
+        cache_write_1h_tokens: int | None = None,
     ) -> None:
         """Record token usage. ``None`` leaves the existing value unchanged.
 
-        ``input_tokens`` is the *total* prompt size, including any cached
-        tokens; ``cached_tokens`` is the subset served from the prompt cache.
+        ``input_tokens`` is the *total* prompt size: uncached tokens plus
+        prompt-cache reads plus prompt-cache writes. ``cached_tokens`` is the
+        part served from the cache (reads); ``cache_write_tokens`` is the part
+        written to it, and ``cache_write_1h_tokens`` the subset of those writes
+        made with a 1-hour TTL (the rest are 5-minute writes). Leave the write
+        fields unset when the provider reports none.
         """
         if not self._mutable:
             return
@@ -220,6 +228,10 @@ class Span:
             self.output_tokens = int(output_tokens)
         if cached_tokens is not None:
             self.cached_tokens = int(cached_tokens)
+        if cache_write_tokens is not None:
+            self.cache_write_tokens = int(cache_write_tokens)
+        if cache_write_1h_tokens is not None:
+            self.cache_write_1h_tokens = int(cache_write_1h_tokens)
 
     def set_request_hash(self, value: str | None) -> None:
         """Record the request hash used to group identical calls.
@@ -301,6 +313,10 @@ class Span:
             "input_tokens": self.input_tokens,
             "output_tokens": self.output_tokens,
             "cached_tokens": self.cached_tokens,
+            # Sent only when set, so payloads for servers that predate cache-write
+            # pricing stay unchanged.
+            "cache_write_tokens": self.cache_write_tokens,
+            "cache_write_1h_tokens": self.cache_write_1h_tokens,
         }
         if any(count is not None for count in token_counts.values()):
             usage = {key: count for key, count in token_counts.items() if count is not None}

{spanlight-0.1.1 → spanlight-0.1.2}/src/spanlight/_version.py

@@ -1,3 +1,3 @@
 """Package version, kept in one place."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{spanlight-0.1.1 → spanlight-0.1.2}/src/spanlight/integrations/anthropic.py

@@ -7,8 +7,10 @@ instance, sync or async.
 Token accounting: Anthropic reports ``input_tokens`` *excluding* prompt-cache
 reads and writes. To keep one meaning across providers, spans record
 ``input_tokens`` as the total prompt size (uncached + cache reads + cache
-writes) and ``cached_tokens`` as the cache reads. The raw cache-write count is
-kept in the ``usage.cache_creation_input_tokens`` attribute.
+writes), ``cached_tokens`` as the cache reads, ``cache_write_tokens`` as the
+cache writes (``cache_creation_input_tokens``) and ``cache_write_1h_tokens``
+as the writes made with the 1-hour TTL
+(``cache_creation.ephemeral_1h_input_tokens``), which the server prices apart.
 """
 
 from __future__ import annotations
@@ -128,16 +130,26 @@ def _record_usage(span: Span, usage: Any) -> None:
     uncached = as_int(get_field(usage, "input_tokens"))
     cache_read = as_int(get_field(usage, "cache_read_input_tokens"))
     cache_write = as_int(get_field(usage, "cache_creation_input_tokens"))
+    cache_write_1h = as_int(get_field(usage, "cache_creation", "ephemeral_1h_input_tokens"))
     total_input = None
     if uncached is not None:
         total_input = uncached + (cache_read or 0) + (cache_write or 0)
+    if cache_write_1h is not None and (cache_write is None or cache_write_1h > cache_write):
+        # The server rejects the whole span for an inconsistent split; keep the
+        # total and drop the part rather than lose the span.
+        logger.debug(
+            "Ignoring Anthropic 1h cache-write count %r exceeding total %r",
+            cache_write_1h,
+            cache_write,
+        )
+        cache_write_1h = None
     span.set_usage(
         input_tokens=total_input,
         output_tokens=as_int(get_field(usage, "output_tokens")),
         cached_tokens=cache_read,
+        cache_write_tokens=cache_write,
+        cache_write_1h_tokens=cache_write_1h,
     )
-    if cache_write:
-        span.set_attribute("usage.cache_creation_input_tokens", cache_write)
 
 
 def _record_message_metadata(span: Span, message_id: Any, stop_reason: Any) -> None:
@@ -184,7 +196,11 @@ class _MessagesStreamAccumulator(StreamAccumulator):
         self._merge_usage(get_field(message, "usage"))
 
     def _merge_usage(self, usage: Any) -> None:
-        """Merge usage counters; later events carry cumulative values."""
+        """Merge usage counters; later events carry cumulative values, never summed.
+
+        The TTL split (``cache_creation``) usually appears only in
+        ``message_start``; a later event without it leaves the split in place.
+        """
         for key in (
             "input_tokens",
             "output_tokens",
@@ -194,6 +210,9 @@ class _MessagesStreamAccumulator(StreamAccumulator):
             value = as_int(get_field(usage, key))
             if value is not None:
                 self._usage[key] = value
+        cache_write_1h = as_int(get_field(usage, "cache_creation", "ephemeral_1h_input_tokens"))
+        if cache_write_1h is not None:
+            self._usage["cache_creation"] = {"ephemeral_1h_input_tokens": cache_write_1h}
 
     def _on_block_start(self, event: Any) -> None:
         index = as_int(get_field(event, "index")) or 0

{spanlight-0.1.1 → spanlight-0.1.2}/tests/provider_mocks.py

@@ -300,6 +300,46 @@ ANTHROPIC_MESSAGE = {
 }
 
 
+# Real usage from a 2026-10-14 pilot call: every write landed in the 1-hour cache.
+ANTHROPIC_CACHE_WRITE_USAGE = {
+    "input_tokens": 19,
+    "output_tokens": 12,
+    "cache_read_input_tokens": 0,
+    "cache_creation_input_tokens": 6404,
+    "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 6404},
+}
+
+ANTHROPIC_CACHE_WRITE_MESSAGE = {**ANTHROPIC_MESSAGE, "usage": ANTHROPIC_CACHE_WRITE_USAGE}
+
+
+def anthropic_cache_write_stream() -> list[tuple[str | None, dict[str, Any] | str]]:
+    """Text stream whose ``message_start`` carries the pilot's cache-write usage.
+
+    ``message_delta`` repeats the cumulative prompt counts without the TTL split,
+    as the API does; the accumulator must not sum them.
+    """
+    events = anthropic_text_stream()
+    name, start = events[0]
+    assert isinstance(start, dict)
+    message = {**start["message"], "usage": {**ANTHROPIC_CACHE_WRITE_USAGE, "output_tokens": 1}}
+    events[0] = (name, {**start, "message": message})
+    name, delta = events[-2]
+    assert isinstance(delta, dict)
+    events[-2] = (
+        name,
+        {
+            **delta,
+            "usage": {
+                "input_tokens": 19,
+                "cache_read_input_tokens": 0,
+                "cache_creation_input_tokens": 6404,
+                "output_tokens": 12,
+            },
+        },
+    )
+    return events
+
+
 def anthropic_text_stream() -> list[tuple[str | None, dict[str, Any] | str]]:
     return [
         (

{spanlight-0.1.1 → spanlight-0.1.2}/tests/test_anthropic.py

@@ -7,9 +7,11 @@ import json
 import anthropic
 import pytest
 from provider_mocks import (
+    ANTHROPIC_CACHE_WRITE_MESSAGE,
     ANTHROPIC_INVALID_REQUEST,
     ANTHROPIC_MESSAGE,
     MockProvider,
+    anthropic_cache_write_stream,
     anthropic_stream_with_overload_error,
     anthropic_text_stream,
     anthropic_tool_use_stream,
@@ -61,8 +63,14 @@ def test_messages_create_span_fields(tracer, ingest):
     assert span["provider"] == "anthropic"
     assert span["model"] == "claude-haiku-4-5-20251001"
     # input_tokens is the full prompt: 12 uncached + 1500 cache reads + 3 cache writes.
-    assert span["usage"] == {"input_tokens": 1515, "output_tokens": 9, "cached_tokens": 1500}
-    assert span["attributes"]["usage.cache_creation_input_tokens"] == 3
+    # No TTL split was reported, so cache_write_1h_tokens is omitted (all writes 5-minute).
+    assert span["usage"] == {
+        "input_tokens": 1515,
+        "output_tokens": 9,
+        "cached_tokens": 1500,
+        "cache_write_tokens": 3,
+    }
+    assert "usage.cache_creation_input_tokens" not in span["attributes"]
     assert span["attributes"]["response.stop_reason"] == "end_turn"
     assert span["attributes"]["response.id"] == "msg_01XFDUDYJgAACzvnptvVoYEL"
     assert span["input"] == {
@@ -78,6 +86,41 @@ def test_messages_create_span_fields(tracer, ingest):
     assert API_KEY not in json.dumps(span)
 
 
+# Real 2026-10-14 pilot usage: 19 uncached + 0 reads + 6404 writes, all 1-hour TTL.
+CACHE_WRITE_USAGE = {
+    "input_tokens": 6423,
+    "output_tokens": 12,
+    "cached_tokens": 0,
+    "cache_write_tokens": 6404,
+    "cache_write_1h_tokens": 6404,
+}
+
+
+def test_create_records_cache_write_fields(tracer, ingest):
+    provider = MockProvider(json_response(ANTHROPIC_CACHE_WRITE_MESSAGE))
+    client = make_client(provider, tracer)
+
+    message = client.messages.create(model=MODEL, max_tokens=256, messages=MESSAGES)
+
+    assert message.usage.cache_creation.ephemeral_1h_input_tokens == 6404
+    span = flushed_spans(tracer, ingest)[0]
+    assert span["usage"] == CACHE_WRITE_USAGE
+    assert "usage.cache_creation_input_tokens" not in span["attributes"]
+
+
+def test_stream_cache_write_fields(tracer, ingest):
+    provider = MockProvider(sse_response(anthropic_cache_write_stream()))
+    client = make_client(provider, tracer)
+
+    with client.messages.stream(model=MODEL, max_tokens=256, messages=MESSAGES) as stream:
+        streamed_text = "".join(stream.text_stream)
+
+    assert streamed_text == "Hi, how can I help?"
+    span = flushed_spans(tracer, ingest)[0]
+    assert span["usage"] == CACHE_WRITE_USAGE
+    assert "usage.cache_creation_input_tokens" not in span["attributes"]
+
+
 async def test_async_messages_create(tracer, ingest):
     provider = MockProvider(json_response(ANTHROPIC_MESSAGE))
     client = make_async_client(provider, tracer)
@@ -105,7 +148,12 @@ def test_create_with_stream_true(tracer, ingest):
     span = flushed_spans(tracer, ingest)[0]
     assert span["status"] == "ok"
     assert span["model"] == "claude-haiku-4-5-20251001"
-    assert span["usage"] == {"input_tokens": 25, "output_tokens": 15, "cached_tokens": 0}
+    assert span["usage"] == {
+        "input_tokens": 25,
+        "output_tokens": 15,
+        "cached_tokens": 0,
+        "cache_write_tokens": 0,
+    }
     assert span["time_to_first_token_ms"] is not None
     assert span["output"] == {
         "role": "assistant",
@@ -142,7 +190,12 @@ def test_messages_stream_helper(tracer, ingest):
     assert final.usage.output_tokens == 15
     span = flushed_spans(tracer, ingest)[0]
     assert span["name"] == f"chat {MODEL}"
-    assert span["usage"] == {"input_tokens": 25, "output_tokens": 15, "cached_tokens": 0}
+    assert span["usage"] == {
+        "input_tokens": 25,
+        "output_tokens": 15,
+        "cached_tokens": 0,
+        "cache_write_tokens": 0,
+    }
     assert span["time_to_first_token_ms"] is not None
     assert span["output"]["content"] == [{"type": "text", "text": "Hi, how can I help?"}]
     assert span["input"]["stream"] is True

{spanlight-0.1.1 → spanlight-0.1.2}/tests/test_spans_and_context.py

@@ -38,6 +38,36 @@ def test_span_setters_are_exported(tracer, ingest):
     assert exported["attributes"] == {"temperature": 0.2, "attempt": 1}
 
 
+def test_set_usage_omits_unset_write_fields(tracer, ingest):
+    with tracer.span("reads-only", kind="llm") as span:
+        span.set_usage(input_tokens=120, output_tokens=30, cached_tokens=100)
+    with tracer.span("writes-5m", kind="llm") as span:
+        span.set_usage(input_tokens=120, output_tokens=30, cache_write_tokens=20)
+    with tracer.span("writes-split", kind="llm") as span:
+        span.set_usage(
+            input_tokens=120,
+            output_tokens=30,
+            cached_tokens=50,
+            cache_write_tokens=20,
+            cache_write_1h_tokens=5,
+        )
+
+    by_name = {item["name"]: item["usage"] for item in flushed_spans(tracer, ingest)}
+    assert by_name["reads-only"] == {"input_tokens": 120, "output_tokens": 30, "cached_tokens": 100}
+    assert by_name["writes-5m"] == {
+        "input_tokens": 120,
+        "output_tokens": 30,
+        "cache_write_tokens": 20,
+    }
+    assert by_name["writes-split"] == {
+        "input_tokens": 120,
+        "output_tokens": 30,
+        "cached_tokens": 50,
+        "cache_write_tokens": 20,
+        "cache_write_1h_tokens": 5,
+    }
+
+
 def test_span_records_error_and_reraises(tracer, ingest):
     with pytest.raises(ZeroDivisionError), tracer.span("divide"):
         _ = 1 / 0

{spanlight-0.1.1 → spanlight-0.1.2}/uv.lock

@@ -838,7 +838,7 @@ wheels = [
 
 [[package]]
 name = "spanlight"
-version = "0.1.1"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },