traceAI-exa 0.1.0__tar.gz

traceai_exa-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: traceAI-exa
+Version: 0.1.0
+Summary: OpenTelemetry instrumentation for Exa
+License: Apache-2.0
+Keywords: traceai,futureagi,opentelemetry,tracing,observability,llm,exa
+Author: Future AGI
+Author-email: no-reply@futureagi.com
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: OpenTelemetry
+Classifier: Framework :: OpenTelemetry :: Instrumentations
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: exa-py (>=2.25.0,<3)
+Requires-Dist: fi-instrumentation-otel (>=1.1.0)
+Requires-Dist: wrapt (>=1.0.0)
+Project-URL: Changelog, https://github.com/future-agi/traceAI/blob/dev/python/frameworks/exa/CHANGELOG.md
+Project-URL: Documentation, https://docs.futureagi.com/docs/tracing
+Project-URL: Homepage, https://futureagi.com
+Project-URL: Issues, https://github.com/future-agi/traceAI/issues
+Project-URL: Repository, https://github.com/future-agi/traceAI/tree/dev/python/frameworks/exa
+Description-Content-Type: text/markdown
+
+# traceAI-exa
+
+OpenTelemetry instrumentation for the [`exa-py`](https://github.com/exa-labs/exa-py) client.
+
+This package wraps Exa client calls; it is not an Exa exporter. Exa does not publish an exporter.
+
+## Installation
+
+```bash
+pip install traceAI-exa
+```
+
+It accepts `exa-py>=2.25.0,<3` and is tested with `exa-py` 2.25.0 on Python
+3.10, 3.11, 3.12 and 3.13. The test suite also passes on `exa-py` 2.26.0.
+
+Live vendor verification (2026-10-17): a real run against `api.exa.ai` with
+`exa-py` 2.25.0 (`search`, `get_contents`, `answer`, both streams, `AsyncExa.search`
+and an invalid-key 401 recorded as ERROR) exported the expected spans to Future
+AGI, and `FI_HIDE_INPUTS=true` kept the query out of every stored column.
+
+## Usage
+
+```python
+from exa_py import Exa
+from fi_instrumentation import register
+from fi_instrumentation.fi_types import ProjectType
+from traceai_exa import ExaInstrumentor
+
+tracer_provider = register(project_name="exa-search", project_type=ProjectType.OBSERVE)
+ExaInstrumentor().instrument(tracer_provider=tracer_provider)
+
+client = Exa(api_key="your-exa-api-key")
+client.search("recent retrieval research", num_results=5)
+```
+
+## Instrumented calls
+
+`Exa` and `AsyncExa` calls to `search`, `get_contents`, `answer`, and the
+deprecated `search_and_contents` alias (traced as `exa.search`) each produce
+one span. `stream_search` and `stream_answer` produce one span that stays open
+until the stream is fully read, closed, or garbage-collected; the returned
+object is still an instance of the vendor's stream class. A stream still open
+when the interpreter exits is ended as cancelled before `register()`'s exit
+hook shuts the exporter down (when `instrument()` runs after `register()`).
+
+`gen_ai.span.kind` is `RETRIEVER` for `search`, `answer` and the two streams,
+and `TOOL` for `get_contents`, which fetches the pages you name rather than
+searching. Each span is a child of the active span
+when there is one, and a root span otherwise. The span is current while
+exa-py sends the request, so a span from an HTTP client instrumentation nests
+under it.
+
+## Span attributes
+
+| Attribute | Calls | Value |
+|---|---|---|
+| `gen_ai.retrieval.query`, `input.value` | `search`, `answer`, streams | The query, with the client's Exa API key replaced by `[redacted]`, cut to 1 KB of UTF-8 on a character boundary. |
+| `exa.url_count` | `get_contents` | Number of requested URLs (a single URL, a list of URLs, or a list of results). |
+| `exa.urls` | `get_contents` with `capture_urls=True` | See [get_contents URLs](#get_contents-urls). |
+| `exa.result_count` | successful calls | `results` for `search` and `get_contents`, `citations` for `answer`, and the citations summed over every chunk of a fully read stream. Absent when the count is unknown (an error or a cancellation), never 0 for unknown. |
+| `exa.cancelled` | cancelled calls and streams | `true`; see [Errors and cancellation](#errors-and-cancellation). |
+
+The spans never carry response content: no result titles, text, highlights or
+summaries, no answer or stream text, no cost, token count or model name. There
+is no setting that adds them. The Exa API key is never recorded; it is
+replaced by `[redacted]` wherever it appears verbatim in a recorded query, URL
+or error text.
+
+### get_contents URLs
+
+`get_contents` spans record the number of requested URLs, not the URLs,
+because URLs can carry tokens or personal data. To record the URLs as well,
+opt in when instrumenting:
+
+```python
+ExaInstrumentor().instrument(tracer_provider=tracer_provider, capture_urls=True)
+```
+
+With `capture_urls=True`, `exa.urls` holds at most the first 20
+requested URLs, each with the Exa API key replaced by `[redacted]` and cut to
+1 KB. Query strings are otherwise kept as given. Hidden inputs (below) turn
+URL capture off.
+
+## Trace config and context
+
+Spans are created through `fi_instrumentation`'s `FITracer`, as in the other
+traceAI instrumentors. Pass a `TraceConfig` to `instrument()`, or set the
+matching `FI_*` environment variables; without `config`, the environment is
+read when `instrument()` runs.
+
+```python
+from fi_instrumentation import TraceConfig
+
+ExaInstrumentor().instrument(
+    tracer_provider=tracer_provider, config=TraceConfig(hide_inputs=True)
+)
+```
+
+With `hide_inputs=True` (or `FI_HIDE_INPUTS=true`), `input.value` is
+`__REDACTED__`, `gen_ai.retrieval.query` and `exa.urls` are not recorded,
+and the query or the requested URLs are replaced by `__REDACTED__` in error
+text. The URL and result counts stay. `pii_redaction` applies to the recorded
+attributes and to the error text described below, and
+`using_session`, `using_user`, `using_metadata` and `using_tags` attributes are
+added to the Exa spans.
+
+## Errors and cancellation
+
+An error raised by exa-py (for example `ValueError` for an HTTP 4xx/5xx
+response) sets the span status to ERROR and records an exception event. The
+exception is re-raised unchanged.
+
+exa-py puts the server's response body in its error message, and a body can
+repeat the request. On the span, the status description
+(`<ExceptionType>: <message>`) and the event's `exception.message` therefore
+have the Exa key replaced by `[redacted]` (and, with hidden inputs, the query
+or the requested URLs by `__REDACTED__`; with `pii_redaction`, PII by tokens such
+as `<EMAIL_ADDRESS>`) and the message cut to 1 KB of UTF-8.
+If the exception's own `str()` fails, the span records only its type. The event carries
+`exception.type` and `exception.message` only: no `exception.stacktrace` is
+exported, because frames hold local file paths, user names and host names.
+Chained exceptions' messages are not copied. Only verbatim
+copies are found: an escaped, normalised or truncated echo of the key, query or
+URLs (for example a JSON-escaped `\/` or a percent-encoded URL) is not.
+
+Closing a stream before its last chunk (`close()` or `aclose()`), dropping it
+mid-iteration, or cancelling an `AsyncExa` call or stream ends the span with
+status ERROR, description `cancelled`, and `exa.cancelled` = `true`.
+
+A traced `AsyncExa` stream always has `aclose()`, which ends the span and closes
+the HTTP response. exa-py's own async streams have `aclose()` from 2.26.0 only;
+2.25.0's have none. On both versions their `close()` raises `RuntimeError`
+(traced or not; the span is ended first). Code that must also run on exa-py
+2.25.0 without this instrumentor can call `aclose()` only when it exists, for
+example `aclose = getattr(stream, "aclose", None)`.
+
+A missing API key raises `ValueError` in `Exa()` or `AsyncExa()` itself,
+before any traced method runs, so no span is recorded for it.
+
+`find_similar` and `find_similar_and_contents` are not traced.
+
+Do not use this package together with another instrumentor that wraps the same
+Exa client methods, or duplicate spans may result.
+

traceai_exa-0.1.0/README.md

@@ -0,0 +1,143 @@
+# traceAI-exa
+
+OpenTelemetry instrumentation for the [`exa-py`](https://github.com/exa-labs/exa-py) client.
+
+This package wraps Exa client calls; it is not an Exa exporter. Exa does not publish an exporter.
+
+## Installation
+
+```bash
+pip install traceAI-exa
+```
+
+It accepts `exa-py>=2.25.0,<3` and is tested with `exa-py` 2.25.0 on Python
+3.10, 3.11, 3.12 and 3.13. The test suite also passes on `exa-py` 2.26.0.
+
+Live vendor verification (2026-10-17): a real run against `api.exa.ai` with
+`exa-py` 2.25.0 (`search`, `get_contents`, `answer`, both streams, `AsyncExa.search`
+and an invalid-key 401 recorded as ERROR) exported the expected spans to Future
+AGI, and `FI_HIDE_INPUTS=true` kept the query out of every stored column.
+
+## Usage
+
+```python
+from exa_py import Exa
+from fi_instrumentation import register
+from fi_instrumentation.fi_types import ProjectType
+from traceai_exa import ExaInstrumentor
+
+tracer_provider = register(project_name="exa-search", project_type=ProjectType.OBSERVE)
+ExaInstrumentor().instrument(tracer_provider=tracer_provider)
+
+client = Exa(api_key="your-exa-api-key")
+client.search("recent retrieval research", num_results=5)
+```
+
+## Instrumented calls
+
+`Exa` and `AsyncExa` calls to `search`, `get_contents`, `answer`, and the
+deprecated `search_and_contents` alias (traced as `exa.search`) each produce
+one span. `stream_search` and `stream_answer` produce one span that stays open
+until the stream is fully read, closed, or garbage-collected; the returned
+object is still an instance of the vendor's stream class. A stream still open
+when the interpreter exits is ended as cancelled before `register()`'s exit
+hook shuts the exporter down (when `instrument()` runs after `register()`).
+
+`gen_ai.span.kind` is `RETRIEVER` for `search`, `answer` and the two streams,
+and `TOOL` for `get_contents`, which fetches the pages you name rather than
+searching. Each span is a child of the active span
+when there is one, and a root span otherwise. The span is current while
+exa-py sends the request, so a span from an HTTP client instrumentation nests
+under it.
+
+## Span attributes
+
+| Attribute | Calls | Value |
+|---|---|---|
+| `gen_ai.retrieval.query`, `input.value` | `search`, `answer`, streams | The query, with the client's Exa API key replaced by `[redacted]`, cut to 1 KB of UTF-8 on a character boundary. |
+| `exa.url_count` | `get_contents` | Number of requested URLs (a single URL, a list of URLs, or a list of results). |
+| `exa.urls` | `get_contents` with `capture_urls=True` | See [get_contents URLs](#get_contents-urls). |
+| `exa.result_count` | successful calls | `results` for `search` and `get_contents`, `citations` for `answer`, and the citations summed over every chunk of a fully read stream. Absent when the count is unknown (an error or a cancellation), never 0 for unknown. |
+| `exa.cancelled` | cancelled calls and streams | `true`; see [Errors and cancellation](#errors-and-cancellation). |
+
+The spans never carry response content: no result titles, text, highlights or
+summaries, no answer or stream text, no cost, token count or model name. There
+is no setting that adds them. The Exa API key is never recorded; it is
+replaced by `[redacted]` wherever it appears verbatim in a recorded query, URL
+or error text.
+
+### get_contents URLs
+
+`get_contents` spans record the number of requested URLs, not the URLs,
+because URLs can carry tokens or personal data. To record the URLs as well,
+opt in when instrumenting:
+
+```python
+ExaInstrumentor().instrument(tracer_provider=tracer_provider, capture_urls=True)
+```
+
+With `capture_urls=True`, `exa.urls` holds at most the first 20
+requested URLs, each with the Exa API key replaced by `[redacted]` and cut to
+1 KB. Query strings are otherwise kept as given. Hidden inputs (below) turn
+URL capture off.
+
+## Trace config and context
+
+Spans are created through `fi_instrumentation`'s `FITracer`, as in the other
+traceAI instrumentors. Pass a `TraceConfig` to `instrument()`, or set the
+matching `FI_*` environment variables; without `config`, the environment is
+read when `instrument()` runs.
+
+```python
+from fi_instrumentation import TraceConfig
+
+ExaInstrumentor().instrument(
+    tracer_provider=tracer_provider, config=TraceConfig(hide_inputs=True)
+)
+```
+
+With `hide_inputs=True` (or `FI_HIDE_INPUTS=true`), `input.value` is
+`__REDACTED__`, `gen_ai.retrieval.query` and `exa.urls` are not recorded,
+and the query or the requested URLs are replaced by `__REDACTED__` in error
+text. The URL and result counts stay. `pii_redaction` applies to the recorded
+attributes and to the error text described below, and
+`using_session`, `using_user`, `using_metadata` and `using_tags` attributes are
+added to the Exa spans.
+
+## Errors and cancellation
+
+An error raised by exa-py (for example `ValueError` for an HTTP 4xx/5xx
+response) sets the span status to ERROR and records an exception event. The
+exception is re-raised unchanged.
+
+exa-py puts the server's response body in its error message, and a body can
+repeat the request. On the span, the status description
+(`<ExceptionType>: <message>`) and the event's `exception.message` therefore
+have the Exa key replaced by `[redacted]` (and, with hidden inputs, the query
+or the requested URLs by `__REDACTED__`; with `pii_redaction`, PII by tokens such
+as `<EMAIL_ADDRESS>`) and the message cut to 1 KB of UTF-8.
+If the exception's own `str()` fails, the span records only its type. The event carries
+`exception.type` and `exception.message` only: no `exception.stacktrace` is
+exported, because frames hold local file paths, user names and host names.
+Chained exceptions' messages are not copied. Only verbatim
+copies are found: an escaped, normalised or truncated echo of the key, query or
+URLs (for example a JSON-escaped `\/` or a percent-encoded URL) is not.
+
+Closing a stream before its last chunk (`close()` or `aclose()`), dropping it
+mid-iteration, or cancelling an `AsyncExa` call or stream ends the span with
+status ERROR, description `cancelled`, and `exa.cancelled` = `true`.
+
+A traced `AsyncExa` stream always has `aclose()`, which ends the span and closes
+the HTTP response. exa-py's own async streams have `aclose()` from 2.26.0 only;
+2.25.0's have none. On both versions their `close()` raises `RuntimeError`
+(traced or not; the span is ended first). Code that must also run on exa-py
+2.25.0 without this instrumentor can call `aclose()` only when it exists, for
+example `aclose = getattr(stream, "aclose", None)`.
+
+A missing API key raises `ValueError` in `Exa()` or `AsyncExa()` itself,
+before any traced method runs, so no span is recorded for it.
+
+`find_similar` and `find_similar_and_contents` are not traced.
+
+Do not use this package together with another instrumentor that wraps the same
+Exa client methods, or duplicate spans may result.

traceai_exa-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[tool.poetry]
+name = "traceAI-exa"
+version = "0.1.0"
+description = "OpenTelemetry instrumentation for Exa"
+authors = ["Future AGI <no-reply@futureagi.com>"]
+readme = "README.md"
+packages = [
+    { include = "traceai_exa" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: OpenTelemetry",
+    "Framework :: OpenTelemetry :: Instrumentations",
+    "Topic :: System :: Monitoring",
+]
+license = "Apache-2.0"
+keywords = ["traceai", "futureagi", "opentelemetry", "tracing", "observability", "llm", "exa"]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.14"
+fi-instrumentation-otel = ">=1.1.0"
+exa-py = ">=2.25.0,<3"
+wrapt = ">=1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.0.0"
+pytest-asyncio = ">=0.21.0"
+
+[tool.poetry.urls]
+Homepage = "https://futureagi.com"
+Documentation = "https://docs.futureagi.com/docs/tracing"
+Repository = "https://github.com/future-agi/traceAI/tree/dev/python/frameworks/exa"
+Changelog = "https://github.com/future-agi/traceAI/blob/dev/python/frameworks/exa/CHANGELOG.md"
+Issues = "https://github.com/future-agi/traceAI/issues"
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

traceai_exa-0.1.0/traceai_exa/__init__.py

@@ -0,0 +1,141 @@
+"""OpenTelemetry instrumentation for the Exa client."""
+
+import atexit
+import logging
+from importlib import import_module
+from typing import Any, Collection, Dict, Tuple
+
+from fi_instrumentation import FITracer, TraceConfig
+from opentelemetry import trace as trace_api
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from wrapt import wrap_function_wrapper
+
+from traceai_exa._wrappers import (
+    AsyncOperationWrapper,
+    AsyncStreamWrapper,
+    OperationWrapper,
+    StreamWrapper,
+    end_open_streams,
+)
+from traceai_exa.package import _instruments
+from traceai_exa.version import __version__
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+_MODULE = "exa_py.api"
+_OPERATIONS = {
+    "search": "exa.search",
+    "get_contents": "exa.get_contents",
+    "answer": "exa.answer",
+    # The SDK keeps this deprecated alias for backwards compatibility. It is a
+    # search operation, so it deliberately shares the search span name.
+    "search_and_contents": "exa.search",
+}
+_STREAM_OPERATIONS = {
+    "stream_search": "exa.search",
+    "stream_answer": "exa.answer",
+}
+
+
+class ExaInstrumentor(BaseInstrumentor):
+    """Instrument Exa's search, contents, answer, and streaming APIs.
+
+    ``instrument()`` accepts ``tracer_provider``, ``capture_urls`` and
+    ``config`` (a ``fi_instrumentation.TraceConfig``; by default one built
+    from the ``FI_*`` environment variables, such as ``FI_HIDE_INPUTS``).
+    Spans come from an ``FITracer``, so the config's masking and PII
+    redaction apply, and ``using_session`` / ``using_user`` /
+    ``using_metadata`` attributes reach the Exa spans.
+    """
+
+    __slots__ = ("_original_methods",)
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs: Any) -> None:
+        config = kwargs.get("config")
+        if config is None:
+            config = TraceConfig()
+        elif not isinstance(config, TraceConfig):
+            raise TypeError(
+                "config must be a fi_instrumentation.TraceConfig, got {0}".format(
+                    type(config).__name__
+                )
+            )
+        tracer_provider = kwargs.get("tracer_provider") or trace_api.get_tracer_provider()
+        tracer = FITracer(
+            trace_api.get_tracer(__name__, __version__, tracer_provider), config=config
+        )
+        # Off by default: get_contents records only a URL count. With
+        # capture_urls=True it also records up to 20 requested URLs, each
+        # with the Exa key redacted and capped at 1 KB. Hidden inputs win.
+        capture_urls = bool(kwargs.get("capture_urls", False))
+        hide_inputs = bool(config.hide_inputs)
+        pii = bool(config.pii_redaction)
+        api_module = import_module(_MODULE)
+        self._original_methods: Dict[Tuple[str, str], Any] = {}
+
+        for client_name in ("Exa", "AsyncExa"):
+            is_async = client_name == "AsyncExa"
+            for method_name, span_name in _OPERATIONS.items():
+                options = {
+                    "contents": method_name == "get_contents",
+                    "capture_urls": capture_urls,
+                    "hide_inputs": hide_inputs,
+                    "pii": pii,
+                }
+                wrapper = (
+                    AsyncOperationWrapper(tracer, span_name, **options)
+                    if is_async
+                    else OperationWrapper(tracer, span_name, **options)
+                )
+                self._wrap_method(api_module, client_name, method_name, wrapper)
+
+            for method_name, span_name in _STREAM_OPERATIONS.items():
+                wrapper = (
+                    AsyncStreamWrapper(tracer, span_name, hide_inputs=hide_inputs, pii=pii)
+                    if is_async
+                    else StreamWrapper(tracer, span_name, hide_inputs=hide_inputs, pii=pii)
+                )
+                self._wrap_method(api_module, client_name, method_name, wrapper)
+
+        # register() adds an atexit hook that shuts the provider down. atexit
+        # runs hooks last-in first-out, so (re-)registering here makes open
+        # stream spans end before that shutdown, not after it.
+        atexit.unregister(end_open_streams)
+        atexit.register(end_open_streams)
+        logger.debug("Exa instrumentation enabled")
+
+    def _wrap_method(
+        self,
+        api_module: Any,
+        client_name: str,
+        method_name: str,
+        wrapper: Any,
+    ) -> None:
+        client = getattr(api_module, client_name)
+        # Only a method defined on this class itself: AsyncExa subclasses Exa,
+        # and wrapping an inherited method would wrap Exa's (already wrapped)
+        # function a second time and leave it wrapped after uninstrument().
+        original = vars(client).get(method_name)
+        if original is None:
+            return
+
+        self._original_methods[(client_name, method_name)] = original
+        wrap_function_wrapper(
+            api_module,
+            "{0}.{1}".format(client_name, method_name),
+            wrapper,
+        )
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        api_module = import_module(_MODULE)
+        for (client_name, method_name), original in self._original_methods.items():
+            setattr(getattr(api_module, client_name), method_name, original)
+        self._original_methods.clear()
+        logger.debug("Exa instrumentation disabled")
+
+
+__all__ = ["ExaInstrumentor", "__version__"]

traceai_exa-0.1.0/traceai_exa/_wrappers.py

@@ -0,0 +1,552 @@
+"""wrapt wrappers for the supported Exa client methods."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import weakref
+from typing import Any, Callable, Mapping, Optional, Sequence, Tuple
+
+import wrapt
+from fi_instrumentation import REDACTED_VALUE
+from fi_instrumentation.instrumentation.pii_redaction import redact_pii_in_string
+from opentelemetry import trace as trace_api
+from opentelemetry.trace import Span, Status, StatusCode, Tracer
+
+_SPAN_KIND = "gen_ai.span.kind"
+_INPUT_VALUE = "input.value"
+_RETRIEVAL_QUERY = "gen_ai.retrieval.query"
+_RESULT_COUNT = "exa.result_count"
+_URL_COUNT = "exa.url_count"
+_URLS = "exa.urls"
+_CANCELLED = "exa.cancelled"
+_RETRIEVER = "RETRIEVER"
+# get_contents fetches given URLs; it is not a search.
+_TOOL = "TOOL"
+_REDACTED = "[redacted]"
+_MAX_QUERY_BYTES = 1024
+_MAX_CAPTURED_URLS = 20
+
+
+def _redact(value: str, api_key: Optional[str]) -> str:
+    return value.replace(api_key, _REDACTED) if api_key else value
+
+
+class _Scrub:
+    """What must not leave the process in error text for one call.
+
+    ``api_key`` is replaced by ``[redacted]``; with hidden inputs, each
+    request input (the query, or get_contents' URLs; already key-redacted)
+    is replaced by ``__REDACTED__``, longest first; with ``pii_redaction``,
+    PII is replaced last. Only verbatim occurrences are found.
+    """
+
+    __slots__ = ("api_key", "hidden", "pii")
+
+    def __init__(
+        self, api_key: Optional[str], hidden: Sequence[str] = (), pii: bool = False
+    ) -> None:
+        self.api_key = api_key
+        self.hidden = tuple(sorted({value for value in hidden if value}, key=len, reverse=True))
+        self.pii = pii
+
+    def __call__(self, text: str) -> str:
+        text = _redact(text, self.api_key)
+        for value in self.hidden:
+            text = text.replace(value, REDACTED_VALUE)
+        if self.pii:
+            text = redact_pii_in_string(text)
+        return text
+
+
+def _query(args: Sequence[Any], kwargs: Mapping[str, Any]) -> Optional[str]:
+    """Return the search or answer query argument, never client configuration."""
+    value = kwargs.get("query")
+    if value is None and args:
+        value = args[0]
+    return None if value is None else str(value)
+
+
+def _requested_urls(args: Sequence[Any], kwargs: Mapping[str, Any]) -> Optional[list]:
+    """Return get_contents' requested URLs, or None when the shape is unknown.
+
+    exa-py accepts one URL, a list of URLs, or a list of Result objects. Only a
+    Result's ``url`` is read, so text and highlights cannot reach a span.
+    """
+    value = kwargs["urls"] if "urls" in kwargs else (args[0] if args else None)
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple)):
+        return [item if isinstance(item, str) else getattr(item, "url", None) for item in value]
+    return None
+
+
+def _request_attributes(
+    instance: Any,
+    args: Sequence[Any],
+    kwargs: Mapping[str, Any],
+    contents: bool,
+    capture_urls: bool,
+    hide_inputs: bool = False,
+    pii: bool = False,
+) -> Tuple[dict, _Scrub]:
+    attributes: dict = {_SPAN_KIND: _TOOL if contents else _RETRIEVER}
+    api_key = _api_key(instance)
+    if contents:
+        # get_contents: a URL count by default. URLs can carry tokens or
+        # personal data, so they are recorded only with capture_urls=True,
+        # and never when inputs are hidden.
+        urls = _requested_urls(args, kwargs)
+        if urls is None:
+            return attributes, _Scrub(api_key, pii=pii)
+        attributes[_URL_COUNT] = len(urls)
+        if hide_inputs:
+            # An error body can echo the URLs; hidden inputs keep them out
+            # of error text as well as attributes.
+            hidden = [_redact(url, api_key) for url in urls if isinstance(url, str)]
+            return attributes, _Scrub(api_key, hidden, pii)
+        if capture_urls:
+            attributes[_URLS] = [
+                _cap(_redact(url, api_key))
+                for url in urls[:_MAX_CAPTURED_URLS]
+                if isinstance(url, str)
+            ]
+        return attributes, _Scrub(api_key, pii=pii)
+
+    query = _query(args, kwargs)
+    if query is None:
+        return attributes, _Scrub(api_key, pii=pii)
+    if hide_inputs:
+        # FITracer masks input.value too; gen_ai.retrieval.query is not one
+        # of its keys, so it is left out here.
+        attributes[_INPUT_VALUE] = REDACTED_VALUE
+        return attributes, _Scrub(api_key, [_redact(query, api_key)], pii)
+    query = _cap(_redact(query, api_key))
+    attributes[_RETRIEVAL_QUERY] = query
+    # The backend input panel reads input.value; keep both keys.
+    attributes[_INPUT_VALUE] = query
+    return attributes, _Scrub(api_key, pii=pii)
+
+
+def _cap(value: str, limit: int = _MAX_QUERY_BYTES) -> str:
+    """Return the longest whole-character prefix of at most ``limit`` UTF-8 bytes."""
+    # A cut inside a multi-byte character leaves an invalid tail; "ignore"
+    # drops it. "replace" keeps a lone surrogate from raising in user code.
+    return value.encode("utf-8", "replace")[:limit].decode("utf-8", "ignore")
+
+
+def _api_key(instance: Any) -> Optional[str]:
+    """Return the client's Exa key so it can be removed from span values.
+
+    exa-py keeps the key only in ``headers["x-api-key"]``; ``api_key`` is a
+    fallback for clients that expose it as an attribute.
+    """
+    key = None
+    headers = getattr(instance, "headers", None)
+    if isinstance(headers, Mapping):
+        key = headers.get("x-api-key")
+    if not key:
+        key = getattr(instance, "api_key", None)
+    return key if isinstance(key, str) and key else None
+
+
+def _document_count(result: Any) -> Optional[int]:
+    """Count returned documents without inspecting their content.
+
+    SearchResponse (search, get_contents) has ``results``; AnswerResponse has
+    ``citations``. Anything else is an unknown count: None, never 0.
+    """
+    for name in ("results", "citations"):
+        documents = getattr(result, name, None)
+        if documents is not None:
+            try:
+                return len(documents)
+            except TypeError:
+                return None
+    return None
+
+
+def _chunk_citations(chunk: Any) -> int:
+    """Citations carried by one StreamChunk (stream_search / stream_answer)."""
+    try:
+        return len(getattr(chunk, "citations", None) or ())
+    except TypeError:
+        return 0
+
+
+class _BaseWrapper:
+    def __init__(
+        self,
+        tracer: Tracer,
+        span_name: str,
+        *,
+        contents: bool = False,
+        capture_urls: bool = False,
+        hide_inputs: bool = False,
+        pii: bool = False,
+    ) -> None:
+        self._tracer = tracer
+        self._span_name = span_name
+        self._contents = contents
+        self._capture_urls = capture_urls
+        self._hide_inputs = hide_inputs
+        self._pii = pii
+
+    def _start_span(
+        self, instance: Any, args: Sequence[Any], kwargs: Mapping[str, Any]
+    ) -> Tuple[Optional[Span], Optional[_Scrub]]:
+        """Start the span; (None, None) runs the call untraced."""
+        scrub: Optional[_Scrub]
+        try:
+            attributes, scrub = _request_attributes(
+                instance,
+                args,
+                kwargs,
+                self._contents,
+                self._capture_urls,
+                self._hide_inputs,
+                self._pii,
+            )
+        except Exception:  # an attribute must never break the user's call
+            # Unknown key and query: error text is withheld (see _error_text).
+            attributes = {_SPAN_KIND: _TOOL if self._contents else _RETRIEVER}
+            scrub = None
+        try:
+            return self._tracer.start_span(self._span_name, attributes=attributes), scrub
+        except Exception:  # a tracer failure must never reach the caller
+            return None, None
+
+    @staticmethod
+    def _finish_ok(span: Span, document_count: Optional[int]) -> None:
+        try:
+            if document_count is not None:
+                span.set_attribute(_RESULT_COUNT, document_count)
+            span.set_status(Status(StatusCode.OK))
+        except Exception:
+            pass
+        finally:
+            span.end()
+
+    @staticmethod
+    def _finish_error(span: Span, error: BaseException, scrub: Optional[_Scrub]) -> None:
+        # No document count: nothing was returned, so the count is unknown.
+        # The event is built here rather than by span.record_exception(),
+        # which calls str(error) unguarded; the span must end whatever the
+        # error's str() does, and the caller's exception must stay the same.
+        try:
+            description, event = _error_text(error, scrub)
+            event["exception.type"] = _exception_type(error)
+            event["exception.escaped"] = "False"
+            span.add_event("exception", attributes=event)
+            span.set_status(Status(StatusCode.ERROR, description))
+        except Exception:
+            pass
+        finally:
+            span.end()
+
+    @staticmethod
+    def _finish_cancelled(span: Span) -> None:
+        # Cancellation is not an exception: no event and no document count.
+        span.set_attribute(_CANCELLED, True)
+        span.set_status(Status(StatusCode.ERROR, "cancelled"))
+        span.end()
+
+
+def _exception_type(error: BaseException) -> str:
+    """The exception type as the OpenTelemetry SDK's record_exception names it."""
+    module = type(error).__module__
+    qualname = type(error).__qualname__
+    return "{0}.{1}".format(module, qualname) if module and module != "builtins" else qualname
+
+
+def _error_text(error: BaseException, scrub: Optional[_Scrub]) -> Tuple[str, dict]:
+    """The status description and exception-event text for ``error``.
+
+    exa-py copies the server's response body into its exceptions, and a body
+    can repeat the request. The key (and, with hidden inputs, the query) is
+    removed and the message is capped at 1 KB; the caller's exception object
+    is not changed. No stack trace is exported: frames carry local file paths
+    (and so usernames and hostnames), and chained exceptions' text.
+    """
+    name = type(error).__name__
+    if scrub is None:
+        return name, {"exception.message": _REDACTED}
+    try:
+        message = _cap(scrub(str(error)))
+    except Exception:
+        return name, {"exception.message": _REDACTED}
+    description = "{0}: {1}".format(name, message) if message else name
+    return description, {"exception.message": message}
+
+
+def _current(span: Span) -> Any:
+    """Make ``span`` current for the vendor call so HTTP client spans nest under it.
+
+    The span is ended by the wrapper, not on exit, and errors are recorded once
+    by ``_finish_error``.
+    """
+    return trace_api.use_span(
+        span, end_on_exit=False, record_exception=False, set_status_on_exception=False
+    )
+
+
+class OperationWrapper(_BaseWrapper):
+    """Trace a synchronous Exa operation."""
+
+    def __call__(
+        self,
+        wrapped: Callable[..., Any],
+        instance: Any,
+        args: tuple,
+        kwargs: Mapping[str, Any],
+    ) -> Any:
+        span, scrub = self._start_span(instance, args, kwargs)
+        if span is None:
+            return wrapped(*args, **kwargs)
+        try:
+            with _current(span):
+                result = wrapped(*args, **kwargs)
+        except BaseException as error:
+            self._finish_error(span, error, scrub)
+            raise
+        self._finish_ok(span, _document_count(result))
+        return result
+
+
+class AsyncOperationWrapper(_BaseWrapper):
+    """Trace an asynchronous Exa operation."""
+
+    async def __call__(
+        self,
+        wrapped: Callable[..., Any],
+        instance: Any,
+        args: tuple,
+        kwargs: Mapping[str, Any],
+    ) -> Any:
+        span, scrub = self._start_span(instance, args, kwargs)
+        if span is None:
+            return await wrapped(*args, **kwargs)
+        try:
+            with _current(span):
+                result = await wrapped(*args, **kwargs)
+        except asyncio.CancelledError:
+            self._finish_cancelled(span)
+            raise
+        except BaseException as error:
+            self._finish_error(span, error, scrub)
+            raise
+        self._finish_ok(span, _document_count(result))
+        return result
+
+
+# Stream spans not yet ended. A stream still referenced at interpreter exit
+# is finalised after atexit hooks, when the exporter is already shut down, so
+# end_open_streams() ends these first (see ExaInstrumentor._instrument).
+_OPEN_STREAMS: "weakref.WeakSet[_StreamState]" = weakref.WeakSet()
+
+
+def end_open_streams() -> None:
+    """End every still-open stream span as cancelled; registered with atexit."""
+    for state in list(_OPEN_STREAMS):
+        try:
+            state.cancelled()
+        except Exception:  # exit must not fail because of tracing
+            pass
+
+
+class _StreamState:
+    """Ends one stream span exactly once; counts citations as chunks arrive."""
+
+    def __init__(self, span: Span, scrub: Optional[_Scrub]) -> None:
+        self.span = span
+        self.scrub = scrub
+        self.finished = False
+        # Citations accumulate over chunks; the total is known only at the end.
+        self.citations = 0
+        _OPEN_STREAMS.add(self)
+
+    def observe(self, chunk: Any) -> None:
+        self.citations += _chunk_citations(chunk)
+
+    def _claim(self) -> bool:
+        if self.finished:
+            return False
+        self.finished = True
+        _OPEN_STREAMS.discard(self)
+        return True
+
+    def ok(self) -> None:
+        if self._claim():
+            _BaseWrapper._finish_ok(self.span, self.citations)
+
+    def error(self, error: BaseException) -> None:
+        if self._claim():
+            _BaseWrapper._finish_error(self.span, error, self.scrub)
+
+    def cancelled(self) -> None:
+        if self._claim():
+            _BaseWrapper._finish_cancelled(self.span)
+
+
+def _state_of(proxy: Any) -> Optional[_StreamState]:
+    # A proxy whose __init__ failed has no state; __del__ must not raise.
+    try:
+        return proxy._self_state
+    except Exception:
+        return None
+
+
+class _TracedStream(wrapt.ObjectProxy):  # type: ignore[misc]
+    """A StreamSearchResponse/StreamAnswerResponse that ends its span.
+
+    An ObjectProxy, so ``isinstance`` against the vendor class still holds.
+    """
+
+    def __init__(self, response: Any, span: Span, scrub: Optional[_Scrub]) -> None:
+        super().__init__(response)
+        self._self_state = _StreamState(span, scrub)
+        self._self_iterator = None
+
+    def __iter__(self) -> "_TracedStream":
+        return self
+
+    def __next__(self) -> Any:
+        state = self._self_state
+        try:
+            if self._self_iterator is None:
+                self._self_iterator = iter(self.__wrapped__)
+            chunk = next(self._self_iterator)
+        except StopIteration:
+            state.ok()
+            raise
+        except BaseException as error:
+            state.error(error)
+            raise
+        state.observe(chunk)
+        return chunk
+
+    def close(self) -> None:
+        """End the span as cancelled (no-op after completion), then close."""
+        self._self_state.cancelled()
+        try:
+            close = getattr(self._self_iterator, "close", None)
+            if close is not None:
+                close()
+        finally:
+            self.__wrapped__.close()
+
+    def __del__(self) -> None:
+        state = _state_of(self)
+        if state is not None:
+            state.cancelled()
+
+
+class StreamWrapper(_BaseWrapper):
+    """Trace a synchronous Exa stream for its full iterator lifetime."""
+
+    def __call__(
+        self,
+        wrapped: Callable[..., Any],
+        instance: Any,
+        args: tuple,
+        kwargs: Mapping[str, Any],
+    ) -> Any:
+        span, scrub = self._start_span(instance, args, kwargs)
+        if span is None:
+            return wrapped(*args, **kwargs)
+        try:
+            with _current(span):
+                response = wrapped(*args, **kwargs)
+        except BaseException as error:
+            self._finish_error(span, error, scrub)
+            raise
+        return _TracedStream(response, span, scrub)
+
+
+class _TracedAsyncStream(wrapt.ObjectProxy):  # type: ignore[misc]
+    """An AsyncStreamSearchResponse/AsyncStreamAnswerResponse that ends its span."""
+
+    def __init__(self, response: Any, span: Span, scrub: Optional[_Scrub]) -> None:
+        super().__init__(response)
+        self._self_state = _StreamState(span, scrub)
+        self._self_iterator = None
+
+    def __aiter__(self) -> "_TracedAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        state = self._self_state
+        try:
+            if self._self_iterator is None:
+                self._self_iterator = self.__wrapped__.__aiter__()
+            chunk = await self._self_iterator.__anext__()
+        except StopAsyncIteration:
+            state.ok()
+            raise
+        except asyncio.CancelledError:
+            state.cancelled()
+            raise
+        except BaseException as error:
+            state.error(error)
+            raise
+        state.observe(chunk)
+        return chunk
+
+    def close(self) -> None:
+        """End the span as cancelled, then delegate to the vendor's close().
+
+        exa-py's async close() raises RuntimeError (2.25.0: httpx's sync close on an
+        async response; 2.26.0: a pointer to aclose()); that outcome is the vendor's
+        and is not changed.
+        """
+        self._self_state.cancelled()
+        self.__wrapped__.close()
+
+    async def aclose(self) -> None:
+        """End the span as cancelled, then release the HTTP response."""
+        self._self_state.cancelled()
+        try:
+            close = getattr(self._self_iterator, "aclose", None)
+            if close is not None:
+                await close()
+        finally:
+            # exa-py 2.26.0 has aclose(); 2.25.0 has none, but its httpx response does.
+            response_close = getattr(self.__wrapped__, "aclose", None)
+            if response_close is None:
+                raw_response = getattr(self.__wrapped__, "_raw_response", None)
+                response_close = getattr(raw_response, "aclose", None)
+            if response_close is not None:
+                await response_close()
+
+    def __del__(self) -> None:
+        state = _state_of(self)
+        if state is not None:
+            state.cancelled()
+
+
+class AsyncStreamWrapper(_BaseWrapper):
+    """Trace an asynchronous Exa stream for its full iterator lifetime."""
+
+    async def __call__(
+        self,
+        wrapped: Callable[..., Any],
+        instance: Any,
+        args: tuple,
+        kwargs: Mapping[str, Any],
+    ) -> Any:
+        span, scrub = self._start_span(instance, args, kwargs)
+        if span is None:
+            response = wrapped(*args, **kwargs)
+            return await response if inspect.isawaitable(response) else response
+        try:
+            with _current(span):
+                response = wrapped(*args, **kwargs)
+                if inspect.isawaitable(response):
+                    response = await response
+        except asyncio.CancelledError:
+            self._finish_cancelled(span)
+            raise
+        except BaseException as error:
+            self._finish_error(span, error, scrub)
+            raise
+        return _TracedAsyncStream(response, span, scrub)

traceai_exa-0.1.0/traceai_exa/package.py

@@ -0,0 +1,2 @@
+# Tested against exa-py 2.25.0; any later 2.x is accepted.
+_instruments = ("exa-py >= 2.25.0, < 3",)

traceai_exa-0.1.0/traceai_exa/py.typed

@@ -0,0 +1 @@
+

traceai_exa-0.1.0/traceai_exa/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"  # x-release-please-version