feat(trace): add advanced span filters

Add nested `filters` to `Trace.get_spans()` so callers can select spans by type, name,
error state, tags, metadata, and duration with matching local and BTQL semantics.

```python
spans = await trace.get_spans(
    filters={
        "span_type": ["tool"],
        "name": ["search", "lookup"],
        "has_error": True,
        "tags": {"all": ["production"], "none": ["internal"]},
        "metadata": {"model": "gpt-5"},
        "duration": {"min": 0.5, "max": 10},
    }
)
```

Preserve fields needed to evaluate these filters in the local span cache. Keep existing full-trace
and span-type caching, but execute advanced remote filters as fresh BTQL requests so partial or
empty results do not become stale snapshots:

```text
local buffered spans -> in-memory filtering
complete trace cache -> in-memory filtering
advanced remote filter -> fresh BTQL request
```

Keep `span_type=[...]` compatible on the public `Trace` API but emit a `DeprecationWarning`
directing callers to `filters={"span_type": [...]}`. Add runtime and type coverage for
validation and equivalent local and server filtering.

Author: AbhiPrasad

py/src/braintrust/logger.py

@@ -4627,6 +4627,9 @@ def log_internal(self, event: dict[str, Any] | None = None, internal_data: dict[
                 metadata=serializable_partial_record.get("metadata"),
                 span_parents=self.span_parents,
                 span_attributes=serializable_partial_record.get("span_attributes"),
+                error=serializable_partial_record.get("error"),
+                metrics=serializable_partial_record.get("metrics"),
+                tags=serializable_partial_record.get("tags"),
             )
             self.state.span_cache.queue_write(self.root_span_id, self.span_id, cached_span)
 

py/src/braintrust/span_cache.py

@@ -14,7 +14,7 @@
 from typing import Any
 
 from braintrust.types import Metadata
-from braintrust.util import merge_dicts
+from braintrust.util import clean_nones, merge_dicts
 
 
 # Global registry of active span caches for process exit cleanup
@@ -23,7 +23,12 @@
 
 
 class CachedSpan:
-    """Cached span data structure."""
+    """A span held in the local cache, before it has been flushed to the server.
+
+    Carries the subset of span fields that scorers can filter on, so that a trace can be
+    queried without a round-trip. Fields the server has but this does not are simply not
+    filterable locally.
+    """
 
     def __init__(
         self,
@@ -33,40 +38,40 @@ def __init__(
         metadata: Metadata | None = None,
         span_parents: list[str] | None = None,
         span_attributes: dict[str, Any] | None = None,
+        error: Any | None = None,
+        metrics: dict[str, Any] | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ):
         self.span_id = span_id
         self.input = input
         self.output = output
         self.metadata = metadata
         self.span_parents = span_parents
         self.span_attributes = span_attributes
+        self.error = error
+        self.metrics = metrics
+        self.tags = tags
+        # Retain any fields written by a newer SDK so to_dict() round-trips them.
+        for key, value in kwargs.items():
+            setattr(self, key, value)
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        result = {"span_id": self.span_id}
-        if self.input is not None:
-            result["input"] = self.input
-        if self.output is not None:
-            result["output"] = self.output
-        if self.metadata is not None:
-            result["metadata"] = self.metadata
-        if self.span_parents is not None:
-            result["span_parents"] = self.span_parents
-        if self.span_attributes is not None:
-            result["span_attributes"] = self.span_attributes
-        return result
+        """Return the span's set fields, dropping those left as None.
+
+        Unset fields are omitted rather than written as null to keep the on-disk record
+        small; span_id is always present, so it survives the stripping.
+        """
+        return clean_nones(self.__dict__)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "CachedSpan":
-        """Create from dictionary."""
-        return cls(
-            span_id=data["span_id"],
-            input=data.get("input"),
-            output=data.get("output"),
-            metadata=data.get("metadata"),
-            span_parents=data.get("span_parents"),
-            span_attributes=data.get("span_attributes"),
-        )
+        """Rebuild a span from its cached record, keeping fields this class does not name.
+
+        Retaining unknown keys means a cache written by a newer SDK stays readable, and
+        round-trips back out through to_dict() intact.
+        """
+        return cls(**data)
 
 
 class DiskSpanRecord:

py/src/braintrust/test_span_cache.py

@@ -13,6 +13,9 @@ def test_span_cache_write_and_read():
         span_id="span-1",
         input={"text": "hello"},
         output={"response": "world"},
+        error={"message": "retryable"},
+        metrics={"start": 1, "end": 3},
+        tags=["production"],
     )
     span2 = CachedSpan(
         span_id="span-2",
@@ -30,6 +33,10 @@ def test_span_cache_write_and_read():
     span_ids = {s.span_id for s in spans}
     assert "span-1" in span_ids
     assert "span-2" in span_ids
+    stored_span1 = next(span for span in spans if span.span_id == "span-1")
+    assert stored_span1.error == {"message": "retryable"}
+    assert stored_span1.metrics == {"start": 1, "end": 3}
+    assert stored_span1.tags == ["production"]
 
     cache.stop()
     cache.dispose()