agent-observability-trace-cli 0.1.2__tar.gz

agent_observability_trace_cli-0.1.2/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# CI/CD and workflow changes are the highest-leverage place for a supply-chain
+# compromise to hide -- require review on any change to them regardless of
+# what other paths are covered.
+/.github/workflows/ @RudrenduPaul

agent_observability_trace_cli-0.1.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please fill in as much detail as possible.
+
+  - type: input
+    id: version
+    attributes:
+      label: agent-trace version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest code snippet that reproduces the bug.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.0"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "macOS 15.0 / Ubuntu 24.04"
+    validations:
+      required: true

agent_observability_trace_cli-0.1.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the pain point. Link to a GitHub Discussion if one exists.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would the API look like? Code example preferred.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: integration
+    attributes:
+      label: Related integration (if any)
+      options:
+        - Not integration-specific
+        - LangGraph
+        - OpenAI Agents SDK
+        - CrewAI
+        - AutoGen
+        - Other
+    validations:
+      required: false

agent_observability_trace_cli-0.1.2/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    groups:
+      patch-updates:
+        update-types: [patch]
+    ignore:
+      - dependency-name: "*"
+        update-types: [version-update:semver-major]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

agent_observability_trace_cli-0.1.2/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do? One paragraph. -->
+
+## Changes
+
+-
+
+## Testing
+
+- [ ] Unit tests added or updated for all behavior changes
+- [ ] `uv run pytest tests/unit/ -q` passes locally
+- [ ] `uv run mypy src/ --strict` passes with zero errors
+- [ ] `uv run ruff check src/ tests/` passes
+
+## Checklist
+
+- [ ] CHANGELOG.md updated (for any user-facing change)
+- [ ] No unrelated refactors in this PR
+- [ ] If this is AI-assisted: I have read and validated every line of generated code
+
+## Benchmark impact (if touching performance-sensitive code)
+
+<!-- Run: uv run pytest benchmarks/ --benchmark-compare and paste the diff -->

agent_observability_trace_cli-0.1.2/.github/workflows/benchmark.yml

@@ -0,0 +1,42 @@
+name: Benchmark
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  benchmark:
+    name: Performance benchmarks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # required by auto-push to the gh-pages branch below
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run benchmarks
+        run: uv run pytest benchmarks/ --benchmark-json=output.json -v
+        env:
+          AGENT_TRACE_NETWORK_GUARD: "1"
+
+      - name: Store benchmark results
+        uses: benchmark-action/github-action-benchmark@52576c92bccf6ac60c8223ec7eb2565637cae9ba # v1
+        with:
+          tool: pytest
+          output-file-path: output.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          alert-threshold: "120%"
+          comment-on-alert: true
+          fail-on-alert: true
+          gh-pages-branch: gh-pages
+          benchmark-data-dir-path: dev/bench

