voxgraph 0.2.0__tar.gz

voxgraph-0.2.0/.env.example

@@ -0,0 +1,14 @@
+# Voxgraph SDK — environment variables
+# Copy to .env and fill in your values.
+
+# Required: your API key from the Voxgraph dashboard
+VOXGRAPH_API_KEY=vxg_your_api_key_here
+
+# Optional: UUID of your agent (from the Voxgraph dashboard)
+# VOXGRAPH_AGENT_ID=550e8400-e29b-41d4-a716-446655440000
+
+# Optional: prompt branch to use (default: "main")
+# VOXGRAPH_ENVIRONMENT=main
+
+# Optional: enable verbose SDK debug logging (default: false)
+# VOXGRAPH_DEBUG=false

voxgraph-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: CI / Publish
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: ["main"]
+
+# Deny all permissions by default — each job grants only what it needs.
+permissions: read-all
+
+# Cancel in-progress runs on the same branch/tag to save Actions minutes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  # ──────────────────────────────────────────────────────────────────
+  # Job 1: Run the full test suite on every push and PR
+  # ──────────────────────────────────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      # SHA-pinned to prevent supply-chain attacks via tag mutation.
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5.4.2
+
+      - name: Install dependencies (dev extras)
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  # ──────────────────────────────────────────────────────────────────
+  # Job 2: Build + publish to PyPI — ONLY on a v*.*.* tag push.
+  # Uses PyPI Trusted Publisher (OIDC) — no API token required.
+  # Generates PEP 740 provenance attestations for supply-chain transparency.
+  # ──────────────────────────────────────────────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: test                         # tests must pass first
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write                   # required for OIDC token minting
+      attestations: write               # required for provenance attestation
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/voxgraph/
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5.4.2
+
+      - name: Build distribution packages
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true            # PEP 740 — cryptographic provenance proof
+        # No username/password needed — OIDC handles authentication.

voxgraph-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment / secrets
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# Dev scratch / debug output
+out.txt
+test_audio_hook.py

voxgraph-0.2.0/LICENSE

@@ -0,0 +1,92 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** includes copying, distributing, making available, and preparing
+derivative works of the software.

