acceldata-aio-tracer 0.1.0.dev1__tar.gz

acceldata_aio_tracer-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.1
+Name: acceldata-aio-tracer
+Version: 0.1.0.dev1
+Summary: Acceldata LLM observability SDK
+License: Apache-2.0
+Author: Acceldata
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: httpx
+Requires-Dist: opik (==1.11.3)
+Description-Content-Type: text/markdown
+
+# acceldata-aio-tracer
+
+LLM observability SDK by Acceldata, built on top of [Opik](https://github.com/comet-ml/opik). It:
+
+- Adds Acceldata `accessKey` / `secretKey` authentication to every Opik HTTP call via an httpx auth hook.
+- Re-exports the full Opik public API under the `acceldata_aio_tracer` namespace.
+- Mirrors all Opik integrations under `acceldata_aio_tracer.integrations.<framework>` so customer code never imports from `opik` directly.
+
+## Index
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+  - [Signature stability](#signature-stability)
+  - [Programmatic (`configure`)](#programmatic-configure)
+  - [Explicit client (`AcceldataTracer`)](#explicit-client-acceldatatracer)
+  - [Environment variables](#environment-variables)
+  - [Auto-init from env](#auto-init-from-env)
+- [Authentication](#authentication)
+- [Integrations](#integrations)
+  - [Decorator-style integrations](#decorator-style-integrations)
+  - [Callback / handler-style integrations](#callback--handler-style-integrations)
+  - [Integration reference](#integration-reference)
+- [Adding a new integration](#adding-a-new-integration)
+- [Debugging](#debugging)
+- [License](#license)
+
+## Installation
+
+```bash
+pip install acceldata-aio-tracer
+```
+
+Requires Python 3.10+. A pinned `opik` version is pulled transitively — do not install `opik` separately at a different version.
+
+## Quick start
+
+```python
+import acceldata_aio_tracer as aio
+
+aio.configure(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+    project_name="default",
+)
+
+@aio.track
+def summarize(text: str) -> str:
+    # call an LLM, return the summary
+    ...
+
+summarize("hello world")  # traced and sent to Acceldata
+```
+
+`aio.track` is the standard Opik `@track` decorator re-exported under the wrapper namespace. All other top-level Opik APIs (`opik.Opik`, `opik.flush`, etc.) are also available as `aio.Opik`, `aio.flush`, and so on.
+
+## Configuration
+
+There are two configuration entry points; pick based on usage style.
+
+### Signature stability
+
+Both `configure()` and `AcceldataTracer()` follow the same shape — three required positional-or-keyword args followed by keyword-only options:
+
+```python
+def configure(
+    url: str,                             # required, stable public name
+    access_key: str,                      # required, stable public name
+    secret_key: str,                      # required, stable public name
+    *,                                    # everything below is keyword-only
+    project_name: Optional[str] = None,   # may evolve across releases
+    debug: bool = False,                  # may evolve across releases
+    check_tls_certificate: bool = True,   # may evolve across releases
+) -> None: ...
+```
+
+What this means in practice:
+
+- **`url`, `access_key`, `secret_key` are required and will not be renamed.** Pass them positionally or by name — both forms are supported indefinitely.
+
+```python
+# Both calls are equivalent:
+aio.configure("https://acme.acceldata.local:5443/aio", "ak", "sk")
+aio.configure(url="https://acme.acceldata.local:5443/aio", access_key="ak", secret_key="sk")
+```
+
+- **All other options are keyword-only.** New options may be added, deprecated, or removed across releases without breaking existing call sites. Always pass them by name (`debug=True`, not `True`).
+- **No partial calls.** All three required args must be supplied on every call. To change only a kwarg later (e.g. project name), either call `configure()` again with the full triple, or set the underlying env var directly (`os.environ["OPIK_PROJECT_NAME"] = "..."`).
+
+### Programmatic (`configure`)
+
+Use this for workflows that rely on `@track` decorators or framework integrations — anything that creates the Opik client lazily.
+
+```python
+import acceldata_aio_tracer as aio
+
+aio.configure(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+    project_name="default",       # optional
+    debug=False,                  # optional, see Debugging
+    check_tls_certificate=True,   # set False only for self-signed dev gateways
+)
+```
+
+`configure()` sets the env vars Opik reads natively (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`) and registers the Acceldata auth hook so every subsequent Opik client carries the auth headers.
+
+### Explicit client (`AcceldataTracer`)
+
+Use this when you want a directly-constructed client (e.g. for non-decorator usage or to hold a per-request client).
+
+```python
+from acceldata_aio_tracer import AcceldataTracer
+
+client = AcceldataTracer(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+)
+# `client` is a fully-configured `opik.Opik` instance.
+```
+
+Calling `AcceldataTracer(...)` also registers the auth hook globally, so any other Opik client created later in the process (including those used by integrations) inherits the auth.
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `ACCELDATA_AIO_URL` | Acceldata gateway URL, e.g. `https://acme.acceldata.local:5443/aio` |
+| `ACCELDATA_AIO_ACCESS_KEY` | Acceldata access key |
+| `ACCELDATA_AIO_SECRET_KEY` | Acceldata secret key |
+| `ACCELDATA_AIO_PROJECT_NAME` | Default project name for traces |
+| `ACCELDATA_AIO_CHECK_TLS_CERTIFICATE` | `false` disables TLS verify on outbound Opik calls (dev / self-signed gateways only) |
+| `ACCELDATA_AIO_DEBUG` | `true` / `1` / `yes` / `on` (case-insensitive) installs the HTTP debug interceptor at import time. Off by default. Wrapper-specific — no upstream fallback. |
+
+The wrapper also respects the upstream Opik names (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`, `OPIK_CHECK_TLS_CERTIFICATE`) as a fallback. If both an `ACCELDATA_AIO_*` and its `OPIK_*` counterpart are set, the `OPIK_*` value wins — useful as an escape hatch for migration, power-user overrides, or ops scripts that already reference Opik names.
+
+At import time the wrapper prints a one-line summary to `stderr` listing which logical setting was picked from which env var name (names only, never values):
+
+```
+[acceldata_aio_tracer] env init: URL<-ACCELDATA_AIO_URL, ACCESS_KEY<-ACCELDATA_AIO_ACCESS_KEY, SECRET_KEY<-ACCELDATA_AIO_SECRET_KEY
+```
+
+### Auto-init from env
+
+If both `ACCELDATA_AIO_ACCESS_KEY` and `ACCELDATA_AIO_SECRET_KEY` (or their `OPIK_*` fallbacks) are present when the package is imported, the Acceldata auth hook is registered automatically — no `configure()` call needed.
+
+```bash
+export ACCELDATA_AIO_URL="https://acme.acceldata.local:5443/aio"
+export ACCELDATA_AIO_ACCESS_KEY="..."
+export ACCELDATA_AIO_SECRET_KEY="..."
+```
+
+```python
+import acceldata_aio_tracer  # auth hook registered, env-init summary printed to stderr
+```
+
+## Authentication
+
+Acceldata uses `accessKey` and `secretKey` HTTP headers instead of bearer tokens. The auth hook attaches these headers to every Opik HTTP request and removes any pre-existing `Authorization` header to avoid conflicts:
+
+```
+accessKey: <ACCESS_KEY>
+secretKey: <SECRET_KEY>
+```
+
+The hook is installed once per process and applies to every `httpx.Client` Opik creates afterward.
+
+## Integrations
+
+Every Opik integration is mirrored under `acceldata_aio_tracer.integrations.<framework>`. Two usage styles exist depending on the framework — pick based on the [reference table](#integration-reference) below.
+
+### Decorator-style integrations
+
+Wrap an SDK client with `track_<framework>(...)`. Tracing is automatic from that point on.
+
+```python
+from openai import OpenAI
+from acceldata_aio_tracer.integrations.openai import track_openai
+
+client = track_openai(OpenAI())
+client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "hi"}],
+)  # automatically traced
+```
+
+The same shape applies to Anthropic, AWS Bedrock, Google GenAI, AISuite, LiteLLM, CrewAI, Guardrails AI, and Harbor — substitute the framework name in both the import and the function call.
+
+### Callback / handler-style integrations
+
+Instantiate a tracer / callback / connector and pass it to the framework's callback machinery.
+
+```python
+# LangChain / LangGraph
+from acceldata_aio_tracer.integrations.langchain import LangChainTracer
+
+tracer = LangChainTracer()
+chain.invoke({"input": "..."}, config={"callbacks": [tracer]})
+```
+
+```python
+# Google ADK
+from acceldata_aio_tracer.integrations.adk import ADKTracer, track_adk_agent_recursive
+
+tracer = ADKTracer()
+track_adk_agent_recursive(my_agent, tracer)
+```
+
+```python
+# DSPy
+import dspy
+from acceldata_aio_tracer.integrations.dspy import DSPyCallback
+
+dspy.configure(callbacks=[DSPyCallback()])
+```
+
+```python
+# Haystack
+from acceldata_aio_tracer.integrations.haystack import HaystackConnector
+
+pipeline.add_component("opik", HaystackConnector())
+```
+
+```python
+# LlamaIndex
+from llama_index.core.callbacks import CallbackManager
+from acceldata_aio_tracer.integrations.llama_index import LlamaIndexCallbackHandler
+
+manager = CallbackManager([LlamaIndexCallbackHandler()])
+```
+
+### Integration reference
+
+15 Opik integrations exist; 14 are mirrored here. Sagemaker is intentionally not exposed (upstream is an internal AWS auth helper with no public API).
+
+| Integration | Import path | Exported names | Style | Renamed from upstream |
+|---|---|---|---|---|
+| LangChain / LangGraph | `acceldata_aio_tracer.integrations.langchain` | `LangChainTracer`, `track_langgraph`, `extract_current_langgraph_span_data`, `LANGGRAPH_INTERRUPT_OUTPUT_KEY`, `LANGGRAPH_RESUME_INPUT_KEY`, `LANGGRAPH_INTERRUPT_METADATA_KEY`, `LANGGRAPH_PARENT_COMMAND_METADATA_KEY` | Callback | `OpikTracer` -> `LangChainTracer` |
+| Google ADK | `acceldata_aio_tracer.integrations.adk` | `ADKTracer`, `track_adk_agent_recursive`, `build_mermaid_graph_definition` | Callback | `OpikTracer` -> `ADKTracer` |
+| DSPy | `acceldata_aio_tracer.integrations.dspy` | `DSPyCallback` | Callback | `OpikCallback` -> `DSPyCallback` |
+| Haystack | `acceldata_aio_tracer.integrations.haystack` | `HaystackConnector` | Component | `OpikConnector` -> `HaystackConnector` |
+| LlamaIndex | `acceldata_aio_tracer.integrations.llama_index` | `LlamaIndexCallbackHandler` | Callback | (already framework-named) |
+| OpenAI | `acceldata_aio_tracer.integrations.openai` | `track_openai` | Decorator | (no rename) |
+| Anthropic | `acceldata_aio_tracer.integrations.anthropic` | `track_anthropic` | Decorator | (no rename) |
+| AWS Bedrock | `acceldata_aio_tracer.integrations.bedrock` | `track_bedrock` | Decorator | (no rename) |
+| Google GenAI | `acceldata_aio_tracer.integrations.genai` | `track_genai` | Decorator | (no rename) |
+| AISuite | `acceldata_aio_tracer.integrations.aisuite` | `track_aisuite` | Decorator | (no rename) |
+| LiteLLM | `acceldata_aio_tracer.integrations.litellm` | `track_completion` | Decorator | (no rename) |
+| CrewAI | `acceldata_aio_tracer.integrations.crewai` | `track_crewai` | Decorator | (no rename) |
+| Guardrails AI | `acceldata_aio_tracer.integrations.guardrails` | `track_guardrails` | Decorator | (no rename) |
+| Harbor | `acceldata_aio_tracer.integrations.harbor` | `track_harbor`, `reset_harbor_tracking` | Decorator | (no rename) |
+
+For per-integration usage details (model versions, async patterns, edge cases, advanced config), refer to the [Opik documentation](https://www.comet.com/docs/opik/) — wrapper imports are drop-in equivalents.
+
+## Adding a new integration
+
+When upstream Opik (`opik.integrations.<name>`) ships a new integration, mirror it here:
+
+1. Inspect the upstream `__init__.py` for the public exports.
+2. Create `src/acceldata_aio_tracer/integrations/<name>.py`:
+   - **Decorator-style** (`track_<name>` function): `from opik.integrations.<name> import track_<name>` + `__all__ = ("track_<name>",)`.
+   - **Class-style with Opik prefix** (`OpikTracer`, `OpikCallback`, `OpikConnector`): rename to a framework-named class. E.g. `from opik.integrations.<name> import OpikTracer as <Framework>Tracer`.
+   - **Class-style with framework prefix** (already framework-named): pass-through re-export.
+3. Add a row to the [Integration reference](#integration-reference) table above.
+4. Smoke-test: `python -c "from acceldata_aio_tracer.integrations.<name> import *"`.
+
+The wrapper does not auto-mirror — every new upstream integration needs an explicit file.
+
+## Debugging
+
+To trace every Opik HTTP call (including a copy-paste `curl` reproducer for any 4xx/5xx response), enable debug mode:
+
+```python
+aio.configure(url=..., access_key=..., secret_key=..., debug=True)
+# or
+client = AcceldataTracer(url=..., access_key=..., secret_key=..., debug=True)
+```
+
+On a failed request, the request body is dumped to `/tmp/acceldata-aio-tracer-last-failed-request.bin` and a replay-ready `curl` command is printed to the `acceldata_aio_tracer.http_trace` logger.
+
+## License
+
+Apache-2.0. This SDK is a thin wrapper around [Opik](https://github.com/comet-ml/opik), which is also Apache-2.0 licensed.

acceldata_aio_tracer-0.1.0.dev1/README.md

@@ -0,0 +1,286 @@
+# acceldata-aio-tracer
+
+LLM observability SDK by Acceldata, built on top of [Opik](https://github.com/comet-ml/opik). It:
+
+- Adds Acceldata `accessKey` / `secretKey` authentication to every Opik HTTP call via an httpx auth hook.
+- Re-exports the full Opik public API under the `acceldata_aio_tracer` namespace.
+- Mirrors all Opik integrations under `acceldata_aio_tracer.integrations.<framework>` so customer code never imports from `opik` directly.
+
+## Index
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+  - [Signature stability](#signature-stability)
+  - [Programmatic (`configure`)](#programmatic-configure)
+  - [Explicit client (`AcceldataTracer`)](#explicit-client-acceldatatracer)
+  - [Environment variables](#environment-variables)
+  - [Auto-init from env](#auto-init-from-env)
+- [Authentication](#authentication)
+- [Integrations](#integrations)
+  - [Decorator-style integrations](#decorator-style-integrations)
+  - [Callback / handler-style integrations](#callback--handler-style-integrations)
+  - [Integration reference](#integration-reference)
+- [Adding a new integration](#adding-a-new-integration)
+- [Debugging](#debugging)
+- [License](#license)
+
+## Installation
+
+```bash
+pip install acceldata-aio-tracer
+```
+
+Requires Python 3.10+. A pinned `opik` version is pulled transitively — do not install `opik` separately at a different version.
+
+## Quick start
+
+```python
+import acceldata_aio_tracer as aio
+
+aio.configure(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+    project_name="default",
+)
+
+@aio.track
+def summarize(text: str) -> str:
+    # call an LLM, return the summary
+    ...
+
+summarize("hello world")  # traced and sent to Acceldata
+```
+
+`aio.track` is the standard Opik `@track` decorator re-exported under the wrapper namespace. All other top-level Opik APIs (`opik.Opik`, `opik.flush`, etc.) are also available as `aio.Opik`, `aio.flush`, and so on.
+
+## Configuration
+
+There are two configuration entry points; pick based on usage style.
+
+### Signature stability
+
+Both `configure()` and `AcceldataTracer()` follow the same shape — three required positional-or-keyword args followed by keyword-only options:
+
+```python
+def configure(
+    url: str,                             # required, stable public name
+    access_key: str,                      # required, stable public name
+    secret_key: str,                      # required, stable public name
+    *,                                    # everything below is keyword-only
+    project_name: Optional[str] = None,   # may evolve across releases
+    debug: bool = False,                  # may evolve across releases
+    check_tls_certificate: bool = True,   # may evolve across releases
+) -> None: ...
+```
+
+What this means in practice:
+
+- **`url`, `access_key`, `secret_key` are required and will not be renamed.** Pass them positionally or by name — both forms are supported indefinitely.
+
+```python
+# Both calls are equivalent:
+aio.configure("https://acme.acceldata.local:5443/aio", "ak", "sk")
+aio.configure(url="https://acme.acceldata.local:5443/aio", access_key="ak", secret_key="sk")
+```
+
+- **All other options are keyword-only.** New options may be added, deprecated, or removed across releases without breaking existing call sites. Always pass them by name (`debug=True`, not `True`).
+- **No partial calls.** All three required args must be supplied on every call. To change only a kwarg later (e.g. project name), either call `configure()` again with the full triple, or set the underlying env var directly (`os.environ["OPIK_PROJECT_NAME"] = "..."`).
+
+### Programmatic (`configure`)
+
+Use this for workflows that rely on `@track` decorators or framework integrations — anything that creates the Opik client lazily.
+
+```python
+import acceldata_aio_tracer as aio
+
+aio.configure(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+    project_name="default",       # optional
+    debug=False,                  # optional, see Debugging
+    check_tls_certificate=True,   # set False only for self-signed dev gateways
+)
+```
+
+`configure()` sets the env vars Opik reads natively (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`) and registers the Acceldata auth hook so every subsequent Opik client carries the auth headers.
+
+### Explicit client (`AcceldataTracer`)
+
+Use this when you want a directly-constructed client (e.g. for non-decorator usage or to hold a per-request client).
+
+```python
+from acceldata_aio_tracer import AcceldataTracer
+
+client = AcceldataTracer(
+    url="https://acme.acceldata.local:5443/aio",
+    access_key="...",
+    secret_key="...",
+)
+# `client` is a fully-configured `opik.Opik` instance.
+```
+
+Calling `AcceldataTracer(...)` also registers the auth hook globally, so any other Opik client created later in the process (including those used by integrations) inherits the auth.
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `ACCELDATA_AIO_URL` | Acceldata gateway URL, e.g. `https://acme.acceldata.local:5443/aio` |
+| `ACCELDATA_AIO_ACCESS_KEY` | Acceldata access key |
+| `ACCELDATA_AIO_SECRET_KEY` | Acceldata secret key |
+| `ACCELDATA_AIO_PROJECT_NAME` | Default project name for traces |
+| `ACCELDATA_AIO_CHECK_TLS_CERTIFICATE` | `false` disables TLS verify on outbound Opik calls (dev / self-signed gateways only) |
+| `ACCELDATA_AIO_DEBUG` | `true` / `1` / `yes` / `on` (case-insensitive) installs the HTTP debug interceptor at import time. Off by default. Wrapper-specific — no upstream fallback. |
+
+The wrapper also respects the upstream Opik names (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`, `OPIK_CHECK_TLS_CERTIFICATE`) as a fallback. If both an `ACCELDATA_AIO_*` and its `OPIK_*` counterpart are set, the `OPIK_*` value wins — useful as an escape hatch for migration, power-user overrides, or ops scripts that already reference Opik names.
+
+At import time the wrapper prints a one-line summary to `stderr` listing which logical setting was picked from which env var name (names only, never values):
+
+```
+[acceldata_aio_tracer] env init: URL<-ACCELDATA_AIO_URL, ACCESS_KEY<-ACCELDATA_AIO_ACCESS_KEY, SECRET_KEY<-ACCELDATA_AIO_SECRET_KEY
+```
+
+### Auto-init from env
+
+If both `ACCELDATA_AIO_ACCESS_KEY` and `ACCELDATA_AIO_SECRET_KEY` (or their `OPIK_*` fallbacks) are present when the package is imported, the Acceldata auth hook is registered automatically — no `configure()` call needed.
+
+```bash
+export ACCELDATA_AIO_URL="https://acme.acceldata.local:5443/aio"
+export ACCELDATA_AIO_ACCESS_KEY="..."
+export ACCELDATA_AIO_SECRET_KEY="..."
+```
+
+```python
+import acceldata_aio_tracer  # auth hook registered, env-init summary printed to stderr
+```
+
+## Authentication
+
+Acceldata uses `accessKey` and `secretKey` HTTP headers instead of bearer tokens. The auth hook attaches these headers to every Opik HTTP request and removes any pre-existing `Authorization` header to avoid conflicts:
+
+```
+accessKey: <ACCESS_KEY>
+secretKey: <SECRET_KEY>
+```
+
+The hook is installed once per process and applies to every `httpx.Client` Opik creates afterward.
+
+## Integrations
+
+Every Opik integration is mirrored under `acceldata_aio_tracer.integrations.<framework>`. Two usage styles exist depending on the framework — pick based on the [reference table](#integration-reference) below.
+
+### Decorator-style integrations
+
+Wrap an SDK client with `track_<framework>(...)`. Tracing is automatic from that point on.
+
+```python
+from openai import OpenAI
+from acceldata_aio_tracer.integrations.openai import track_openai
+
+client = track_openai(OpenAI())
+client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "hi"}],
+)  # automatically traced
+```
+
+The same shape applies to Anthropic, AWS Bedrock, Google GenAI, AISuite, LiteLLM, CrewAI, Guardrails AI, and Harbor — substitute the framework name in both the import and the function call.
+
+### Callback / handler-style integrations
+
+Instantiate a tracer / callback / connector and pass it to the framework's callback machinery.
+
+```python
+# LangChain / LangGraph
+from acceldata_aio_tracer.integrations.langchain import LangChainTracer
+
+tracer = LangChainTracer()
+chain.invoke({"input": "..."}, config={"callbacks": [tracer]})
+```
+
+```python
+# Google ADK
+from acceldata_aio_tracer.integrations.adk import ADKTracer, track_adk_agent_recursive
+
+tracer = ADKTracer()
+track_adk_agent_recursive(my_agent, tracer)
+```
+
+```python
+# DSPy
+import dspy
+from acceldata_aio_tracer.integrations.dspy import DSPyCallback
+
+dspy.configure(callbacks=[DSPyCallback()])
+```
+
+```python
+# Haystack
+from acceldata_aio_tracer.integrations.haystack import HaystackConnector
+
+pipeline.add_component("opik", HaystackConnector())
+```
+
+```python
+# LlamaIndex
+from llama_index.core.callbacks import CallbackManager
+from acceldata_aio_tracer.integrations.llama_index import LlamaIndexCallbackHandler
+
+manager = CallbackManager([LlamaIndexCallbackHandler()])
+```
+
+### Integration reference
+
+15 Opik integrations exist; 14 are mirrored here. Sagemaker is intentionally not exposed (upstream is an internal AWS auth helper with no public API).
+
+| Integration | Import path | Exported names | Style | Renamed from upstream |
+|---|---|---|---|---|
+| LangChain / LangGraph | `acceldata_aio_tracer.integrations.langchain` | `LangChainTracer`, `track_langgraph`, `extract_current_langgraph_span_data`, `LANGGRAPH_INTERRUPT_OUTPUT_KEY`, `LANGGRAPH_RESUME_INPUT_KEY`, `LANGGRAPH_INTERRUPT_METADATA_KEY`, `LANGGRAPH_PARENT_COMMAND_METADATA_KEY` | Callback | `OpikTracer` -> `LangChainTracer` |
+| Google ADK | `acceldata_aio_tracer.integrations.adk` | `ADKTracer`, `track_adk_agent_recursive`, `build_mermaid_graph_definition` | Callback | `OpikTracer` -> `ADKTracer` |
+| DSPy | `acceldata_aio_tracer.integrations.dspy` | `DSPyCallback` | Callback | `OpikCallback` -> `DSPyCallback` |
+| Haystack | `acceldata_aio_tracer.integrations.haystack` | `HaystackConnector` | Component | `OpikConnector` -> `HaystackConnector` |
+| LlamaIndex | `acceldata_aio_tracer.integrations.llama_index` | `LlamaIndexCallbackHandler` | Callback | (already framework-named) |
+| OpenAI | `acceldata_aio_tracer.integrations.openai` | `track_openai` | Decorator | (no rename) |
+| Anthropic | `acceldata_aio_tracer.integrations.anthropic` | `track_anthropic` | Decorator | (no rename) |
+| AWS Bedrock | `acceldata_aio_tracer.integrations.bedrock` | `track_bedrock` | Decorator | (no rename) |
+| Google GenAI | `acceldata_aio_tracer.integrations.genai` | `track_genai` | Decorator | (no rename) |
+| AISuite | `acceldata_aio_tracer.integrations.aisuite` | `track_aisuite` | Decorator | (no rename) |
+| LiteLLM | `acceldata_aio_tracer.integrations.litellm` | `track_completion` | Decorator | (no rename) |
+| CrewAI | `acceldata_aio_tracer.integrations.crewai` | `track_crewai` | Decorator | (no rename) |
+| Guardrails AI | `acceldata_aio_tracer.integrations.guardrails` | `track_guardrails` | Decorator | (no rename) |
+| Harbor | `acceldata_aio_tracer.integrations.harbor` | `track_harbor`, `reset_harbor_tracking` | Decorator | (no rename) |
+
+For per-integration usage details (model versions, async patterns, edge cases, advanced config), refer to the [Opik documentation](https://www.comet.com/docs/opik/) — wrapper imports are drop-in equivalents.
+
+## Adding a new integration
+
+When upstream Opik (`opik.integrations.<name>`) ships a new integration, mirror it here:
+
+1. Inspect the upstream `__init__.py` for the public exports.
+2. Create `src/acceldata_aio_tracer/integrations/<name>.py`:
+   - **Decorator-style** (`track_<name>` function): `from opik.integrations.<name> import track_<name>` + `__all__ = ("track_<name>",)`.
+   - **Class-style with Opik prefix** (`OpikTracer`, `OpikCallback`, `OpikConnector`): rename to a framework-named class. E.g. `from opik.integrations.<name> import OpikTracer as <Framework>Tracer`.
+   - **Class-style with framework prefix** (already framework-named): pass-through re-export.
+3. Add a row to the [Integration reference](#integration-reference) table above.
+4. Smoke-test: `python -c "from acceldata_aio_tracer.integrations.<name> import *"`.
+
+The wrapper does not auto-mirror — every new upstream integration needs an explicit file.
+
+## Debugging
+
+To trace every Opik HTTP call (including a copy-paste `curl` reproducer for any 4xx/5xx response), enable debug mode:
+
+```python
+aio.configure(url=..., access_key=..., secret_key=..., debug=True)
+# or
+client = AcceldataTracer(url=..., access_key=..., secret_key=..., debug=True)
+```
+
+On a failed request, the request body is dumped to `/tmp/acceldata-aio-tracer-last-failed-request.bin` and a replay-ready `curl` command is printed to the `acceldata_aio_tracer.http_trace` logger.
+
+## License
+
+Apache-2.0. This SDK is a thin wrapper around [Opik](https://github.com/comet-ml/opik), which is also Apache-2.0 licensed.

acceldata_aio_tracer-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,20 @@
+[tool.poetry]
+name = "acceldata-aio-tracer"
+version = "0.1.0.dev1"
+description = "Acceldata LLM observability SDK"
+authors = ["Acceldata"]
+license = "Apache-2.0"
+readme = "README.md"
+packages = [{ include = "acceldata_aio_tracer", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+opik = "1.11.3"
+httpx = "*"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

acceldata_aio_tracer-0.1.0.dev1/setup.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+from setuptools import setup
+
+package_dir = \
+{'': 'src'}
+
+packages = \
+['acceldata_aio_tracer', 'acceldata_aio_tracer.integrations']
+
+package_data = \
+{'': ['*']}
+
+install_requires = \
+['httpx', 'opik==1.11.3']
+
+setup_kwargs = {
+    'name': 'acceldata-aio-tracer',
+    'version': '0.1.0.dev1',
+    'description': 'Acceldata LLM observability SDK',
+    'long_description': '# acceldata-aio-tracer\n\nLLM observability SDK by Acceldata, built on top of [Opik](https://github.com/comet-ml/opik). It:\n\n- Adds Acceldata `accessKey` / `secretKey` authentication to every Opik HTTP call via an httpx auth hook.\n- Re-exports the full Opik public API under the `acceldata_aio_tracer` namespace.\n- Mirrors all Opik integrations under `acceldata_aio_tracer.integrations.<framework>` so customer code never imports from `opik` directly.\n\n## Index\n\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [Configuration](#configuration)\n  - [Signature stability](#signature-stability)\n  - [Programmatic (`configure`)](#programmatic-configure)\n  - [Explicit client (`AcceldataTracer`)](#explicit-client-acceldatatracer)\n  - [Environment variables](#environment-variables)\n  - [Auto-init from env](#auto-init-from-env)\n- [Authentication](#authentication)\n- [Integrations](#integrations)\n  - [Decorator-style integrations](#decorator-style-integrations)\n  - [Callback / handler-style integrations](#callback--handler-style-integrations)\n  - [Integration reference](#integration-reference)\n- [Adding a new integration](#adding-a-new-integration)\n- [Debugging](#debugging)\n- [License](#license)\n\n## Installation\n\n```bash\npip install acceldata-aio-tracer\n```\n\nRequires Python 3.10+. A pinned `opik` version is pulled transitively — do not install `opik` separately at a different version.\n\n## Quick start\n\n```python\nimport acceldata_aio_tracer as aio\n\naio.configure(\n    url="https://acme.acceldata.local:5443/aio",\n    access_key="...",\n    secret_key="...",\n    project_name="default",\n)\n\n@aio.track\ndef summarize(text: str) -> str:\n    # call an LLM, return the summary\n    ...\n\nsummarize("hello world")  # traced and sent to Acceldata\n```\n\n`aio.track` is the standard Opik `@track` decorator re-exported under the wrapper namespace. All other top-level Opik APIs (`opik.Opik`, `opik.flush`, etc.) are also available as `aio.Opik`, `aio.flush`, and so on.\n\n## Configuration\n\nThere are two configuration entry points; pick based on usage style.\n\n### Signature stability\n\nBoth `configure()` and `AcceldataTracer()` follow the same shape — three required positional-or-keyword args followed by keyword-only options:\n\n```python\ndef configure(\n    url: str,                             # required, stable public name\n    access_key: str,                      # required, stable public name\n    secret_key: str,                      # required, stable public name\n    *,                                    # everything below is keyword-only\n    project_name: Optional[str] = None,   # may evolve across releases\n    debug: bool = False,                  # may evolve across releases\n    check_tls_certificate: bool = True,   # may evolve across releases\n) -> None: ...\n```\n\nWhat this means in practice:\n\n- **`url`, `access_key`, `secret_key` are required and will not be renamed.** Pass them positionally or by name — both forms are supported indefinitely.\n\n```python\n# Both calls are equivalent:\naio.configure("https://acme.acceldata.local:5443/aio", "ak", "sk")\naio.configure(url="https://acme.acceldata.local:5443/aio", access_key="ak", secret_key="sk")\n```\n\n- **All other options are keyword-only.** New options may be added, deprecated, or removed across releases without breaking existing call sites. Always pass them by name (`debug=True`, not `True`).\n- **No partial calls.** All three required args must be supplied on every call. To change only a kwarg later (e.g. project name), either call `configure()` again with the full triple, or set the underlying env var directly (`os.environ["OPIK_PROJECT_NAME"] = "..."`).\n\n### Programmatic (`configure`)\n\nUse this for workflows that rely on `@track` decorators or framework integrations — anything that creates the Opik client lazily.\n\n```python\nimport acceldata_aio_tracer as aio\n\naio.configure(\n    url="https://acme.acceldata.local:5443/aio",\n    access_key="...",\n    secret_key="...",\n    project_name="default",       # optional\n    debug=False,                  # optional, see Debugging\n    check_tls_certificate=True,   # set False only for self-signed dev gateways\n)\n```\n\n`configure()` sets the env vars Opik reads natively (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`) and registers the Acceldata auth hook so every subsequent Opik client carries the auth headers.\n\n### Explicit client (`AcceldataTracer`)\n\nUse this when you want a directly-constructed client (e.g. for non-decorator usage or to hold a per-request client).\n\n```python\nfrom acceldata_aio_tracer import AcceldataTracer\n\nclient = AcceldataTracer(\n    url="https://acme.acceldata.local:5443/aio",\n    access_key="...",\n    secret_key="...",\n)\n# `client` is a fully-configured `opik.Opik` instance.\n```\n\nCalling `AcceldataTracer(...)` also registers the auth hook globally, so any other Opik client created later in the process (including those used by integrations) inherits the auth.\n\n### Environment variables\n\n| Variable | Purpose |\n|---|---|\n| `ACCELDATA_AIO_URL` | Acceldata gateway URL, e.g. `https://acme.acceldata.local:5443/aio` |\n| `ACCELDATA_AIO_ACCESS_KEY` | Acceldata access key |\n| `ACCELDATA_AIO_SECRET_KEY` | Acceldata secret key |\n| `ACCELDATA_AIO_PROJECT_NAME` | Default project name for traces |\n| `ACCELDATA_AIO_CHECK_TLS_CERTIFICATE` | `false` disables TLS verify on outbound Opik calls (dev / self-signed gateways only) |\n| `ACCELDATA_AIO_DEBUG` | `true` / `1` / `yes` / `on` (case-insensitive) installs the HTTP debug interceptor at import time. Off by default. Wrapper-specific — no upstream fallback. |\n\nThe wrapper also respects the upstream Opik names (`OPIK_URL_OVERRIDE`, `OPIK_ACCESS_KEY`, `OPIK_SECRET_KEY`, `OPIK_PROJECT_NAME`, `OPIK_CHECK_TLS_CERTIFICATE`) as a fallback. If both an `ACCELDATA_AIO_*` and its `OPIK_*` counterpart are set, the `OPIK_*` value wins — useful as an escape hatch for migration, power-user overrides, or ops scripts that already reference Opik names.\n\nAt import time the wrapper prints a one-line summary to `stderr` listing which logical setting was picked from which env var name (names only, never values):\n\n```\n[acceldata_aio_tracer] env init: URL<-ACCELDATA_AIO_URL, ACCESS_KEY<-ACCELDATA_AIO_ACCESS_KEY, SECRET_KEY<-ACCELDATA_AIO_SECRET_KEY\n```\n\n### Auto-init from env\n\nIf both `ACCELDATA_AIO_ACCESS_KEY` and `ACCELDATA_AIO_SECRET_KEY` (or their `OPIK_*` fallbacks) are present when the package is imported, the Acceldata auth hook is registered automatically — no `configure()` call needed.\n\n```bash\nexport ACCELDATA_AIO_URL="https://acme.acceldata.local:5443/aio"\nexport ACCELDATA_AIO_ACCESS_KEY="..."\nexport ACCELDATA_AIO_SECRET_KEY="..."\n```\n\n```python\nimport acceldata_aio_tracer  # auth hook registered, env-init summary printed to stderr\n```\n\n## Authentication\n\nAcceldata uses `accessKey` and `secretKey` HTTP headers instead of bearer tokens. The auth hook attaches these headers to every Opik HTTP request and removes any pre-existing `Authorization` header to avoid conflicts:\n\n```\naccessKey: <ACCESS_KEY>\nsecretKey: <SECRET_KEY>\n```\n\nThe hook is installed once per process and applies to every `httpx.Client` Opik creates afterward.\n\n## Integrations\n\nEvery Opik integration is mirrored under `acceldata_aio_tracer.integrations.<framework>`. Two usage styles exist depending on the framework — pick based on the [reference table](#integration-reference) below.\n\n### Decorator-style integrations\n\nWrap an SDK client with `track_<framework>(...)`. Tracing is automatic from that point on.\n\n```python\nfrom openai import OpenAI\nfrom acceldata_aio_tracer.integrations.openai import track_openai\n\nclient = track_openai(OpenAI())\nclient.chat.completions.create(\n    model="gpt-4o-mini",\n    messages=[{"role": "user", "content": "hi"}],\n)  # automatically traced\n```\n\nThe same shape applies to Anthropic, AWS Bedrock, Google GenAI, AISuite, LiteLLM, CrewAI, Guardrails AI, and Harbor — substitute the framework name in both the import and the function call.\n\n### Callback / handler-style integrations\n\nInstantiate a tracer / callback / connector and pass it to the framework\'s callback machinery.\n\n```python\n# LangChain / LangGraph\nfrom acceldata_aio_tracer.integrations.langchain import LangChainTracer\n\ntracer = LangChainTracer()\nchain.invoke({"input": "..."}, config={"callbacks": [tracer]})\n```\n\n```python\n# Google ADK\nfrom acceldata_aio_tracer.integrations.adk import ADKTracer, track_adk_agent_recursive\n\ntracer = ADKTracer()\ntrack_adk_agent_recursive(my_agent, tracer)\n```\n\n```python\n# DSPy\nimport dspy\nfrom acceldata_aio_tracer.integrations.dspy import DSPyCallback\n\ndspy.configure(callbacks=[DSPyCallback()])\n```\n\n```python\n# Haystack\nfrom acceldata_aio_tracer.integrations.haystack import HaystackConnector\n\npipeline.add_component("opik", HaystackConnector())\n```\n\n```python\n# LlamaIndex\nfrom llama_index.core.callbacks import CallbackManager\nfrom acceldata_aio_tracer.integrations.llama_index import LlamaIndexCallbackHandler\n\nmanager = CallbackManager([LlamaIndexCallbackHandler()])\n```\n\n### Integration reference\n\n15 Opik integrations exist; 14 are mirrored here. Sagemaker is intentionally not exposed (upstream is an internal AWS auth helper with no public API).\n\n| Integration | Import path | Exported names | Style | Renamed from upstream |\n|---|---|---|---|---|\n| LangChain / LangGraph | `acceldata_aio_tracer.integrations.langchain` | `LangChainTracer`, `track_langgraph`, `extract_current_langgraph_span_data`, `LANGGRAPH_INTERRUPT_OUTPUT_KEY`, `LANGGRAPH_RESUME_INPUT_KEY`, `LANGGRAPH_INTERRUPT_METADATA_KEY`, `LANGGRAPH_PARENT_COMMAND_METADATA_KEY` | Callback | `OpikTracer` -> `LangChainTracer` |\n| Google ADK | `acceldata_aio_tracer.integrations.adk` | `ADKTracer`, `track_adk_agent_recursive`, `build_mermaid_graph_definition` | Callback | `OpikTracer` -> `ADKTracer` |\n| DSPy | `acceldata_aio_tracer.integrations.dspy` | `DSPyCallback` | Callback | `OpikCallback` -> `DSPyCallback` |\n| Haystack | `acceldata_aio_tracer.integrations.haystack` | `HaystackConnector` | Component | `OpikConnector` -> `HaystackConnector` |\n| LlamaIndex | `acceldata_aio_tracer.integrations.llama_index` | `LlamaIndexCallbackHandler` | Callback | (already framework-named) |\n| OpenAI | `acceldata_aio_tracer.integrations.openai` | `track_openai` | Decorator | (no rename) |\n| Anthropic | `acceldata_aio_tracer.integrations.anthropic` | `track_anthropic` | Decorator | (no rename) |\n| AWS Bedrock | `acceldata_aio_tracer.integrations.bedrock` | `track_bedrock` | Decorator | (no rename) |\n| Google GenAI | `acceldata_aio_tracer.integrations.genai` | `track_genai` | Decorator | (no rename) |\n| AISuite | `acceldata_aio_tracer.integrations.aisuite` | `track_aisuite` | Decorator | (no rename) |\n| LiteLLM | `acceldata_aio_tracer.integrations.litellm` | `track_completion` | Decorator | (no rename) |\n| CrewAI | `acceldata_aio_tracer.integrations.crewai` | `track_crewai` | Decorator | (no rename) |\n| Guardrails AI | `acceldata_aio_tracer.integrations.guardrails` | `track_guardrails` | Decorator | (no rename) |\n| Harbor | `acceldata_aio_tracer.integrations.harbor` | `track_harbor`, `reset_harbor_tracking` | Decorator | (no rename) |\n\nFor per-integration usage details (model versions, async patterns, edge cases, advanced config), refer to the [Opik documentation](https://www.comet.com/docs/opik/) — wrapper imports are drop-in equivalents.\n\n## Adding a new integration\n\nWhen upstream Opik (`opik.integrations.<name>`) ships a new integration, mirror it here:\n\n1. Inspect the upstream `__init__.py` for the public exports.\n2. Create `src/acceldata_aio_tracer/integrations/<name>.py`:\n   - **Decorator-style** (`track_<name>` function): `from opik.integrations.<name> import track_<name>` + `__all__ = ("track_<name>",)`.\n   - **Class-style with Opik prefix** (`OpikTracer`, `OpikCallback`, `OpikConnector`): rename to a framework-named class. E.g. `from opik.integrations.<name> import OpikTracer as <Framework>Tracer`.\n   - **Class-style with framework prefix** (already framework-named): pass-through re-export.\n3. Add a row to the [Integration reference](#integration-reference) table above.\n4. Smoke-test: `python -c "from acceldata_aio_tracer.integrations.<name> import *"`.\n\nThe wrapper does not auto-mirror — every new upstream integration needs an explicit file.\n\n## Debugging\n\nTo trace every Opik HTTP call (including a copy-paste `curl` reproducer for any 4xx/5xx response), enable debug mode:\n\n```python\naio.configure(url=..., access_key=..., secret_key=..., debug=True)\n# or\nclient = AcceldataTracer(url=..., access_key=..., secret_key=..., debug=True)\n```\n\nOn a failed request, the request body is dumped to `/tmp/acceldata-aio-tracer-last-failed-request.bin` and a replay-ready `curl` command is printed to the `acceldata_aio_tracer.http_trace` logger.\n\n## License\n\nApache-2.0. This SDK is a thin wrapper around [Opik](https://github.com/comet-ml/opik), which is also Apache-2.0 licensed.',
+    'author': 'Acceldata',
+    'author_email': 'None',
+    'maintainer': 'None',
+    'maintainer_email': 'None',
+    'url': 'None',
+    'package_dir': package_dir,
+    'packages': packages,
+    'package_data': package_data,
+    'install_requires': install_requires,
+    'python_requires': '>=3.10,<4.0',
+}
+
+
+setup(**setup_kwargs)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/__init__.py

@@ -0,0 +1,91 @@
+from typing import Optional
+
+import opik as _opik
+from opik import *  # noqa: F401, F403
+
+from . import _opik_bridge
+from .auth import (
+    AcceldataAuth,
+    setup_acceldata_auth,
+    setup_acceldata_auth_hook,
+)
+from .client import AcceldataTracer
+
+
+def configure(
+    url: str,
+    access_key: str,
+    secret_key: str,
+    *,
+    project_name: Optional[str] = None,
+    debug: bool = False,
+    check_tls_certificate: bool = True,
+) -> None:
+    """Acceldata equivalent of opik.configure().
+
+    Registers the Acceldata auth hook so every subsequent Opik client
+    carries accessKey/secretKey headers, applies the URL/project settings,
+    and optionally installs an HTTP debug interceptor.
+
+    The first three parameters (``url``, ``access_key``, ``secret_key``) are
+    the SDK's stable public surface and may be passed positionally or by
+    name. All other options are keyword-only so future flags can be added,
+    deprecated, or removed without breaking customer call sites.
+
+    Each argument has a matching ``ACCELDATA_AIO_*`` env variable that can
+    be used instead of an explicit call. If both are present the explicit
+    argument wins; if neither, ``configure()`` cannot be skipped. Upstream
+    ``OPIK_*`` names are accepted as a fallback (see README "Environment
+    variables").
+
+    Args:
+        url: Acceldata gateway URL, e.g.
+            ``https://acme.acceldata.local:5443/aio``.
+            Env: ``ACCELDATA_AIO_URL`` (fallback: ``OPIK_URL_OVERRIDE``).
+        access_key: Acceldata API access key.
+            Env: ``ACCELDATA_AIO_ACCESS_KEY``
+            (fallback: ``OPIK_ACCESS_KEY``).
+        secret_key: Acceldata API secret key.
+            Env: ``ACCELDATA_AIO_SECRET_KEY``
+            (fallback: ``OPIK_SECRET_KEY``).
+        project_name: Default project name for traces.
+            Env: ``ACCELDATA_AIO_PROJECT_NAME``
+            (fallback: ``OPIK_PROJECT_NAME``).
+        debug: When True, install an httpx interceptor that logs every Opik
+            HTTP call and, on >=400 responses, dumps the request body to
+            disk and prints a copy-paste curl for replay. Off by default.
+            Env: ``ACCELDATA_AIO_DEBUG`` accepts ``1`` / ``true`` / ``yes``
+            / ``on`` (case-insensitive) to enable. Wrapper-specific — has
+            no upstream ``OPIK_*`` fallback.
+        check_tls_certificate: When False, disables TLS certificate
+            verification for outbound HTTP calls. Use only for local dev
+            against self-signed gateways. Default True.
+            Env: ``ACCELDATA_AIO_CHECK_TLS_CERTIFICATE``
+            (fallback: ``OPIK_CHECK_TLS_CERTIFICATE``).
+    """
+    _opik_bridge.apply_configure(
+        url=url,
+        access_key=access_key,
+        secret_key=secret_key,
+        project_name=project_name,
+        debug=debug,
+        check_tls_certificate=check_tls_certificate,
+    )
+
+
+# Bootstrap ACCELDATA_AIO_* env vars and auto-register the auth hook at
+# import time. All upstream-naming details live in _opik_bridge so this
+# module stays free of OPIK_* references.
+_opik_bridge.bootstrap_from_env()
+
+
+__all__ = (
+    "AcceldataTracer",
+    "AcceldataAuth",
+    "configure",
+    "setup_acceldata_auth",
+    "setup_acceldata_auth_hook",
+    *_opik.__all__,
+)
+
+del _opik

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/_opik_bridge.py

@@ -0,0 +1,107 @@
+"""Bridge between the Acceldata-branded API surface and upstream Opik internals.
+
+Everything in this module knows about the OPIK_* env-var names and the
+upstream Opik configuration keys. Nothing outside this module should
+reference them — that keeps the public package surface (__init__.py,
+configure(), etc.) brand-clean.
+"""
+
+import os
+import sys
+from typing import Optional
+
+from .auth import setup_acceldata_auth_hook
+from .client import _install_http_debug_interceptor
+
+
+# Customer-facing AIO env var name -> upstream Opik env var name.
+# Upstream names are an internal implementation detail and never exposed
+# in the public API.
+_ALIASES = (
+    ("URL",                   "ACCELDATA_AIO_URL",                   "OPIK_URL_OVERRIDE"),
+    ("ACCESS_KEY",            "ACCELDATA_AIO_ACCESS_KEY",            "OPIK_ACCESS_KEY"),
+    ("SECRET_KEY",            "ACCELDATA_AIO_SECRET_KEY",            "OPIK_SECRET_KEY"),
+    ("PROJECT_NAME",          "ACCELDATA_AIO_PROJECT_NAME",          "OPIK_PROJECT_NAME"),
+    ("CHECK_TLS_CERTIFICATE", "ACCELDATA_AIO_CHECK_TLS_CERTIFICATE", "OPIK_CHECK_TLS_CERTIFICATE"),
+)
+
+
+def _parse_truthy(value: str) -> bool:
+    """True for common truthy string representations: 1, true, yes, on (case-insensitive)."""
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def bootstrap_from_env() -> None:
+    """Translate ACCELDATA_AIO_* env vars to the upstream names Opik reads
+    natively, then auto-register the auth hook if creds are present and
+    install the HTTP debug interceptor if ``ACCELDATA_AIO_DEBUG`` is truthy.
+
+    An explicit upstream value (e.g. OPIK_URL_OVERRIDE) wins over its
+    ACCELDATA_AIO_* counterpart — escape hatch for migration, ops scripts,
+    or power-user overrides.
+
+    Prints a one-line stderr summary naming which env var fed each setting
+    (names only, never values).
+    """
+    picked = []
+    for label, aio_name, upstream_name in _ALIASES:
+        if os.environ.get(upstream_name) is not None:
+            picked.append((label, upstream_name))
+        elif os.environ.get(aio_name) is not None:
+            os.environ[upstream_name] = os.environ[aio_name]
+            picked.append((label, aio_name))
+
+    debug_raw = os.environ.get("ACCELDATA_AIO_DEBUG")
+    debug_enabled = debug_raw is not None and _parse_truthy(debug_raw)
+    if debug_enabled:
+        picked.append(("DEBUG", "ACCELDATA_AIO_DEBUG"))
+
+    if picked:
+        summary = ", ".join(f"{label}<-{source}" for label, source in picked)
+        print(f"[acceldata_aio_tracer] env init: {summary}", file=sys.stderr)
+    else:
+        print(
+            "[acceldata_aio_tracer] env init: no ACCELDATA_AIO_* or upstream "
+            "env vars detected; call configure() to set explicitly",
+            file=sys.stderr,
+        )
+
+    access_key = os.environ.get("OPIK_ACCESS_KEY")
+    secret_key = os.environ.get("OPIK_SECRET_KEY")
+    if access_key and secret_key:
+        setup_acceldata_auth_hook(access_key, secret_key)
+
+    if debug_enabled:
+        url = os.environ.get("OPIK_URL_OVERRIDE")
+        if url:
+            _install_http_debug_interceptor(url)
+        else:
+            print(
+                "[acceldata_aio_tracer] env init: ACCELDATA_AIO_DEBUG is truthy "
+                "but no URL configured; debug interceptor not installed",
+                file=sys.stderr,
+            )
+
+
+def apply_configure(
+    *,
+    url: str,
+    access_key: str,
+    secret_key: str,
+    project_name: Optional[str],
+    debug: bool,
+    check_tls_certificate: bool,
+) -> None:
+    """Apply the side effects of a configure() call: write upstream env vars,
+    register the Acceldata auth hook, optionally install the HTTP debug
+    interceptor.
+    """
+    os.environ["OPIK_URL_OVERRIDE"] = url
+    os.environ["OPIK_ACCESS_KEY"] = access_key
+    os.environ["OPIK_SECRET_KEY"] = secret_key
+    if project_name is not None:
+        os.environ["OPIK_PROJECT_NAME"] = project_name
+    setup_acceldata_auth_hook(access_key, secret_key)
+    os.environ["OPIK_CHECK_TLS_CERTIFICATE"] = "true" if check_tls_certificate else "false"
+    if debug:
+        _install_http_debug_interceptor(url)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/auth.py

@@ -0,0 +1,38 @@
+import os
+
+import httpx
+import opik.hooks
+
+
+class AcceldataAuth(httpx.Auth):
+    def __init__(self, access_key: str, secret_key: str) -> None:
+        self.access_key = access_key
+        self.secret_key = secret_key
+
+    def auth_flow(self, request):  # type: ignore
+        request.headers.pop("authorization", None)
+        request.headers["accessKey"] = self.access_key
+        request.headers["secretKey"] = self.secret_key
+        yield request
+
+
+def setup_acceldata_auth_hook(access_key: str, secret_key: str) -> None:
+    def acceldata_auth_client_hook(client: httpx.Client) -> None:
+        client.auth = AcceldataAuth(access_key, secret_key)
+
+    opik.hooks.add_httpx_client_hook(
+        opik.hooks.HttpxClientHook(
+            client_modifier=acceldata_auth_client_hook,
+            client_init_arguments=None,
+        )
+    )
+
+
+def setup_acceldata_auth(url: str, access_key: str, secret_key: str) -> None:
+    """Boot-time setup for users of @opik.track and Opik integrations.
+
+    Call once before any tracked function runs. Subsequent Opik clients
+    (including the cached one used by @track) will pick up the auth.
+    """
+    os.environ.setdefault("OPIK_URL_OVERRIDE", url)
+    setup_acceldata_auth_hook(access_key, secret_key)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/client.py

@@ -0,0 +1,166 @@
+import logging
+import os
+import shlex
+from typing import Any
+from urllib.parse import urlparse
+
+from opik import Opik
+
+from .auth import setup_acceldata_auth_hook
+
+
+_DEBUG_REQ_DUMP_PATH = "/tmp/acceldata-aio-tracer-last-failed-request.bin"
+_debug_installed = False
+
+
+def _install_http_debug_interceptor(opik_url: str) -> None:
+    """Patch httpx.Client.send and httpx.AsyncClient.send to log every Opik
+    HTTP call. On responses with status >= 400, dumps the request body to
+    `_DEBUG_REQ_DUMP_PATH` and prints a copy-paste curl that replays the
+    request. Idempotent — safe to call multiple times.
+    """
+    global _debug_installed
+    if _debug_installed:
+        return
+
+    import httpx
+
+    logger = logging.getLogger("acceldata_aio_tracer.http_trace")
+    logger.setLevel(logging.DEBUG)
+    if not logger.handlers:
+        h = logging.StreamHandler()
+        h.setFormatter(logging.Formatter(
+            "%(asctime)s %(levelname)-5s acceldata_aio_tracer.http_trace: %(message)s"
+        ))
+        logger.addHandler(h)
+        logger.propagate = False
+
+    target_host = urlparse(opik_url).netloc
+
+    def is_opik_url(url) -> bool:
+        try:
+            return urlparse(str(url)).netloc == target_host
+        except Exception:
+            return False
+
+    def fmt_body(body) -> str:
+        if body is None:
+            return "<none>"
+        if isinstance(body, (bytes, bytearray)):
+            try:
+                return body.decode("utf-8", errors="replace")[:4000]
+            except Exception:
+                return f"<{len(body)} bytes>"
+        return str(body)[:4000]
+
+    def decode_resp(resp_body) -> str:
+        if isinstance(resp_body, (bytes, bytearray)):
+            return resp_body.decode("utf-8", errors="replace")
+        return str(resp_body)
+
+    def build_replay_curl(method: str, url: str, headers: dict, body_path) -> str:
+        parts = ["curl -v --insecure -X", method, shlex.quote(str(url))]
+        for k, v in headers.items():
+            if k.lower() in ("host", "content-length"):
+                continue
+            parts += ["-H", shlex.quote(f"{k}: {v}")]
+        if body_path:
+            parts += ["--data-binary", f"@{body_path}"]
+        return " \\\n  ".join(parts)
+
+    def dump_request_body(request) -> str:
+        if not request.content:
+            return ""
+        try:
+            with open(_DEBUG_REQ_DUMP_PATH, "wb") as f:
+                f.write(request.content)
+            return _DEBUG_REQ_DUMP_PATH
+        except Exception as write_err:
+            logger.warning(f"failed to dump request body: {write_err}")
+            return ""
+
+    def log_failure(request, response, resp_body, async_marker: str = "") -> None:
+        body_path = dump_request_body(request)
+        decoded = decode_resp(resp_body)[:8000]
+        curl = build_replay_curl(
+            request.method, str(request.url), dict(request.headers), body_path
+        )
+        logger.error(
+            f"<<< {async_marker}{response.status_code} {request.method} {request.url}\n"
+            f"    error_body={decoded}\n"
+            f"    request_body_dumped_to={body_path or '<none>'}\n"
+            f"    REPLAY (paste into shell):\n{curl}"
+        )
+
+    orig_send = httpx.Client.send
+
+    def patched_send(self, request, *args, **kwargs):
+        log_this = is_opik_url(request.url)
+        if log_this:
+            logger.debug(
+                f">>> {request.method} {request.url}\n"
+                f"    headers={dict(request.headers)}\n"
+                f"    body={fmt_body(request.content)}"
+            )
+        response = orig_send(self, request, *args, **kwargs)
+        if log_this:
+            try:
+                resp_body = response.read()
+            except Exception as read_err:
+                resp_body = f"<read failed: {read_err}>".encode()
+            if response.status_code >= 400:
+                log_failure(request, response, resp_body)
+            else:
+                logger.debug(
+                    f"<<< {response.status_code} {request.method} {request.url}\n"
+                    f"    body={fmt_body(resp_body)}"
+                )
+        return response
+
+    httpx.Client.send = patched_send
+
+    orig_async_send = httpx.AsyncClient.send
+
+    async def patched_async_send(self, request, *args, **kwargs):
+        log_this = is_opik_url(request.url)
+        if log_this:
+            logger.debug(
+                f">>> [async] {request.method} {request.url}\n"
+                f"    headers={dict(request.headers)}\n"
+                f"    body={fmt_body(request.content)}"
+            )
+        response = await orig_async_send(self, request, *args, **kwargs)
+        if log_this:
+            try:
+                resp_body = await response.aread()
+            except Exception as read_err:
+                resp_body = f"<read failed: {read_err}>".encode()
+            if response.status_code >= 400:
+                log_failure(request, response, resp_body, async_marker="[async] ")
+            else:
+                logger.debug(
+                    f"<<< [async] {response.status_code} {request.method} {request.url}\n"
+                    f"    body={fmt_body(resp_body)}"
+                )
+        return response
+
+    httpx.AsyncClient.send = patched_async_send
+
+    _debug_installed = True
+    logger.info(f"http debug interceptor installed for host={target_host}")
+
+
+def AcceldataTracer(
+    url: str,
+    access_key: str,
+    secret_key: str,
+    *,
+    debug: bool = False,
+    check_tls_certificate: bool = True,
+    **kwargs: Any,
+) -> Opik:
+    setup_acceldata_auth_hook(access_key, secret_key)
+    os.environ["OPIK_CHECK_TLS_CERTIFICATE"] = "true" if check_tls_certificate else "false"
+    if debug:
+        _install_http_debug_interceptor(url)
+    return Opik(host=url, **kwargs)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/adk.py

@@ -0,0 +1,11 @@
+from opik.integrations.adk import (
+    OpikTracer as ADKTracer,
+    build_mermaid_graph_definition,
+    track_adk_agent_recursive,
+)
+
+__all__ = (
+    "ADKTracer",
+    "track_adk_agent_recursive",
+    "build_mermaid_graph_definition",
+)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/aisuite.py

@@ -0,0 +1,3 @@
+from opik.integrations.aisuite import track_aisuite
+
+__all__ = ("track_aisuite",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/anthropic.py

@@ -0,0 +1,3 @@
+from opik.integrations.anthropic import track_anthropic
+
+__all__ = ("track_anthropic",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/bedrock.py

@@ -0,0 +1,3 @@
+from opik.integrations.bedrock import track_bedrock
+
+__all__ = ("track_bedrock",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/crewai.py

@@ -0,0 +1,3 @@
+from opik.integrations.crewai import track_crewai
+
+__all__ = ("track_crewai",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/dspy.py

@@ -0,0 +1,3 @@
+from opik.integrations.dspy import OpikCallback as DSPyCallback
+
+__all__ = ("DSPyCallback",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/genai.py

@@ -0,0 +1,3 @@
+from opik.integrations.genai import track_genai
+
+__all__ = ("track_genai",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/guardrails.py

@@ -0,0 +1,3 @@
+from opik.integrations.guardrails import track_guardrails
+
+__all__ = ("track_guardrails",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/harbor.py

@@ -0,0 +1,3 @@
+from opik.integrations.harbor import reset_harbor_tracking, track_harbor
+
+__all__ = ("track_harbor", "reset_harbor_tracking")

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/haystack.py

@@ -0,0 +1,3 @@
+from opik.integrations.haystack import OpikConnector as HaystackConnector
+
+__all__ = ("HaystackConnector",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/langchain.py

@@ -0,0 +1,19 @@
+from opik.integrations.langchain import (
+    LANGGRAPH_INTERRUPT_METADATA_KEY,
+    LANGGRAPH_INTERRUPT_OUTPUT_KEY,
+    LANGGRAPH_PARENT_COMMAND_METADATA_KEY,
+    LANGGRAPH_RESUME_INPUT_KEY,
+    OpikTracer as LangChainTracer,
+    extract_current_langgraph_span_data,
+    track_langgraph,
+)
+
+__all__ = (
+    "LangChainTracer",
+    "track_langgraph",
+    "extract_current_langgraph_span_data",
+    "LANGGRAPH_INTERRUPT_OUTPUT_KEY",
+    "LANGGRAPH_RESUME_INPUT_KEY",
+    "LANGGRAPH_INTERRUPT_METADATA_KEY",
+    "LANGGRAPH_PARENT_COMMAND_METADATA_KEY",
+)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/litellm.py

@@ -0,0 +1,3 @@
+from opik.integrations.litellm import track_completion
+
+__all__ = ("track_completion",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/llama_index.py

@@ -0,0 +1,3 @@
+from opik.integrations.llama_index import LlamaIndexCallbackHandler
+
+__all__ = ("LlamaIndexCallbackHandler",)

acceldata_aio_tracer-0.1.0.dev1/src/acceldata_aio_tracer/integrations/openai.py

@@ -0,0 +1,3 @@
+from opik.integrations.openai import track_openai
+
+__all__ = ("track_openai",)