agent_observability_trace_cli-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: quality (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/ benchmarks/
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check src/ tests/ benchmarks/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/ --strict
+
+      - name: Unit tests (overall ≥ 80%)
+        run: uv run pytest tests/unit/ --cov=src/ --cov-report=xml --cov-fail-under=80 -v
+        env:
+          AGENT_TRACE_NETWORK_GUARD: "1"
+
+      - name: Coverage gate — replay/ and interceptor/ each ≥ 90%
+        run: |
+          uv run pytest tests/unit/ \
+            --cov=src/agent_trace/_replay \
+            --cov=src/agent_trace/interceptor \
+            --cov-fail-under=90 \
+            -q --no-header
+        env:
+          AGENT_TRACE_NETWORK_GUARD: "1"
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
+        if: matrix.python-version == '3.12'
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+      - name: Security scan (Trivy)
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          scan-type: fs
+          format: sarif
+          output: trivy-results.sarif
+          severity: HIGH,CRITICAL
+
+      - name: Upload Trivy results
+        uses: github/codeql-action/upload-sarif@b7351df727350dca84cb9d725d57dcf5bc82ba26 # v3
+        if: always()
+        with:
+          sarif_file: trivy-results.sarif

agent_observability_trace_cli-0.1.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,22 @@
+name: Publish PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: dist

agent_observability_trace_cli-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for sigstore OIDC signing (does NOT cover the PyPI publish step below — see note)
+      contents: write   # required to create GitHub releases and upload assets
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      # Publishes with a long-lived PyPI API token (secrets.PYPI_TOKEN), NOT PyPI
+      # Trusted Publishing — id-token: write above is only consumed by the sigstore
+      # signing step further down. To remove the static-token risk entirely, register
+      # this workflow as a trusted publisher at
+      # https://pypi.org/manage/project/agent-trace/settings/publishing/
+      # (repo: RudrenduPaul/agent-observability, workflow: release.yml, environment: none),
+      # then replace this step with `pypa/gh-action-pypi-publish` and drop PYPI_TOKEN —
+      # that's a one-time manual step on pypi.org this workflow file can't perform for you.
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+      # SBOM — CycloneDX JSON (machine-readable) + XML (toolchain-compatible)
+      # cyclonedx-py 4.x CLI: `cyclonedx-py environment` generates from the
+      # active Python environment; outputs CycloneDX 1.6 by default.
+      - name: Generate SBOM (JSON + XML)
+        run: |
+          pip install cyclonedx-bom==4.5.0
+          cyclonedx-py environment --format JSON --output-file sbom.json
+          cyclonedx-py environment --format XML  --output-file sbom.xml
+
+      # SLSA Level 2 — sign dist artifacts with Sigstore via GitHub OIDC.
+      # Produces *.sigstore bundles alongside each dist file.
+      - name: Sign release artifacts (sigstore / SLSA Level 2)
+        uses: sigstore/gh-action-sigstore-python@5b79a39c381910c090341a2c9b0bf022c8b387e1 # v3.4.0
+        with:
+          inputs: dist/*.whl dist/*.tar.gz
+
+      # Upload to GitHub release: dist files + sigstore bundles + both SBOM formats
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.sigstore
+            sbom.json
+            sbom.xml
+          generate_release_notes: true

agent_observability_trace_cli-0.1.2/.github/workflows/scorecard.yml

@@ -0,0 +1,34 @@
+name: OpenSSF Scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "30 1 * * 6"
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+      contents: read
+      actions: read
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload results
+        uses: github/codeql-action/upload-sarif@b7351df727350dca84cb9d725d57dcf5bc82ba26 # v3
+        with:
+          sarif_file: results.sarif

agent_observability_trace_cli-0.1.2/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.sarif
+
+# Benchmarks output
+.benchmarks/
+benchmarks/results/latest.json
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets and local config
+.env
+.env.*
+*.pem
+*.key
+
+# agent-trace runtime data — fixture files contain API keys and prompt content
+.agent-trace/
+*.db
+fixture.db
+
+# Docs build
+docs/_build/
+docs/site/
+
+# Pre-commit
+.pre-commit-config.yaml.bak

agent_observability_trace_cli-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: no-commit-to-branch
+        args: [--branch, main]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        args: [--strict]
+        additional_dependencies:
+          - httpx>=0.27
+          - rich>=13.0
+          - types-requests>=2.31
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

agent_observability_trace_cli-0.1.2/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to agent-trace are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.2] - 2026-07-16
+
+### Added
+- gRPC transport interception (`pip install agent-trace[grpc]`) for LLM SDKs
+  that default to gRPC instead of REST (e.g. Vertex AI's mTLS-authenticated
+  path). Records/replays unary-unary and unary-stream gRPC calls the same
+  way `RecordingTransport`/`ReplayTransport` do for httpx; wired into
+  `Tracer._install_recording_transport`/`_uninstall_recording_transport` and
+  the replay engine alongside the existing httpx/requests patches. Covers
+  both sync `grpc` and async `grpc.aio` (unary-unary only for aio).
+- HTTP transport interception for `aiohttp.ClientSession` (`pip install agent-trace[aiohttp]`), closing a silent recording gap for LLM traffic routed through aiohttp-based clients (e.g. LiteLLM's default async transport)
+
+### Fixed
+- PyPI distribution renamed to `agent-observability-trace` to match the name actually registered on PyPI (import path is unchanged: `import agent_trace`)
+- `Author` field on PyPI linked to Rudrendu's personal email under Sourav's displayed name; authors are now name-only with GitHub profile links in `project.urls`
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Core span and trace data model (`Span`, `Trace`, `SpanStatus`)
+- Clock abstraction (`core/clock.py`) enabling deterministic replay
+- HTTP transport interception for `httpx` and `requests`
+- SQLite-backed fixture store (`replay/fixture.py`) for record/replay
+- Replay engine with `AGENT_TRACE_NETWORK_GUARD` enforcement
+- `@tracer.instrument(record=True)` decorator API
+- `tracer.span()` context manager for manual span creation
+- LangGraph callback handler integration (`pip install agent-trace[langgraph]`)
+- OpenAI Agents SDK hook integration (`pip install agent-trace[openai-agents]`)
+- OTLP exporter for Jaeger/Grafana Tempo (`pip install agent-trace[otlp]`)
+- `stdout` and `file` exporters
+- Three benchmark scripts: overhead, fidelity, ingestion
+- CI pipeline with ruff, mypy --strict, pytest, Trivy, OpenSSF Scorecard
+- Apache 2.0 license

agent_observability_trace_cli-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,151 @@
+# Contributing to agent-observability
+
+Thank you for your interest in contributing. This guide covers everything you need to get started, from setting up a local dev environment to getting your PR merged quickly.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10 or later
+- [uv](https://github.com/astral-sh/uv) (install via `curl -Lf https://astral.sh/uv/install.sh | sh`)
+- Git
+
+### First-time setup
+
+```bash
+git clone https://github.com/RudrenduPaul/agent-observability.git
+cd agent-observability
+uv sync --extra dev
+pre-commit install
+```
+
+### Verify your setup
+
+```bash
+uv run pytest tests/unit/ -q
+```
+
+All tests should pass before you make any changes. If they don't, open an issue.
+
+---
+
+## Engineering Standards
+
+Every PR must pass the full quality gate before it can merge. Run these locally before pushing:
+
+```bash
+# Lint and format
+uv run ruff check src/ tests/ benchmarks/
+uv run ruff format --check src/ tests/ benchmarks/
+
+# Type checking — zero errors required
+uv run mypy src/ --strict
+
+# Unit tests with coverage gate
+uv run pytest tests/unit/ --cov=src/ --cov-fail-under=80 -v
+```
+
+### Style conventions
+
+- **Formatter:** `ruff format` (88-char line length, no manual overrides)
+- **Linter:** `ruff check` with the ruleset in `pyproject.toml` — do not add `# noqa` without a comment explaining why
+- **Types:** All public functions must be fully typed. Internal helpers too, unless the type annotation would be genuinely unreadable
+- **Docstrings:** Public API functions need a one-line summary. Private helpers do not require docstrings
+
+### What makes a PR merge quickly
+
+1. **One concern per PR.** A PR that fixes a bug and refactors three unrelated modules will be asked to split. Reviewers review the whole diff — keep it small and reviewable.
+2. **Tests for every behavior change.** If you add a feature, add a unit test. If you fix a bug, add a regression test that would have caught it.
+3. **CHANGELOG.md entry.** Every user-facing change goes under `## [Unreleased]`. Internal refactors and CI changes do not need an entry.
+4. **Passing CI before requesting review.** The CI matrix runs on Python 3.10–3.13. Fix failures before pinging for review.
+5. **Clear PR description.** Fill in the PR template. Reviewers should not have to ask "what does this do?" after reading your description.
+
+---
+
+## Integration Tests
+
+Integration tests hit real external APIs (OpenAI, Anthropic, etc.) and are never mocked. They are gated behind the `@pytest.mark.integration` marker and excluded from the standard CI run.
+
+**Rules:**
+- Integration tests live in `tests/integration/`
+- Every integration test must be decorated with `@pytest.mark.integration`
+- Do not mock API calls in integration tests — that is what unit tests with `respx` are for
+- Integration tests must be self-contained: they must set up and tear down any state they create
+- Secrets are injected via environment variables, never hardcoded
+
+**Running integration tests locally:**
+
+```bash
+export OPENAI_API_KEY=sk-...
+uv run pytest tests/integration/ -m integration -v
+```
+
+**CI policy:** Integration tests do not run in CI by default. They run in a separate scheduled workflow against maintainer-controlled secrets. If your PR requires integration test coverage, mention it in the PR description.
+
+---
+
+## Benchmark PRs
+
+If your change touches any of the following, it is a benchmark-sensitive PR and requires a benchmark comparison:
+
+- `src/agent_trace/core/` — span/trace data model
+- `src/agent_trace/transport/` — HTTP interceptors
+- `src/agent_trace/replay/` — fixture store or replay engine
+- Any change to serialization or deserialization paths
+
+**How to run benchmarks and attach the output:**
+
+```bash
+# First run on main to establish baseline
+git checkout main
+uv run pytest benchmarks/ --benchmark-save=baseline
+
+# Apply your changes, then compare
+git checkout your-branch
+uv run pytest benchmarks/ --benchmark-compare=baseline --benchmark-compare-fail=mean:10%
+```
+
+Paste the comparison table into your PR description under "Benchmark impact". PRs that regress mean latency by more than 10% will not merge without a compelling justification.
+
+---
+
+## Response SLAs
+
+We aim to respond within these windows on business days (Pacific Time):
+
+| Type | Target |
+|------|--------|
+| Bug reports | 24 hours |
+| Feature requests | 72 hours |
+| Pull requests | 72 hours |
+
+Response means "acknowledged, triaged, or reviewed" — not necessarily resolved. If your issue or PR is approaching these windows with no response, a single polite ping in the thread is welcome.
+
+---
+
+## AI-Assisted Contributions
+
+AI tools (Copilot, Claude, GPT-4, etc.) are permitted and can speed up boilerplate-heavy work. However:
+
+- **You are responsible for every line you submit.** "The AI wrote it" is not a defense for a security issue, incorrect logic, or a type error.
+- Read and understand every generated line before submitting.
+- Indicate in your PR description if the implementation is AI-assisted. This is for the reviewer's awareness, not a negative mark.
+- Do not submit AI-generated tests that only test the happy path. Tests must cover edge cases and failure modes.
+
+---
+
+## Good First Issues
+
+Looking for somewhere to start? Filter the issue tracker by these labels:
+
+- [`good first issue`](https://github.com/RudrenduPaul/agent-observability/labels/good%20first%20issue) — small, well-scoped tasks with clear acceptance criteria
+- [`docs`](https://github.com/RudrenduPaul/agent-observability/labels/docs) — documentation improvements, typo fixes, example additions
+- [`help wanted`](https://github.com/RudrenduPaul/agent-observability/labels/help%20wanted) — medium-complexity issues where a contributor's perspective would be valuable
+
+If you plan to work on an issue, leave a comment so we can assign it and avoid duplication.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0. See `LICENSE` for details.