agent-observability-trace-cli 0.1.2__tar.gz → 0.1.3__tar.gz

{agent_observability_trace_cli-0.1.2 → agent_observability_trace_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-observability-trace-cli
-Version: 0.1.2
+Version: 0.1.3
 Summary: AI agent observability with deterministic record/replay — capture any LangGraph or OpenAI Agents SDK run, replay it offline at zero API cost.
 Project-URL: Homepage, https://github.com/RudrenduPaul/agent-observability
 Project-URL: Documentation, https://github.com/RudrenduPaul/agent-observability/blob/main/docs/getting-started.md
@@ -95,7 +95,7 @@ Description-Content-Type: text/markdown
 
 ![Terminal recording of agent-trace recording a live HTTP call, then replaying the same run offline with zero network requests](docs/assets/dev-to-demos/demo-1-record-replay.gif)
 
-[![PyPI](https://img.shields.io/pypi/v/agent-observability-trace)](https://pypi.org/project/agent-observability-trace/)
+[![PyPI](https://img.shields.io/pypi/v/agent-observability-trace-cli)](https://pypi.org/project/agent-observability-trace-cli/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![CI](https://github.com/RudrenduPaul/agent-observability/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/agent-observability/actions)
@@ -106,23 +106,25 @@ Description-Content-Type: text/markdown
 ## Install
 
 ```bash
-pip install agent-observability-trace
+pip install agent-observability-trace-cli
 # or
-uv add agent-observability-trace
+uv add agent-observability-trace-cli
 ```
 
 LangGraph support:
 
 ```bash
-pip install agent-observability-trace[langgraph]
+pip install agent-observability-trace-cli[langgraph]
 ```
 
 OpenAI Agents SDK support:
 
 ```bash
-pip install agent-observability-trace[openai-agents]
+pip install agent-observability-trace-cli[openai-agents]
 ```
 
+![Terminal recording of installing agent-observability-trace-cli into a fresh virtual environment, then running agent-trace version and recording a first HTTP call with agent-trace list showing the resulting run](docs/demo.gif)
+
 ## The problem
 
 A LangGraph run fails after step 8. Your trace in LangSmith or Langfuse shows *what* broke. But to reproduce it you have to re-run the entire agent: 8 more LLM calls, 30 more seconds, another $0.15 in API cost. If the failure was caused by a specific tool response or a transient model output, you can't reproduce it at all. You're debugging against a moving target.
@@ -169,6 +171,8 @@ with replay("run_<id>") as ctx:
 
 > **Sync and async clients:** Agent Observability intercepts `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` — including the async client used by default in the OpenAI Python SDK v1.x and Anthropic SDK. The patch is installed at request-dispatch time, so it also covers clients constructed before recording/replay starts (e.g. a module-level `openai.AsyncOpenAI()` instance).
 
+![Terminal recording of replaying a previously recorded run with zero network calls, then running agent-trace show to print the replayed span tree](docs/usage.gif)
+
 ---
 
 ## Use in CI: replay at zero cost
@@ -321,6 +325,42 @@ after:
 
 ---
 
+## FAQ
+
+**What is Agent Observability, and how is it different from a typical LLM tracing tool?**
+
+It's a Python library and CLI (`agent-trace`) that records every HTTP request and response your agent makes, verbatim, to a local SQLite fixture, then replays those exact bytes later with no network call. Most tracing tools, including LangSmith, Langfuse, Helicone, and OpenLLMetry, show you what happened during a run. Agent Observability additionally lets you reproduce that exact run offline, deterministically, without touching the live API. See "How Agent Observability compares" above for the full capability breakdown against those four tools.
+
+**How does deterministic record/replay actually work?**
+
+Recording patches `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` at the transport layer (`src/agent_trace/interceptor/`) to capture every outbound request and response as raw bytes into `fixture.db`. Replay installs a `FixtureClock` (`src/agent_trace/core/clock.py`) and serves those same bytes back in the original sequence, so the code path, span tree, and timestamps all match the original recording. The benchmark numbers quoted above (0.011% recording overhead, 0.93ms mean replay latency, 100% fidelity) come from `benchmarks/test_overhead.py`, `benchmarks/test_replay_vs_live.py`, and `benchmarks/test_fidelity.py` in this repo, runnable yourself with `uv run pytest benchmarks/`.
+
+**How do I install it, and what platforms does it support?**
+
+`pip install agent-observability-trace-cli`, or `uv add agent-observability-trace-cli`. It requires Python 3.10 or newer and depends only on `httpx` and `rich`, no compiled extensions, so it installs anywhere those wheels do. CI (`.github/workflows/ci.yml`) currently runs on Ubuntu only; macOS and Windows aren't part of the automated test matrix, though nothing in the interceptor or replay engine touches OS-specific APIs. An npm wrapper, [`agent-observability-trace-cli`](npm/) (source under [`npm/`](npm/) in this repo), is also published for teams that reach for `npx`/`npm`, but it still shells out to the Python CLI under the hood, so the Python package must be installed too.
+
+**How does this compare to LangSmith specifically?**
+
+LangSmith's `LANGSMITH_TEST_CACHE` (VCR-style cassettes, via `langsmith[vcr]`) is the closest built-in equivalent. It's Python plus LangChain only, captures HTTP calls to `api.openai.com` rather than any HTTP client, doesn't record full wire-level bytes, and requires a LangSmith account. Agent Observability works with any Python HTTP client, plus dedicated interceptors for gRPC, aiohttp, botocore, and WebSocket traffic, records full request and response bytes locally, and needs no account or hosted service. Pick LangSmith if you're already on LangChain and want dataset management, prompt versioning, and human feedback loops alongside tracing. Pick Agent Observability if the goal is reproducing one specific failed run at zero API cost, regardless of which SDK made the call.
+
+**What happens if replay can't find a matching fixture entry?**
+
+With `AGENT_TRACE_NETWORK_GUARD=1` set, any request missing from the fixture raises `NetworkGuardError` immediately instead of silently falling through to a live call. The most common cause is an HTTP client constructed before the recording or replay context was entered, since the patch only applies to clients created inside the `start_trace`/`replay` block. See "Known limitations" above for the full list of edges, including partial gRPC streaming coverage and pre-HTTP exceptions that never reach the interceptor.
+
+**Does it capture agents built on non-Python frameworks?**
+
+No. Capture is a Python HTTP-transport interceptor plus instrumented callbacks for the integrations under `src/agent_trace/integrations/` (LangGraph, CrewAI, AutoGen, LlamaIndex, Haystack, Agno, PydanticAI, Google GenAI, and others). It only sees traffic from your own Python process. Agents built in other languages, or calls made by a third-party hosted service you don't run yourself, are outside its capture surface.
+
+**Are fixture files safe to commit to version control?**
+
+Not by default. `fixture.db` contains full HTTP request and response bodies, which means API keys and prompt contents whenever they appear in headers or payloads. Add `.agent-trace/` and `*.db` to `.gitignore`, and never commit a fixture recorded against a production API key. Strip or redact secrets first if you want to keep a fixture as a committed CI test asset.
+
+**Is this free to use commercially?**
+
+Yes. The project is Apache 2.0 licensed (see [LICENSE](LICENSE)), which permits commercial use, modification, and redistribution, including inside closed-source products, subject to the license's own attribution and notice terms. There is no separate paid tier or commercial license.
+
+---
+
 ## Contributing
 
 - Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR
@@ -334,3 +374,4 @@ Apache 2.0. Contributions welcome.
 ---
 
 *Built by Rudrendu Paul*
+

{agent_observability_trace_cli-0.1.2 → agent_observability_trace_cli-0.1.3}/README.md

@@ -4,7 +4,7 @@
 
 ![Terminal recording of agent-trace recording a live HTTP call, then replaying the same run offline with zero network requests](docs/assets/dev-to-demos/demo-1-record-replay.gif)
 
-[![PyPI](https://img.shields.io/pypi/v/agent-observability-trace)](https://pypi.org/project/agent-observability-trace/)
+[![PyPI](https://img.shields.io/pypi/v/agent-observability-trace-cli)](https://pypi.org/project/agent-observability-trace-cli/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![CI](https://github.com/RudrenduPaul/agent-observability/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/agent-observability/actions)
@@ -15,23 +15,25 @@
 ## Install
 
 ```bash
-pip install agent-observability-trace
+pip install agent-observability-trace-cli
 # or
-uv add agent-observability-trace
+uv add agent-observability-trace-cli
 ```
 
 LangGraph support:
 
 ```bash
-pip install agent-observability-trace[langgraph]
+pip install agent-observability-trace-cli[langgraph]
 ```
 
 OpenAI Agents SDK support:
 
 ```bash
-pip install agent-observability-trace[openai-agents]
+pip install agent-observability-trace-cli[openai-agents]
 ```
 
+![Terminal recording of installing agent-observability-trace-cli into a fresh virtual environment, then running agent-trace version and recording a first HTTP call with agent-trace list showing the resulting run](docs/demo.gif)
+
 ## The problem
 
 A LangGraph run fails after step 8. Your trace in LangSmith or Langfuse shows *what* broke. But to reproduce it you have to re-run the entire agent: 8 more LLM calls, 30 more seconds, another $0.15 in API cost. If the failure was caused by a specific tool response or a transient model output, you can't reproduce it at all. You're debugging against a moving target.
@@ -78,6 +80,8 @@ with replay("run_<id>") as ctx:
 
 > **Sync and async clients:** Agent Observability intercepts `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` — including the async client used by default in the OpenAI Python SDK v1.x and Anthropic SDK. The patch is installed at request-dispatch time, so it also covers clients constructed before recording/replay starts (e.g. a module-level `openai.AsyncOpenAI()` instance).
 
+![Terminal recording of replaying a previously recorded run with zero network calls, then running agent-trace show to print the replayed span tree](docs/usage.gif)
+
 ---
 
 ## Use in CI: replay at zero cost
@@ -230,6 +234,42 @@ after:
 
 ---
 
+## FAQ
+
+**What is Agent Observability, and how is it different from a typical LLM tracing tool?**
+
+It's a Python library and CLI (`agent-trace`) that records every HTTP request and response your agent makes, verbatim, to a local SQLite fixture, then replays those exact bytes later with no network call. Most tracing tools, including LangSmith, Langfuse, Helicone, and OpenLLMetry, show you what happened during a run. Agent Observability additionally lets you reproduce that exact run offline, deterministically, without touching the live API. See "How Agent Observability compares" above for the full capability breakdown against those four tools.
+
+**How does deterministic record/replay actually work?**
+
+Recording patches `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` at the transport layer (`src/agent_trace/interceptor/`) to capture every outbound request and response as raw bytes into `fixture.db`. Replay installs a `FixtureClock` (`src/agent_trace/core/clock.py`) and serves those same bytes back in the original sequence, so the code path, span tree, and timestamps all match the original recording. The benchmark numbers quoted above (0.011% recording overhead, 0.93ms mean replay latency, 100% fidelity) come from `benchmarks/test_overhead.py`, `benchmarks/test_replay_vs_live.py`, and `benchmarks/test_fidelity.py` in this repo, runnable yourself with `uv run pytest benchmarks/`.
+
+**How do I install it, and what platforms does it support?**
+
+`pip install agent-observability-trace-cli`, or `uv add agent-observability-trace-cli`. It requires Python 3.10 or newer and depends only on `httpx` and `rich`, no compiled extensions, so it installs anywhere those wheels do. CI (`.github/workflows/ci.yml`) currently runs on Ubuntu only; macOS and Windows aren't part of the automated test matrix, though nothing in the interceptor or replay engine touches OS-specific APIs. An npm wrapper, [`agent-observability-trace-cli`](npm/) (source under [`npm/`](npm/) in this repo), is also published for teams that reach for `npx`/`npm`, but it still shells out to the Python CLI under the hood, so the Python package must be installed too.
+
+**How does this compare to LangSmith specifically?**
+
+LangSmith's `LANGSMITH_TEST_CACHE` (VCR-style cassettes, via `langsmith[vcr]`) is the closest built-in equivalent. It's Python plus LangChain only, captures HTTP calls to `api.openai.com` rather than any HTTP client, doesn't record full wire-level bytes, and requires a LangSmith account. Agent Observability works with any Python HTTP client, plus dedicated interceptors for gRPC, aiohttp, botocore, and WebSocket traffic, records full request and response bytes locally, and needs no account or hosted service. Pick LangSmith if you're already on LangChain and want dataset management, prompt versioning, and human feedback loops alongside tracing. Pick Agent Observability if the goal is reproducing one specific failed run at zero API cost, regardless of which SDK made the call.
+
+**What happens if replay can't find a matching fixture entry?**
+
+With `AGENT_TRACE_NETWORK_GUARD=1` set, any request missing from the fixture raises `NetworkGuardError` immediately instead of silently falling through to a live call. The most common cause is an HTTP client constructed before the recording or replay context was entered, since the patch only applies to clients created inside the `start_trace`/`replay` block. See "Known limitations" above for the full list of edges, including partial gRPC streaming coverage and pre-HTTP exceptions that never reach the interceptor.
+
+**Does it capture agents built on non-Python frameworks?**
+
+No. Capture is a Python HTTP-transport interceptor plus instrumented callbacks for the integrations under `src/agent_trace/integrations/` (LangGraph, CrewAI, AutoGen, LlamaIndex, Haystack, Agno, PydanticAI, Google GenAI, and others). It only sees traffic from your own Python process. Agents built in other languages, or calls made by a third-party hosted service you don't run yourself, are outside its capture surface.
+
+**Are fixture files safe to commit to version control?**
+
+Not by default. `fixture.db` contains full HTTP request and response bodies, which means API keys and prompt contents whenever they appear in headers or payloads. Add `.agent-trace/` and `*.db` to `.gitignore`, and never commit a fixture recorded against a production API key. Strip or redact secrets first if you want to keep a fixture as a committed CI test asset.
+
+**Is this free to use commercially?**
+
+Yes. The project is Apache 2.0 licensed (see [LICENSE](LICENSE)), which permits commercial use, modification, and redistribution, including inside closed-source products, subject to the license's own attribution and notice terms. There is no separate paid tier or commercial license.
+
+---
+
 ## Contributing
 
 - Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR
@@ -243,3 +283,4 @@ Apache 2.0. Contributions welcome.
 ---
 
 *Built by Rudrendu Paul*
+

agent_observability_trace_cli-0.1.3/npm/LICENSE

@@ -0,0 +1,198 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on an unchanged basis, or on the basis of
+      derivatives of it, solely to the extent these changes are necessary
+      to conform to other license requirements applicable to those
+      derivatives.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. It is also
+      recommended that a file or directory name and a description of the
+      purpose of the file be included on the same "PRINT" or "on the
+      first page" of each appropriate file.
+
+   Copyright 2026 Rudrendu Paul and Sourav Nandy
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agent_observability_trace_cli-0.1.3/npm/README.md

@@ -0,0 +1,135 @@
+# agent-observability-trace-cli (npm wrapper)
+
+An npm-installable wrapper for [`agent-trace`](https://github.com/RudrenduPaul/agent-observability), the deterministic record/replay tool for LLM agents. This package does not reimplement `agent-trace`. It puts the real `agent-trace` command on your PATH through `npm install`/`npx`, then forwards every argument straight through to the actual Python CLI.
+
+## What agent-trace does
+
+`agent-trace` records every HTTP request and response your agent makes, verbatim, to a local SQLite fixture, then replays those exact bytes later with zero network calls. It patches `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` at the transport layer, so it works with any Python HTTP client, including the clients used internally by the OpenAI Python SDK and the Anthropic SDK. The project's own benchmark suite (`benchmarks/test_overhead.py`, `benchmarks/test_replay_vs_live.py`, `benchmarks/test_fidelity.py` in the main repo) reports 0.011% recording overhead, 0.93ms mean replay latency, and byte-for-byte replay fidelity, at $0 API cost per replay.
+
+## Why this wrapper exists
+
+`agent-trace` is a Python tool. If your team, CI pipeline, or agent harness already reaches for `npx` to run CLIs, this wrapper skips the "how do I invoke a Python tool from a Node-first workflow" step. It is a thin exec-and-forward shim, nothing more: the actual record/replay engine, interceptors, and CLI logic all live in the `agent_trace` Python package.
+
+## Prerequisites
+
+- Python 3.10 or newer
+- The [`agent-observability-trace-cli`](https://pypi.org/project/agent-observability-trace-cli/) PyPI package installed on the same machine (its console command is `agent-trace`):
+
+```bash
+pip install agent-observability-trace-cli
+# or
+uv add agent-observability-trace-cli
+# or, for an isolated global install
+pipx install agent-observability-trace-cli
+```
+
+Without that package installed, this wrapper prints install instructions and exits non-zero. It never installs anything on your behalf.
+
+## Install
+
+```bash
+npm install -g agent-observability-trace-cli
+# or run without installing
+npx agent-observability-trace-cli version
+```
+
+## Usage
+
+Once installed, `agent-trace` on your PATH is this wrapper, and every subcommand is forwarded unchanged to the real CLI:
+
+```bash
+agent-trace version
+agent-trace list
+agent-trace show run_abc123def456
+agent-trace show run_abc123def456 --errors-only
+agent-trace replay run_abc123def456
+agent-trace inspect run_abc123def456
+agent-trace diff run_a run_b
+agent-trace run -- langgraph dev
+```
+
+A recording/replay round trip in Python, using the underlying library directly:
+
+```python
+from agent_trace import tracer
+import httpx
+
+@tracer.instrument(record=True)
+def fetch_data(query: str) -> dict:
+    with tracer.span("http-call") as span:
+        resp = httpx.get("https://httpbin.org/get", params={"q": query})
+        span.set_attribute("http.status_code", resp.status_code)
+        return resp.json()
+
+result = fetch_data("hello")
+# Trace and fixture saved to ~/.agent-trace/runs/run_<id>/
+```
+
+Full command reference, the record/replay model, and framework integrations (LangGraph, OpenAI Agents SDK, CrewAI, and more) are documented in the [main repository](https://github.com/RudrenduPaul/agent-observability).
+
+## How it works
+
+The `agent-trace` bin script this package installs does two things, in order:
+
+1. Looks for a real `agent-trace` executable on your PATH (the console script `pip`/`uv`/`pipx` installs) and execs it with your arguments.
+2. If that isn't found, falls back to invoking the `agent_trace` Python module directly through `python3`/`python`.
+
+If neither is available, it prints the install instructions above and exits with a non-zero status.
+
+## How it compares
+
+Most observability tools for LLM agents, including LangSmith, Langfuse, Helicone, and OpenLLMetry, are observe-only: they show you a trace of what happened, but reproducing a failure still means re-running the full agent against live APIs. `agent-trace` additionally lets you reproduce that exact run offline, deterministically, without touching the live API.
+
+The closest built-in comparison is LangSmith's `LANGSMITH_TEST_CACHE` (VCR-style cassettes via `langsmith[vcr]`). It's Python plus LangChain only, captures HTTP calls to `api.openai.com` specifically rather than any HTTP client, doesn't record full wire-level bytes, and requires a LangSmith account. `agent-trace` works with any Python HTTP client, records full request and response bytes locally, and needs no account or hosted service.
+
+The full capability table against LangSmith, Langfuse, Helicone, and OpenLLMetry lives in the [main repository's README](https://github.com/RudrenduPaul/agent-observability#how-agent-observability-compares).
+
+## Known limitations
+
+This wrapper only forwards arguments; the limitations below belong to `agent-trace` itself (documented in full in the main repo's README):
+
+- Recording and replay happen inside the Python process you import `agent_trace` into. It cannot observe or replay calls made by a third-party hosted service you don't run yourself, only your own process's outbound calls.
+- gRPC coverage is partial: unary-unary and sync unary-stream calls (used by Gemini/Vertex AI) are captured and replayed, but client-streaming, bidirectional-streaming, and any `grpc.aio` streaming call are not.
+- Capture starts once a fully-constructed HTTP request object reaches the interceptor. Exceptions raised earlier, while an SDK is still serializing a tool schema or building headers, produce zero fixture rows unless a wired-in framework integration's own error callback catches them first.
+
+## FAQ
+
+**Does this package reimplement `agent-trace` in JavaScript?**
+
+No. It is a thin wrapper. The `bin/agent-trace.js` script it installs execs the real `agent-trace` console script if it finds one on your PATH, or falls back to invoking the `agent_trace` Python module through `python3`/`python`. All record/replay logic, HTTP interceptors, and CLI commands live in the Python package.
+
+**Why would I install a Node wrapper for a Python tool?**
+
+If your team already standardizes on `npx`/`npm` to run CLIs, whether in local scripts, CI steps, or agent tooling, this lets `agent-trace` slot into that same invocation pattern without a separate "activate a Python environment first" step. You still need the Python package installed; this wrapper does not remove that dependency.
+
+**What do I need installed before this works?**
+
+Python 3.10 or newer, plus the `agent-observability-trace-cli` PyPI package (`pip install agent-observability-trace-cli`, `uv add agent-observability-trace-cli`, or `pipx install agent-observability-trace-cli`). This npm package alone does nothing useful without it.
+
+**What happens if I run `agent-trace` through this wrapper without the Python package installed?**
+
+The wrapper tries the real console script first, then falls back to a direct Python module import. If both fail, it prints the exact `pip`/`uv`/`pipx` install commands above and exits with a non-zero status. It never installs anything automatically.
+
+**Which commands does this wrapper support?**
+
+All of them, unmodified. Every argument you pass to `agent-trace` through this wrapper is forwarded verbatim to the real CLI, so `agent-trace version`, `agent-trace list`, `agent-trace show <run-id>`, `agent-trace replay <run-id>`, `agent-trace inspect <run-id>`, `agent-trace diff <run-a> <run-b>`, and `agent-trace run -- <command>` all work exactly as documented in the main repository.
+
+**How is this different from LangSmith's tracing/caching?**
+
+LangSmith's `LANGSMITH_TEST_CACHE` needs LangChain and a LangSmith account, and only captures calls to `api.openai.com`. `agent-trace` works with any Python HTTP client (`httpx`, `requests`, and the transports used inside the OpenAI and Anthropic SDKs), records full request/response bytes locally, and needs no account. See the comparison table in the main repository for the full breakdown against LangSmith, Langfuse, Helicone, and OpenLLMetry.
+
+**Does this wrapper work on Windows?**
+
+The wrapper itself is plain Node.js and has no OS-specific code. Whether the underlying `agent-trace` Python package works on your platform depends on that package's own support, documented in the main repository; its automated CI currently runs on Ubuntu only.
+
+**Is it safe to commit recorded fixtures to version control?**
+
+Not by default, and this is a property of `agent-trace` itself, not this wrapper. Fixture files can contain full HTTP request and response bodies, including API keys and prompt contents. See the main repository's README for guidance on `.gitignore` entries and redacting secrets before committing a fixture.
+
+**Is this free to use commercially?**
+
+Yes. Both this npm package and the underlying `agent-observability-trace-cli` PyPI package are Apache 2.0 licensed, which permits commercial use, modification, and redistribution, subject to the license's attribution and notice terms.
+
+## License
+
+Apache-2.0

agent_observability_trace_cli-0.1.3/npm/bin/agent-trace.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+
+const args = process.argv.slice(2);
+
+const INSTALL_HELP = `
+agent-trace-cli is an npm wrapper: the actual CLI ships as a Python package.
+
+Install it, then re-run this command:
+
+  pip install agent-observability-trace-cli
+  # or
+  uv add agent-observability-trace-cli
+  # or, for an isolated global install
+  pipx install agent-observability-trace-cli
+
+Docs: https://github.com/RudrenduPaul/agent-observability
+`;
+
+function run(command, commandArgs) {
+  return spawnSync(command, commandArgs, { stdio: "inherit" });
+}
+
+// Preferred path: the real "agent-trace" console script is on PATH
+// (installed via pip/uv/pipx per project.scripts in pyproject.toml).
+let result = run("agent-trace", args);
+if (!(result.error && result.error.code === "ENOENT")) {
+  if (result.error) {
+    throw result.error;
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+// Fallback: agent-trace's console script isn't on PATH (e.g. pip
+// installed into a venv not exported to PATH). Try invoking the
+// module's CLI entry point directly through Python. Output is
+// captured (not streamed) here so a missing module can be turned into
+// the friendlier INSTALL_HELP message below instead of a raw traceback.
+const pyScript =
+  "import sys; from agent_trace._cli import main; sys.argv = ['agent-trace'] + sys.argv[1:]; main()";
+let pythonFound = false;
+for (const python of ["python3", "python"]) {
+  const pyResult = spawnSync(python, ["-c", pyScript, ...args], {
+    stdio: ["inherit", "inherit", "pipe"],
+    encoding: "utf8",
+  });
+  if (pyResult.error && pyResult.error.code === "ENOENT") {
+    continue;
+  }
+  pythonFound = true;
+  if (pyResult.stderr && pyResult.stderr.includes("ModuleNotFoundError: No module named 'agent_trace'")) {
+    break;
+  }
+  if (pyResult.stderr) {
+    process.stderr.write(pyResult.stderr);
+  }
+  process.exit(pyResult.status === null ? 1 : pyResult.status);
+}
+
+process.stderr.write(INSTALL_HELP);
+process.exit(1);

agent_observability_trace_cli-0.1.3/npm/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-observability-trace-cli",
+  "version": "0.1.0",
+  "description": "npm-installable CLI wrapper for agent-trace, deterministic record/replay for LLM agents. Requires Python 3.10+ and the agent-observability-trace-cli PyPI package.",
+  "bin": {
+    "agent-trace": "bin/agent-trace.js"
+  },
+  "files": [
+    "bin",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "agent-trace",
+    "ai-agents",
+    "observability",
+    "tracing",
+    "llm",
+    "langgraph",
+    "openai",
+    "record-replay",
+    "debugging",
+    "cli"
+  ],
+  "homepage": "https://github.com/RudrenduPaul/agent-observability#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RudrenduPaul/agent-observability.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/RudrenduPaul/agent-observability/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Rudrendu Paul",
+  "engines": {
+    "node": ">=18"
+  }
+}

{agent_observability_trace_cli-0.1.2 → agent_observability_trace_cli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-observability-trace-cli"
-version = "0.1.2"
+version = "0.1.3"
 description = "AI agent observability with deterministic record/replay — capture any LangGraph or OpenAI Agents SDK run, replay it offline at zero API cost."
 readme = "README.md"
 license = {text = "Apache-2.0"}