veris-ai 1.1.0__tar.gz → 1.3.0__tar.gz

{veris_ai-1.1.0 → veris_ai-1.3.0}/PKG-INFO

@@ -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.1.0 → veris_ai-1.3.0}/README.md

@@ -28,7 +28,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)
@@ -398,14 +398,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.1.0 → veris_ai-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "veris-ai"
-version = "1.1.0"
+version = "1.3.0"
 description = "A Python package for Veris AI tools"
 readme = "README.md"
 requires-python = ">=3.11"

{veris_ai-1.1.0 → veris_ai-1.3.0}/src/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-1.3.0/src/veris_ai/jaeger_interface/README.md

@@ -0,0 +1,137 @@
+# Jaeger Interface
+
+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. 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
+> dependencies) and uses *pydantic* for full type-safety.
+
+---
+
+## Installation
+
+`veris-ai` already lists both `requests` and `pydantic` as hard
+requirements, so **no additional dependencies are required**.
+
+```bash
+pip install veris-ai
+```
+
+---
+
+## Quick-start
+
+```python
+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
+client = JaegerClient("http://localhost:16686")
+
+# --- 1. Search traces --------------------------------------------------
+resp = client.search(
+    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
+with open("resp.json", "w") as f:
+    f.write(resp.model_dump_json(indent=2))
+
+# Guard clause
+if not resp or not resp.data:
+    print("No data found")
+    exit(1)
+
+# Print trace ids
+for trace in resp.data:
+    if isinstance(trace, Trace):
+        print("TRACE ID:", trace.traceID, len(trace.spans), "spans")
+
+# --- 2. Retrieve a specific trace -------------------------------------
+if isinstance(resp.data, list):
+    trace_id = resp.data[0].traceID
+else:
+    trace_id = resp.data.traceID
+
+detailed = client.get_trace(trace_id)
+# save detailed to json
+with open("detailed.json", "w") as f:
+    f.write(detailed.model_dump_json(indent=2))
+```
+
+---
+
+## API Reference
+
+### `JaegerClient`
+
+| Method | Description |
+| -------- | ----------- |
+| `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}`). |
+
+### `search()` Parameters
+
+The `search()` method now uses a flattened parameter structure:
+
+| 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. |
+
+### Filter Logic
+
+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
+)
+```
+
+---
+
+## Compatibility
+
+The implementation targets **Jaeger v1.x** REST endpoints. For clusters
+backed by **OpenSearch** storage the same endpoints apply. Should you
+need API v3 support feel free to open an issue or contribution—thanks!
+
+---
+
+## License
+
+This package is released under the **MIT license**.

veris_ai-1.3.0/src/veris_ai/jaeger_interface/__init__.py

@@ -0,0 +1,39 @@
+"""Jaeger interface for searching and retrieving traces.
+
+This sub-package provides a thin synchronous wrapper around the Jaeger
+Query Service HTTP API with client-side span filtering capabilities.
+
+Typical usage example::
+
+    from veris_ai.jaeger_interface import JaegerClient
+
+    client = JaegerClient("http://localhost:16686")
+
+    # Search traces with trace-level filters
+    traces = client.search(
+        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
+are fully typed using *pydantic* models so that IDEs can provide proper
+autocomplete and type checking.
+"""
+
+from .client import JaegerClient as JaegerClient  # noqa: F401
+
+__all__ = ["JaegerClient"]

veris_ai-1.3.0/src/veris_ai/jaeger_interface/client.py

@@ -0,0 +1,236 @@
+"""Synchronous Jaeger Query Service client built on **requests**.
+
+This implementation keeps dependencies minimal while providing fully-typed
+*pydantic* models for both **request** and **response** bodies.
+"""
+
+import json
+import types
+from typing import Any, Self
+
+import requests
+
+from .models import GetTraceResponse, SearchResponse, Span, Trace
+
+__all__ = ["JaegerClient"]
+
+
+class JaegerClient:  # noqa: D101
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float | None = 10.0,
+        session: requests.Session | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Create a new *JaegerClient* instance.
+
+        Args:
+            base_url: Base URL of the Jaeger Query Service (e.g. ``http://localhost:16686``).
+            timeout: Request timeout in **seconds** (applied to every call).
+            session: Optional pre-configured :class:`requests.Session` to reuse.
+            headers: Optional default headers to send with every request.
+        """
+        # Normalise to avoid trailing slash duplicates
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._external_session = session  # If provided we won't close it
+        self._headers = headers or {}
+
+    # ---------------------------------------------------------------------
+    # Internal helpers
+    # ---------------------------------------------------------------------
+
+    def _make_session(self) -> tuple[requests.Session, bool]:  # noqa: D401
+        """Return a *(session, should_close)* tuple.
+
+        If an external session was supplied we **must not** close it after the
+        request, hence the boolean flag letting callers know whether they are
+        responsible for closing the session.
+        """
+        if self._external_session is not None:
+            return self._external_session, False
+
+        # Reuse the session opened via the context manager if available
+        if hasattr(self, "_session_ctx"):
+            return self._session_ctx, False
+
+        session = requests.Session()
+        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(  # 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:
+            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
+            with spans filtered according to span_tags if provided.
+        """
+        # 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"
+            response = session.get(url, params=params, timeout=self._timeout)
+            response.raise_for_status()
+            data = response.json()
+        finally:
+            if should_close:
+                session.close()
+
+        # 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*.
+
+        Args:
+            trace_id: The Jaeger trace identifier.
+
+        Returns:
+            Parsed :class:`~veris_ai.jaeger_interface.models.GetTraceResponse` model.
+        """
+        if not trace_id:
+            error_msg = "trace_id must be non-empty"
+            raise ValueError(error_msg)
+
+        session, should_close = self._make_session()
+        try:
+            url = f"{self._base_url}/api/traces/{trace_id}"
+            response = session.get(url, timeout=self._timeout)
+            response.raise_for_status()
+            data = response.json()
+        finally:
+            if should_close:
+                session.close()
+        return GetTraceResponse.model_validate(data)  # type: ignore[arg-type]
+
+    # ------------------------------------------------------------------
+    # Context-manager helpers (optional but convenient)
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        self._session_ctx, self._should_close_ctx = self._make_session()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        """Exit the context manager."""
+        # Only close if we created the session
+        if getattr(self, "_should_close_ctx", False):
+            self._session_ctx.close()

veris_ai-1.3.0/src/veris_ai/jaeger_interface/models.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "Tag",
+    "Process",
+    "Span",
+    "Trace",
+    "SearchResponse",
+    "GetTraceResponse",
+]
+
+
+class Tag(BaseModel):
+    """A Jaeger tag key/value pair."""
+
+    key: str
+    value: Any
+    type: str | None = None  # Jaeger uses an optional *type* field in v1
+
+
+class Process(BaseModel):
+    """Represents the *process* section of a Jaeger trace."""
+
+    serviceName: str = Field(alias="serviceName")  # noqa: N815
+    tags: list[Tag] | None = None
+
+
+class Span(BaseModel):
+    """Represents a single Jaeger span."""
+
+    traceID: str  # noqa: N815
+    spanID: str  # noqa: N815
+    operationName: str  # noqa: N815
+    startTime: int  # noqa: N815
+    duration: int
+    tags: list[Tag] | None = None
+    references: list[dict[str, Any]] | None = None
+    processID: str | None = None  # noqa: N815
+
+    model_config = ConfigDict(extra="allow")
+
+
+class Trace(BaseModel):
+    """A full Jaeger trace as returned by the Query API."""
+
+    traceID: str  # noqa: N815
+    spans: list[Span]
+    process: Process | dict[str, Process] | None = None
+    warnings: list[str] | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class _BaseResponse(BaseModel):
+    data: list[Trace] | Trace | None = None
+    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.
+
+    model_config = ConfigDict(extra="allow")
+
+
+class SearchResponse(_BaseResponse):
+    """Response model for *search* or *find traces* requests."""
+
+    total: int | None = None
+    limit: int | None = None
+
+
+class GetTraceResponse(_BaseResponse):
+    """Response model for *get trace by id* requests."""
+
+    # Same as base but alias for clarity

veris_ai-1.3.0/src/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"