veris-ai 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

veris_ai/__init__.py

@@ -5,7 +5,8 @@ from typing import Any
 __version__ = "0.1.0"
 
 # Import lightweight modules that only use base dependencies
-from .jaeger_interface import JaegerClient, SearchQuery
+from .jaeger_interface import JaegerClient
+from .models import ResponseExpectation
 from .tool_mock import veris
 
 # Lazy import for modules with heavy dependencies
@@ -33,9 +34,4 @@ def instrument(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
     return _instrument(*args, **kwargs)
 
 
-__all__ = [
-    "veris",
-    "JaegerClient",
-    "SearchQuery",
-    "instrument",
-]
+__all__ = ["veris", "JaegerClient", "instrument", "ResponseExpectation"]

veris_ai/jaeger_interface/README.md

@@ -3,9 +3,10 @@
 This sub-package ships a **thin synchronous wrapper** around the
 [Jaeger Query Service](https://www.jaegertracing.io/docs/) HTTP API so
 that you can **search for and retrieve traces** directly from Python
-with minimal boilerplate.
+with minimal boilerplate. It also provides **client-side span filtering**
+capabilities for more granular control over the returned data.
 
-> The client relies on `requests` (already included in the SDK’s
+> The client relies on `requests` (already included in the SDK's
 > dependencies) and uses *pydantic* for full type-safety.
 
 ---
@@ -24,7 +25,7 @@ pip install veris-ai
 ## Quick-start
 
 ```python
-from veris_ai.jaeger_interface import JaegerClient, SearchQuery
+from veris_ai.jaeger_interface import JaegerClient
 import json
 from veris_ai.jaeger_interface.models import Trace
 # Replace with the URL of your Jaeger Query Service instance
@@ -32,12 +33,11 @@ client = JaegerClient("http://localhost:16686")
 
 # --- 1. Search traces --------------------------------------------------
 resp = client.search(
-    SearchQuery(
-        service="veris-agent",
-        limit=3,
-        operation="CustomSpanData",
-        tags={"bt.metadata.session_id":"oRL1_IhMP3s7T7mYrixCW"}
-    )
+    service="veris-agent",
+    limit=10,
+    # operation="CustomSpanData",
+    tags={"veris.session_id":"088b5aaf-84bd-4768-9a62-5e981222a9f2"},
+    span_tags={"bt.metadata.model":"gpt-4.1-2025-04-14"}
 )
 
 # save to json
@@ -74,25 +74,53 @@ with open("detailed.json", "w") as f:
 
 | Method | Description |
 | -------- | ----------- |
-| `search(query: SearchQuery) -> SearchResponse` | Search for traces matching the given parameters (wrapper around `/api/traces`). |
-| `get_trace(trace_id: str) -> GetTraceResponse` | Fetch a single trace by ID  (wrapper around `/api/traces/{id}`). |
+| `search(service, *, limit=None, tags=None, operation=None, span_tags=None, **kwargs) -> SearchResponse` | Search for traces with optional span-level filtering. |
+| `get_trace(trace_id: str) -> GetTraceResponse` | Fetch a single trace by ID (wrapper around `/api/traces/{id}`). |
 
-### `SearchQuery`
+### `search()` Parameters
 
-`SearchQuery` is a *pydantic* model for building the query-string sent to
-Jaeger’s `/api/traces` endpoint.
+The `search()` method now uses a flattened parameter structure:
 
-Parameter logic:
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `service` | `str` | Service name to search for. Optional - if not provided, searches across all services. |
+| `limit` | `int` | Maximum number of traces to return. |
+| `tags` | `Dict[str, Any]` | Trace-level tag filters (AND logic). A trace must have a span matching ALL tags. |
+| `operation` | `str` | Filter by operation name. |
+| `span_tags` | `Dict[str, Any]` | Span-level tag filters (OR logic). Returns only spans matching ANY of these tags. | 
+| `span_operations` | `List[str]` | Span-level operation name filters (OR logic). Returns only spans matching ANY of these operations. |
+| `**kwargs` | `Any` | Additional parameters passed directly to Jaeger API. |
 
-* **service** – mandatory, sets the top-level service filter.
-* **operation** – optional; a trace is kept only if *any* of its spans has
-  this exact `operationName`.
-* **tags** – dict of key/value filters; *all* pairs must match on a single
-  span (logical AND). Example: `{"error": "true"}`.
-* **limit** – applied after all filters and trims the result list.
+### Filter Logic
 
-Any other fields are forwarded untouched, so you can experiment with new
-Jaeger parameters without waiting for an SDK update.
+The interface provides two levels of filtering:
+
+1. **Trace-level filtering** (`tags` parameter):
+   - Sent directly to Jaeger API
+   - Uses AND logic: all tag key-value pairs must match on a single span
+   - Efficient server-side filtering
+
+2. **Span-level filtering** (`span_tags` parameter):
+   - Applied client-side after retrieving traces
+   - Uses OR logic: spans matching ANY of the provided tags are included
+   - Traces with no matching spans are excluded from results
+   - Useful for finding spans with specific characteristics across different traces
+
+### Example: Combining Filters
+
+```python
+# Find traces in service that have errors, then filter to show only 
+# spans with specific HTTP status codes or database errors
+traces = client.search(
+    service="my-api",
+    tags={"error": "true"},  # Trace must contain an error
+    span_tags={
+        "http.status_code": 500,
+        "http.status_code": 503,
+        "db.error": "connection_timeout"
+    }  # Show only spans with these specific errors
+)
+```
 
 ---
 
@@ -104,6 +132,6 @@ need API v3 support feel free to open an issue or contribution—thanks!
 
 ---
 
-## Licence
+## License
 
 This package is released under the **MIT license**.

veris_ai/jaeger_interface/__init__.py

@@ -1,18 +1,32 @@
 """Jaeger interface for searching and retrieving traces.
 
 This sub-package provides a thin synchronous wrapper around the Jaeger
-Query Service HTTP API.
+Query Service HTTP API with client-side span filtering capabilities.
 
 Typical usage example::
 
-    from veris_ai.jaeger_interface import JaegerClient, SearchQuery
+    from veris_ai.jaeger_interface import JaegerClient
 
     client = JaegerClient("http://localhost:16686")
 
+    # Search traces with trace-level filters
     traces = client.search(
-        SearchQuery(service="veris-agent", limit=20)
+        service="veris-agent",
+        limit=20,
+        tags={"error": "true"}  # AND logic at trace level
     )
 
+    # Search with span-level filtering
+    traces_filtered = client.search(
+        service="veris-agent",
+        limit=20,
+        span_tags={
+            "http.status_code": 404,
+            "db.error": "timeout"
+        }  # OR logic: spans with either tag are included
+    )
+
+    # Get a specific trace
     trace = client.get_trace(traces.data[0].traceID)
 
 The implementation uses *requests* under the hood and all public functions
@@ -20,7 +34,6 @@ are fully typed using *pydantic* models so that IDEs can provide proper
 autocomplete and type checking.
 """
 
-from .client import JaegerClient
-from .models import SearchQuery
+from .client import JaegerClient as JaegerClient  # noqa: F401
 
-__all__ = ["JaegerClient", "SearchQuery"]
+__all__ = ["JaegerClient"]

veris_ai/jaeger_interface/client.py

@@ -4,16 +4,13 @@ This implementation keeps dependencies minimal while providing fully-typed
 *pydantic* models for both **request** and **response** bodies.
 """
 
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Self
+import json
+import types
+from typing import Any, Self
 
 import requests
 
-from .models import GetTraceResponse, SearchQuery, SearchResponse
-
-if TYPE_CHECKING:
-    from types import TracebackType
+from .models import GetTraceResponse, SearchResponse, Span, Trace
 
 __all__ = ["JaegerClient"]
 
@@ -63,20 +60,110 @@ class JaegerClient:  # noqa: D101
         session.headers.update(self._headers)
         return session, True
 
+    def _span_matches_tags(self, span: Span, span_tags: dict[str, Any]) -> bool:
+        """Check if a span matches any of the provided tags (OR logic)."""
+        if not span.tags or not span_tags:
+            return False
+
+        # Convert span tags to a dict for easier lookup
+        span_tag_dict = {tag.key: tag.value for tag in span.tags}
+
+        # OR logic: return True if ANY tag matches
+        return any(span_tag_dict.get(key) == value for key, value in span_tags.items())
+
+    def _filter_spans(
+        self,
+        traces: list[Trace],
+        span_tags: dict[str, Any] | None,
+        span_operations: list[str] | None = None,
+    ) -> list[Trace]:
+        """Filter spans within traces based on span_tags and/or span_operations.
+
+        Uses OR logic within each filter type. If both are provided, a span must
+        match at least one tag AND at least one operation.
+        """
+        if not span_tags and not span_operations:
+            return traces
+
+        filtered_traces = []
+        for trace in traces:
+            filtered_spans = []
+            for span in trace.spans:
+                tag_match = True
+                op_match = True
+
+                if span_tags:
+                    tag_match = self._span_matches_tags(span, span_tags)
+                if span_operations:
+                    op_match = span.operationName in span_operations
+
+                # If both filters are provided, require both to match (AND logic)
+                if tag_match and op_match:
+                    filtered_spans.append(span)
+
+            if filtered_spans:
+                filtered_trace = Trace(
+                    traceID=trace.traceID,
+                    spans=filtered_spans,
+                    process=trace.process,
+                    warnings=trace.warnings,
+                )
+                filtered_traces.append(filtered_trace)
+
+        return filtered_traces
+
     # ---------------------------------------------------------------------
     # Public API
     # ---------------------------------------------------------------------
 
-    def search(self, query: SearchQuery) -> SearchResponse:  # noqa: D401
-        """Search traces using the *v1* ``/api/traces`` endpoint.
+    def search(  # noqa: PLR0913
+        self,
+        service: str | None = None,
+        *,
+        limit: int | None = None,
+        tags: dict[str, Any] | None = None,
+        operation: str | None = None,
+        span_tags: dict[str, Any] | None = None,
+        span_operations: list[str] | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> SearchResponse:  # noqa: D401
+        """Search traces using the *v1* ``/api/traces`` endpoint with optional span filtering.
 
         Args:
-            query: :class:`~veris_ai.jaeger_interface.models.SearchQuery` instance.
+            service: Service name to search for. If not provided, searches across all services.
+            limit: Maximum number of traces to return.
+            tags: Dictionary of tag filters for trace-level filtering (AND-combined).
+            operation: Operation name to search for.
+            span_tags: Dictionary of tag filters for span-level filtering.
+                      Uses OR logic. Combined with span_operations using AND.
+                      Applied client-side after retrieving traces.
+            span_operations: List of operation names to search for.
+                            Uses OR logic. Combined with span_tags using AND.
+            **kwargs: Additional parameters to pass to the Jaeger API.
 
         Returns:
-            Parsed :class:`~veris_ai.jaeger_interface.models.SearchResponse` model.
+            Parsed :class:`~veris_ai.jaeger_interface.models.SearchResponse` model
+            with spans filtered according to span_tags if provided.
         """
-        params = query.to_params()
+        # Build params for the Jaeger API (excluding span_tags)
+        params: dict[str, Any] = {}
+
+        if service is not None:
+            params["service"] = service
+
+        if limit is not None:
+            params["limit"] = limit
+
+        if operation is not None:
+            params["operation"] = operation
+
+        if tags:
+            # Convert tags to JSON string as expected by Jaeger API
+            params["tags"] = json.dumps(tags)
+
+        # Add any additional parameters
+        params.update(kwargs)
+
         session, should_close = self._make_session()
         try:
             url = f"{self._base_url}/api/traces"
@@ -86,7 +173,23 @@ class JaegerClient:  # noqa: D101
         finally:
             if should_close:
                 session.close()
-        return SearchResponse.model_validate(data)  # type: ignore[arg-type]
+
+        # Parse the response
+        search_response = SearchResponse.model_validate(data)  # type: ignore[arg-type]
+
+        # Apply span-level filtering if span_tags is provided
+        if (
+            (span_tags or span_operations)
+            and search_response.data
+            and isinstance(search_response.data, list)
+        ):
+            filtered_traces = self._filter_spans(search_response.data, span_tags, span_operations)
+            search_response.data = filtered_traces
+            # Update the total to reflect filtered results
+            if search_response.total is not None:
+                search_response.total = len(filtered_traces)
+
+        return search_response
 
     def get_trace(self, trace_id: str) -> GetTraceResponse:  # noqa: D401
         """Retrieve a single trace by *trace_id*.
@@ -125,7 +228,7 @@ class JaegerClient:  # noqa: D101
         self,
         exc_type: type[BaseException] | None,
         exc: BaseException | None,
-        tb: TracebackType | None,
+        tb: types.TracebackType | None,
     ) -> None:
         """Exit the context manager."""
         # Only close if we created the session

veris_ai/jaeger_interface/models.py

@@ -1,9 +1,8 @@
 from __future__ import annotations
 
-import json
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field
 
 __all__ = [
     "Tag",
@@ -12,7 +11,6 @@ __all__ = [
     "Trace",
     "SearchResponse",
     "GetTraceResponse",
-    "SearchQuery",
 ]
 
 
@@ -62,7 +60,7 @@ class _BaseResponse(BaseModel):
     errors: list[str] | None = None
 
     # Allow any additional keys returned by Jaeger so that nothing gets
-    # silently dropped if the backend adds new fields we don’t know about.
+    # silently dropped if the backend adds new fields we don't know about.
 
     model_config = ConfigDict(extra="allow")
 
@@ -78,76 +76,3 @@ class GetTraceResponse(_BaseResponse):
     """Response model for *get trace by id* requests."""
 
     # Same as base but alias for clarity
-
-
-# ---------------------------------------------------------------------------
-# Query models
-# ---------------------------------------------------------------------------
-
-
-class SearchQuery(BaseModel):
-    """Minimal set of query parameters for the `/api/traces` endpoint.
-
-    Parameter interaction rules:
-
-    * **service** – global filter; *all* returned traces must belong to this
-      service.
-    * **operation** – optional secondary filter; returned traces must contain
-      *at least one span* whose ``operationName`` equals the provided value.
-    * **tags** – dictionary of key‒value pairs; each trace must include a span
-      that matches **all** of the pairs (logical AND).
-    * **limit** – applied *after* all other filters; truncates the final list
-      of traces to the requested maximum.
-
-    Any additional/unknown parameters are forwarded thanks to
-    ``extra = "allow"`` – this keeps the model future-proof.
-    """
-
-    # NOTE: Only the fields that are reliably supported by Jaeger’s REST API and
-    # work with the user’s deployment are kept. The model remains *open* to any
-    # extra parameters thanks to `extra = "allow"`.
-
-    service: str = Field(
-        ...,
-        description="Service name to search for. Example: 'veris-agent'",
-    )
-
-    limit: int | None = Field(
-        None,
-        description="Maximum number of traces to return. Example: 10",
-    )
-
-    tags: dict[str, Any] | None = Field(
-        None,
-        description=(
-            "Dictionary of tag filters (AND-combined). "
-            "Example: {'error': 'true', 'bt.metrics.time_to_first_token': '0.813544'}"
-        ),
-    )
-
-    operation: str | None = Field(
-        None,
-        description="Operation name to search for. Example: 'process_chat_message'",
-    )
-
-    model_config = ConfigDict(
-        extra="allow",  # allow additional query params implicitly
-        populate_by_name=True,
-        str_to_lower=False,
-    )
-
-    @field_validator("tags", mode="before")
-    @classmethod
-    def _empty_to_none(cls, v: dict[str, Any] | None) -> dict[str, Any] | None:  # noqa: D401, ANN102
-        return v or None
-
-    def to_params(self) -> dict[str, Any]:  # noqa: D401
-        """Translate the model into a *requests*/*httpx* compatible params dict."""
-        # Dump using aliases so ``span_kind`` becomes ``spanKind`` automatically.
-        params: dict[str, Any] = self.model_dump(exclude_none=True, by_alias=True)
-
-        # Convert tags to a JSON string if necessary – this matches what the UI sends.
-        if "tags" in params and isinstance(params["tags"], dict):
-            params["tags"] = json.dumps(params["tags"])
-
-        return params

veris_ai/models.py

@@ -0,0 +1,11 @@
+"""Models for the VERIS SDK."""
+
+from enum import Enum
+
+
+class ResponseExpectation(str, Enum):
+    """Expected response behavior for tool mocking."""
+
+    AUTO = "auto"
+    REQUIRED = "required"
+    NONE = "none"

veris_ai/tool_mock.py

@@ -15,6 +15,7 @@ from typing import (
 
 import httpx
 
+from veris_ai.models import ResponseExpectation
 from veris_ai.utils import convert_to_type, extract_json_schema
 
 logger = logging.getLogger(__name__)
@@ -91,7 +92,7 @@ class VerisSDK:
             **params_dict,
         )
 
-    def mock(
+    def mock(  # noqa: C901, PLR0915
         self,
         mode: Literal["tool", "function"] = "tool",
         expects_response: bool | None = None,
@@ -99,26 +100,16 @@ class VerisSDK:
     ) -> Callable:
         """Decorator for mocking tool calls."""
 
-        def decorator(func: Callable) -> Callable:
+        def decorator(func: Callable) -> Callable:  # noqa: C901, PLR0915
             """Decorator for mocking tool calls."""
-            endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
-            if not endpoint:
-                error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
-                raise ValueError(error_msg)
-            # Default timeout of 30 seconds
-            timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+            # Check if the original function is async
+            is_async = inspect.iscoroutinefunction(func)
 
-            @wraps(func)
-            async def wrapper(
+            def create_mock_payload(
                 *args: tuple[object, ...],
                 **kwargs: dict[str, object],
-            ) -> object:
-                # Check if we're in simulation mode
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
-                    # If not in simulation mode, execute the original function
-                    return await func(*args, **kwargs)
-                logger.info(f"Simulating function: {func.__name__}")
+            ) -> tuple[dict[str, Any], Any]:
+                """Create the mock payload - shared logic for both sync and async."""
                 sig = inspect.signature(func)
                 type_hints = get_type_hints(func)
 
@@ -143,10 +134,18 @@ class VerisSDK:
                 if expects_response is None and mode == "function":
                     expects_response = False
                 # Prepare payload
+                # Convert expects_response to response_expectation enum
+                if expects_response is False:
+                    response_expectation = ResponseExpectation.NONE
+                elif expects_response is True:
+                    response_expectation = ResponseExpectation.REQUIRED
+                else:
+                    response_expectation = ResponseExpectation.AUTO
+
                 payload = {
                     "session_id": self.session_id,
-                    "expects_response": expects_response,
-                    "cache_response": cache_response,
+                    "response_expectation": response_expectation.value,
+                    "cache_response": bool(cache_response) if cache_response is not None else False,
                     "tool_call": {
                         "function_name": func.__name__,
                         "parameters": params_info,
@@ -155,6 +154,27 @@ class VerisSDK:
                     },
                 }
 
+                return payload, return_type_obj
+
+            @wraps(func)
+            async def async_wrapper(
+                *args: tuple[object, ...],
+                **kwargs: dict[str, object],
+            ) -> object:
+                # Check if we're in simulation mode
+                if not self.session_id:
+                    # If not in simulation mode, execute the original function
+                    return await func(*args, **kwargs)
+                endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
+                if not endpoint:
+                    error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
+                    raise ValueError(error_msg)
+                # Default timeout of 30 seconds
+                timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+                logger.info(f"Simulating function: {func.__name__}")
+                payload, return_type_obj = create_mock_payload(*args, **kwargs)
+
                 # Send request to endpoint with timeout
                 async with httpx.AsyncClient(timeout=timeout) as client:
                     response = await client.post(endpoint, json=payload)
@@ -162,36 +182,77 @@ class VerisSDK:
                     mock_result = response.json()
                     logger.info(f"Mock response: {mock_result}")
 
-                # Convert the mock result to the expected return type
-                if mode == "tool":
-                    return {"content": [{"type": "text", "text": mock_result}]}
-                # Parse the mock result if it's a string
-                # Extract result field for backwards compatibility
-                # Parse the mock result if it's a string
                 if isinstance(mock_result, str):
                     with suppress(json.JSONDecodeError):
                         mock_result = json.loads(mock_result)
                         return convert_to_type(mock_result, return_type_obj)
                 return convert_to_type(mock_result, return_type_obj)
 
-            return wrapper
+            @wraps(func)
+            def sync_wrapper(
+                *args: tuple[object, ...],
+                **kwargs: dict[str, object],
+            ) -> object:
+                # Check if we're in simulation mode
+                if not self.session_id:
+                    # If not in simulation mode, execute the original function
+                    return func(*args, **kwargs)
+                endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
+                if not endpoint:
+                    error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
+                    raise ValueError(error_msg)
+                # Default timeout of 30 seconds
+                timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+                logger.info(f"Simulating function: {func.__name__}")
+                payload, return_type_obj = create_mock_payload(*args, **kwargs)
+
+                # Send request to endpoint with timeout (synchronous)
+                with httpx.Client(timeout=timeout) as client:
+                    response = client.post(endpoint, json=payload)
+                    response.raise_for_status()
+                    mock_result = response.json()
+                    logger.info(f"Mock response: {mock_result}")
+
+                if isinstance(mock_result, str):
+                    with suppress(json.JSONDecodeError):
+                        mock_result = json.loads(mock_result)
+                        return convert_to_type(mock_result, return_type_obj)
+                return convert_to_type(mock_result, return_type_obj)
+
+            # Return the appropriate wrapper based on whether the function is async
+            return async_wrapper if is_async else sync_wrapper
 
         return decorator
 
     def stub(self, return_value: Any) -> Callable:  # noqa: ANN401
-        """Decorator for stubbing tool calls."""
+        """Decorator for stubbing toolw calls."""
 
         def decorator(func: Callable) -> Callable:
+            # Check if the original function is async
+            is_async = inspect.iscoroutinefunction(func)
+
             @wraps(func)
-            async def wrapper(*args: tuple[object, ...], **kwargs: dict[str, object]) -> object:
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
+            async def async_wrapper(
+                *args: tuple[object, ...],
+                **kwargs: dict[str, object],
+            ) -> object:
+                if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return await func(*args, **kwargs)
                 logger.info(f"Simulating function: {func.__name__}")
                 return return_value
 
-            return wrapper
+            @wraps(func)
+            def sync_wrapper(*args: tuple[object, ...], **kwargs: dict[str, object]) -> object:
+                if not self.session_id:
+                    # If not in simulation mode, execute the original function
+                    return func(*args, **kwargs)
+                logger.info(f"Simulating function: {func.__name__}")
+                return return_value
+
+            # Return the appropriate wrapper based on whether the function is async
+            return async_wrapper if is_async else sync_wrapper
 
         return decorator
 

veris_ai/utils.py

@@ -20,6 +20,7 @@ def convert_to_type(value: object, target_type: type) -> object:
         list: _convert_list,
         dict: _convert_dict,
         Union: _convert_union,
+        types.UnionType: _convert_union,  # Handle Python 3.10+ union syntax (str | int)
     }
 
     # Use appropriate converter based on origin

{veris_ai-1.1.0.dist-info → veris_ai-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veris-ai
-Version: 1.1.0
+Version: 1.3.0
 Summary: A Python package for Veris AI tools
 Project-URL: Homepage, https://github.com/veris-ai/veris-python-sdk
 Project-URL: Bug Tracker, https://github.com/veris-ai/veris-python-sdk/issues
@@ -64,7 +64,7 @@ The SDK supports flexible import patterns to minimize dependencies:
 
 ```python
 # These imports only require base dependencies (httpx, pydantic, requests)
-from veris_ai import veris, JaegerClient, SearchQuery
+from veris_ai import veris, JaegerClient
 ```
 
 ### Optional Imports (Require Extra Dependencies)
@@ -434,14 +434,23 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 ## Jaeger Trace Interface
 
 A lightweight, fully-typed wrapper around the Jaeger **Query Service** HTTP API lives under `veris_ai.jaeger_interface`.
-It allows you to **search and retrieve traces** from both Jaeger’s default storage back-ends as well as **OpenSearch**, which powers the official Jaeger UI search page.
+It allows you to **search and retrieve traces** from both Jaeger's default storage back-ends as well as **OpenSearch**, with additional **client-side span filtering** capabilities.
 
 ```python
-from veris_ai.jaeger_interface import JaegerClient, SearchQuery
+from veris_ai.jaeger_interface import JaegerClient
 
 client = JaegerClient("http://localhost:16686")
 
-traces = client.search(SearchQuery(service="veris-agent", limit=2))
+# Search with trace-level filters (server-side)
+traces = client.search(service="veris-agent", limit=2, tags={"error": "true"})
+
+# Search with span-level filters (client-side, OR logic)
+filtered = client.search(
+    service="veris-agent", 
+    limit=10,
+    span_tags={"http.status_code": 500, "db.error": "timeout"}
+)
+
 first_trace = client.get_trace(traces.data[0].traceID)
 ```
 

veris_ai-1.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+veris_ai/__init__.py,sha256=Vp5yf9ZRchw0mmPwrRuNebI5cb2NGwpJGfr41l86q1U,1177
+veris_ai/braintrust_tracing.py,sha256=0i-HR6IuK3-Q5ujMjT1FojxESRZLgqEvJ44bfJfDHaw,11938
+veris_ai/models.py,sha256=6HINPxNFCakCVPcyEbUswWkXwb2K4lF0A8g8EvTMal4,213
+veris_ai/tool_mock.py,sha256=U4xjINEZbtjutb_Vtr_So1ENNrU9kDROSyNUU5RL1Jc,10610
+veris_ai/utils.py,sha256=3R2J9ko5t1UATiF1R6Hox9IPbtUz59EHsMDFg1-i7sk,9208
+veris_ai/jaeger_interface/README.md,sha256=te5z3MWLqd2ECVV-a0MImBwTKRgQuuSuDB3bwIIsHi0,4437
+veris_ai/jaeger_interface/__init__.py,sha256=d873a0zq3eUYU2Y77MtdjCwIARjAsAP7WDqGXDMWpYs,1158
+veris_ai/jaeger_interface/client.py,sha256=yJrh86wRR0Dk3Gq12DId99WogcMIVbL0QQFqVSevvlE,8772
+veris_ai/jaeger_interface/models.py,sha256=e64VV6IvOEFuzRUgvDAMQFyOZMRb56I-PUPZLBZ3rX0,1864
+veris_ai-1.3.0.dist-info/METADATA,sha256=FD5DuzpYTZKjDmsPOb897HIMdOzS4l1UNTKh_68d29Y,13832
+veris_ai-1.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+veris_ai-1.3.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
+veris_ai-1.3.0.dist-info/RECORD,,

veris_ai-1.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-veris_ai/__init__.py,sha256=D7IkmgwQmucTTqqgRu-kOs5JTLLAA0ts3x91k4kyK2Y,1161
-veris_ai/braintrust_tracing.py,sha256=0i-HR6IuK3-Q5ujMjT1FojxESRZLgqEvJ44bfJfDHaw,11938
-veris_ai/tool_mock.py,sha256=PkI90tHMtmLj8shp8ytmOlrKc53M4kY-1YU0y4muTmU,7645
-veris_ai/utils.py,sha256=AjKfsCdpatUqO6iPcqcN_V5JFWo25MfF-xchwCnx3Ws,9119
-veris_ai/jaeger_interface/README.md,sha256=mu-XdBm3FM8MqyLEpZdjIE1lbgsvWszk2ehvez2p-8w,3055
-veris_ai/jaeger_interface/__init__.py,sha256=sWwt5M52Hi1vltNXmjSEpIHvA1NqsXymV8MiiGSedlg,735
-veris_ai/jaeger_interface/client.py,sha256=GWYFS0sgTZShQOi7Ndz504vyzCIKi6Kb_ZAMKskdjgE,4782
-veris_ai/jaeger_interface/models.py,sha256=Tnx_817dCNUJ1bM9dv-45AhK017AL8qgOfgE6ne9HUU,4606
-veris_ai-1.1.0.dist-info/METADATA,sha256=FzO5tRUgWZ5OXqqeUpz_uHpou5I4mc000n2jTjMja_g,13597
-veris_ai-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-veris_ai-1.1.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
-veris_ai-1.1.0.dist-info/RECORD,,