voxgraph-0.2.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: voxgraph
+Version: 0.2.0
+Summary: Observability SDK for LiveKit voice agents — captures prompts, metrics, logs, and latency data.
+Project-URL: Homepage, https://voxgraph.io
+Project-URL: Repository, https://github.com/voxgraph/voxgraph-sdk
+Project-URL: Documentation, https://docs.voxgraph.io/sdk
+License: Elastic License 2.0
+        
+        URL: https://www.elastic.co/licensing/elastic-license
+        
+        ## Acceptance
+        
+        By using the software, you agree to all of the terms and conditions below.
+        
+        ## Copyright License
+        
+        The licensor grants you a non-exclusive, royalty-free, worldwide,
+        non-sublicensable, non-transferable license to use, copy, distribute, make
+        available, and prepare derivative works of the software, in each case subject
+        to the limitations and conditions below.
+        
+        ## Limitations
+        
+        You may not provide the software to third parties as a hosted or managed
+        service, where the service provides users with access to any substantial set of
+        the features or functionality of the software.
+        
+        You may not move, change, disable, or circumvent the license key functionality
+        in the software, and you may not remove or obscure any functionality in the
+        software that is protected by the license key.
+        
+        You may not alter, remove, or obscure any licensing, copyright, or other notices
+        of the licensor in the software. Any use of the licensor's trademarks is subject
+        to applicable law.
+        
+        ## Patents
+        
+        The licensor grants you a license, under any patent claims the licensor can
+        license, or becomes able to license, to make, have made, use, sell, offer for
+        sale, import and have imported the software, in each case subject to the
+        limitations and conditions in this license. This license does not cover any
+        patent claims that you cause to be infringed by modifications or additions to
+        the software. If you or your company make any written claim that the software
+        infringes or contributes to infringement of any patent, your patent license for
+        the software granted under these terms ends immediately. If your company makes
+        such a claim, your patent license ends immediately for work on behalf of your
+        company.
+        
+        ## Notices
+        
+        You must ensure that anyone who gets a copy of any part of the software from you
+        also gets a copy of these terms.
+        
+        If you modify the software, you must include in any modified copies of the
+        software prominent notices stating that you have modified the software.
+        
+        ## No Other Rights
+        
+        These terms do not imply any licenses other than those expressly granted in
+        these terms.
+        
+        ## Termination
+        
+        If you use the software in violation of these terms, such use is not licensed,
+        and your licenses will automatically terminate. If the licensor provides you
+        with a notice of your violation, and you cease all violation of this license no
+        later than 30 days after you receive that notice, your licenses will be
+        reinstated retroactively. However, if you violate these terms after such
+        reinstatement, any additional violation of these terms will cause your licenses
+        to terminate automatically and permanently.
+        
+        ## No Liability
+        
+        *As far as the law allows, the software comes as is, without any warranty or
+        condition, and the licensor will not be liable to you for any damages arising
+        out of these terms or the use or nature of the software, under any kind of
+        legal claim.*
+        
+        ## Definitions
+        
+        The **licensor** is the entity offering these terms, and the **software** is the
+        software the licensor makes available under these terms, including any portion
+        of it.
+        
+        **you** refers to the individual or entity agreeing to these terms.
+        
+        **your company** is any legal entity, sole proprietorship, or other kind of
+        organization that you work for, plus all organizations that have control over,
+        are under the control of, or are under common control with that organization.
+        **control** means ownership of substantially all the assets of an entity, or the
+        power to direct its management and policies by vote, contract, or otherwise.
+        Control can be direct or indirect.
+        
+        **your licenses** are all the licenses granted to you for the software under
+        these terms.
+        
+        **use** includes copying, distributing, making available, and preparing
+        derivative works of the software.
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: av>=12.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: livekit-agents<2.0,>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Voxgraph SDK
+
+> Observability for LiveKit Voice Agents — see what happens inside the "black box" between user speech and agent response.
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-Elastic%20License%202.0-lightgrey.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-typed-brightgreen.svg)](https://peps.python.org/pep-0561/)
+
+## Access
+
+> **This SDK requires a Voxgraph API key.**
+>
+> The SDK sends telemetry exclusively to the Voxgraph backend. Without a valid API key issued by Voxgraph, all telemetry is silently discarded. Contact your Voxgraph account team to obtain credentials.
+
+## What does it do?
+
+LiveKit tells you *the voice was slow*. Voxgraph tells you **why your code made the voice slow**.
+
+The Voxgraph SDK wraps your LiveKit `AgentSession` and captures:
+
+| Signal | Detail |
+|---|---|
+| **Logs** | Contextually linked to conversation turns |
+| **Prompts** | Versioned & captured per session |
+| **Latency** | Code-level waterfall (STT → Your Code → LLM → TTS) |
+| **Costs** | Token/USD breakdown per turn |
+| **Metrics** | Structured, typed, and batched |
+
+## Quick Start
+
+### Install
+
+```bash
+pip install voxgraph
+```
+
+### Integrate (2 lines of change)
+
+```python
+from livekit.agents import AgentSession, Agent, AgentServer
+from voxgraph import VoxSession  # ← add this import
+
+class MyAgent(Agent):
+    def __init__(self):
+        super().__init__(instructions="You are a helpful assistant.")
+
+    async def on_enter(self):
+        self.session.generate_reply()
+
+server = AgentServer()
+
+@server.rtc_session()
+async def entrypoint(ctx):
+    session = AgentSession(
+        stt="deepgram/nova-3:multi",
+        llm="openai/gpt-4.1-mini",
+        tts="cartesia/sonic-3",
+    )
+
+    # ← Wrap with VoxSession — one arg, done
+    vox = VoxSession(session, api_key="vxg_...", agent_id="<your-agent-id>")
+
+    await vox.start(agent=MyAgent(), room=ctx.room)
+    # Shutdown callback is auto-registered via get_job_context()
+```
+
+That's it. The SDK automatically:
+- ✅ Captures session report at call end (transcripts, latency, tool calls, events)
+- ✅ Aggregates LLM token counts, STT audio duration, TTS character counts
+- ✅ Tags your Python logs with the current session context
+- ✅ Sends telemetry to the Voxgraph backend in non-blocking batches
+- ✅ Drains all buffered data on session shutdown (cancel-safe)
+
+## VoxSession Parameters
+
+```python
+VoxSession(
+    session,
+    api_key="vxg_...",
+    agent_id="...",
+    environment="main",
+    tags={},
+    enable_recording=False,
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `session` | `AgentSession` | *(required)* | The LiveKit `AgentSession` to observe |
+| `api_key` | `str \| None` | `None` | Voxgraph API key. Falls back to `VOXGRAPH_API_KEY` env var if not passed. A warning is emitted and telemetry is discarded if neither is set. |
+| `agent_id` | `str \| None` | `None` | UUID of your agent from the Voxgraph dashboard. Required for prompt fetch and usage attribution. Falls back to `VOXGRAPH_AGENT_ID` env var. |
+| `environment` | `str \| None` | `"main"` | Prompt branch to fetch (`"main"`, `"dev"`, `"staging"`, etc.). Falls back to `VOXGRAPH_ENVIRONMENT` env var. |
+| `tags` | `dict[str, str] \| None` | `{}` | Arbitrary key-value metadata attached to the session report (e.g. `{"customer_tier": "enterprise"}`). |
+| `enable_recording` | `bool` | `False` | When `True`, captures session audio (user mic + agent TTS as stereo Opus/OGG) and uploads it to Voxgraph-managed storage. See [Session Recording](#session-recording). |
+
+## Debug Mode
+
+Set `VOXGRAPH_DEBUG=true` to see captured telemetry printed to stdout without sending it to the backend:
+
+```bash
+VOXGRAPH_DEBUG=true python agent.py console
+```
+
+## Session Recording
+
+To capture full session audio (user mic + agent TTS as a stereo Opus/OGG file):
+
+```python
+vox = VoxSession(session, api_key="vxg_abc123", enable_recording=True)
+```
+
+> **⚠️ Recording & Consent — Operator Responsibility**
+>
+> Setting `enable_recording=True` captures audio from **both** call participants and uploads it to Voxgraph-managed S3 storage. Recording is **disabled by default** (`enable_recording=False`).
+>
+> As the operator deploying this SDK, **you are solely responsible** for:
+> - Obtaining explicit user consent before enabling recording
+> - Complying with applicable laws in your jurisdiction, including:
+>   - **GDPR** (EU) — voice recordings may qualify as biometric data; explicit prior consent required
+>   - **CCPA/CPRA** (California) — voice recordings are biometric information; notice at collection required
+>   - **US wiretapping laws** — ~13 states (CA, IL, FL, MA, WA, etc.) require all-party consent; phone calls (`call_channel: "phone"`) carry the strictest requirements
+>   - **EU AI Act** (August 2026) — AI-human interactions must be disclosed
+
+## Context-Aware Logging
+
+Any Python logger automatically gets tagged with the current session:
+
+```python
+import logging
+logger = logging.getLogger(__name__)
+
+@function_tool
+async def check_inventory(ctx, product_id: str):
+    logger.info(f"Checking stock for {product_id}")  # ← automatically tagged
+    result = await db.query(product_id)
+    return result
+```
+
+Or use the pre-configured structured logger:
+
+```python
+from voxgraph import vox_logger
+
+vox_logger.info("Querying database", product_id=123, stock=True)
+# Output: {"event": "Querying database", "product_id": 123, "vox_session_id": "vox_...", ...}
+```
+
+## Architecture
+
+```
+Your Agent Code
+      │
+      ▼
+┌─────────────────────┐
+│   VoxSession        │  ← Composition wrapper (does NOT extend AgentSession)
+│                     │
+│  ┌───────────────┐  │
+│  │ Log Handler   │  │  ← Tags Python logs with ContextVar session ID
+│  └───────┬───────┘  │
+│          │          │
+│  ┌───────▼───────┐  │
+│  │ Telemetry     │  │  ← Async queue → batched HTTP with retry + backoff
+│  │ Sender        │  │
+│  └───────────────┘  │
+│                     │
+│  ┌───────────────┐  │
+│  │ AudioRecorder │  │  ← Optional. RecorderIO + S3 streaming upload
+│  └───────────────┘  │
+└─────────────────────┘
+      │
+      ▼
+  Voxgraph Backend
+```
+
+## License
+
+[Elastic License 2.0](LICENSE) — free to use, not for competing hosted services.