nero-client 0.1.0__tar.gz

nero_client-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+.planning
+.claude

nero_client-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: nero-client
+Version: 0.1.0
+Summary: Lightweight Python client for the Nero voice-agent monitoring platform
+Project-URL: Homepage, https://github.com/nurixlabs/nero
+Project-URL: Documentation, https://docs.nero.dev
+Author: Nero Team
+License: MIT
+Keywords: monitoring,nero,observability,voice-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nero-client
+
+Lightweight Python client for the [Nero](https://nero.dev) voice-agent monitoring platform.
+
+## Installation
+
+```bash
+pip install nero-client
+```
+
+## Quick start
+
+```python
+from nero_client import NeroClient
+
+nero = NeroClient(api_key="nero_...")
+
+nero.end_session(
+    transcript=[
+        {"role": "assistant", "content": "Hi, this is Alex from ...", "timestamp": "2026-04-09T10:00:01Z"},
+        {"role": "user", "content": "I'm not interested", "timestamp": "2026-04-09T10:00:04Z"},
+    ],
+    latency_metrics={"stt_ms": 180, "llm_ms": 620, "tts_ms": 240, "round_trip_ms": 1040},
+    tool_calls=[{"name": "lookup_customer", "params": {"phone": "+1234567890"}, "result": {"name": "Jane"}}],
+    metadata={"caller_id": "+1234567890", "campaign": "q2_upsell", "duration_ms": 45000},
+)
+```
+
+### Async
+
+```python
+await nero.end_session_async(transcript=[...])
+```
+
+### Configuration
+
+| Parameter | Env var | Default |
+|-----------|---------|---------|
+| `api_key` | `NERO_API_KEY` | _(required)_ |
+| `base_url` | `NERO_BASE_URL` | `https://api.nero.dev` |
+| `timeout` | — | `10.0` |
+| `max_retries` | — | `3` |
+
+## License
+
+MIT

nero_client-0.1.0/README.md

@@ -0,0 +1,46 @@
+# nero-client
+
+Lightweight Python client for the [Nero](https://nero.dev) voice-agent monitoring platform.
+
+## Installation
+
+```bash
+pip install nero-client
+```
+
+## Quick start
+
+```python
+from nero_client import NeroClient
+
+nero = NeroClient(api_key="nero_...")
+
+nero.end_session(
+    transcript=[
+        {"role": "assistant", "content": "Hi, this is Alex from ...", "timestamp": "2026-04-09T10:00:01Z"},
+        {"role": "user", "content": "I'm not interested", "timestamp": "2026-04-09T10:00:04Z"},
+    ],
+    latency_metrics={"stt_ms": 180, "llm_ms": 620, "tts_ms": 240, "round_trip_ms": 1040},
+    tool_calls=[{"name": "lookup_customer", "params": {"phone": "+1234567890"}, "result": {"name": "Jane"}}],
+    metadata={"caller_id": "+1234567890", "campaign": "q2_upsell", "duration_ms": 45000},
+)
+```
+
+### Async
+
+```python
+await nero.end_session_async(transcript=[...])
+```
+
+### Configuration
+
+| Parameter | Env var | Default |
+|-----------|---------|---------|
+| `api_key` | `NERO_API_KEY` | _(required)_ |
+| `base_url` | `NERO_BASE_URL` | `https://api.nero.dev` |
+| `timeout` | — | `10.0` |
+| `max_retries` | — | `3` |
+
+## License
+
+MIT

nero_client-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nero-client"
+version = "0.1.0"
+description = "Lightweight Python client for the Nero voice-agent monitoring platform"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    { name = "Nero Team" },
+]
+keywords = ["nero", "voice-agent", "monitoring", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/nurixlabs/nero"
+Documentation = "https://docs.nero.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nero_client"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

nero_client-0.1.0/src/nero_client/__init__.py

@@ -0,0 +1,17 @@
+"""nero-client — Lightweight Python client for the Nero voice-agent monitoring platform."""
+
+from .client import NeroClient
+from .exceptions import (
+    NeroAuthError,
+    NeroError,
+    NeroTransportError,
+    NeroValidationError,
+)
+
+__all__ = [
+    "NeroClient",
+    "NeroError",
+    "NeroAuthError",
+    "NeroValidationError",
+    "NeroTransportError",
+]

nero_client-0.1.0/src/nero_client/client.py

@@ -0,0 +1,214 @@
+"""Nero client — lightweight session reporter for voice agents."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .exceptions import NeroAuthError, NeroTransportError, NeroValidationError
+
+logger = logging.getLogger("nero_client")
+
+_DEFAULT_BASE_URL = "https://api.nero.dev"
+_DEFAULT_TIMEOUT = 10.0
+_DEFAULT_MAX_RETRIES = 3
+_BACKOFF_BASE = 1  # seconds — retries at 1s, 3s, 9s (×3 each)
+_BACKOFF_MULTIPLIER = 3
+_SESSIONS_PATH = "/v1/sessions"
+
+
+class NeroClient:
+    """Client for sending voice-agent session data to the Nero platform.
+
+    Args:
+        api_key: Nero API key (``nero_...``). Falls back to ``NERO_API_KEY`` env var.
+        base_url: Nero API base URL. Falls back to ``NERO_BASE_URL`` env var,
+            then to ``https://api.nero.dev``.
+        timeout: HTTP request timeout in seconds.
+        max_retries: Number of retries on transient (5xx / timeout) failures.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("NERO_API_KEY", "")
+        if not self.api_key:
+            raise NeroAuthError(
+                "API key is required. Pass api_key= or set NERO_API_KEY env var."
+            )
+
+        self.base_url = (
+            base_url or os.environ.get("NERO_BASE_URL", _DEFAULT_BASE_URL)
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def end_session(
+        self,
+        transcript: List[Dict[str, Any]],
+        latency_metrics: Optional[Dict[str, Any]] = None,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, str]:
+        """Send a completed session to Nero (synchronous).
+
+        Returns:
+            ``{"conversation_id": "<uuid>"}`` on success.
+
+        Raises:
+            NeroAuthError: 401 — invalid API key.
+            NeroValidationError: 422 — malformed payload.
+            NeroTransportError: After retries exhausted on 5xx / timeout.
+        """
+        payload = self._build_payload(transcript, latency_metrics, tool_calls, metadata)
+        return self._post_with_retry(payload)
+
+    async def end_session_async(
+        self,
+        transcript: List[Dict[str, Any]],
+        latency_metrics: Optional[Dict[str, Any]] = None,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, str]:
+        """Send a completed session to Nero (async).
+
+        Returns:
+            ``{"conversation_id": "<uuid>"}`` on success.
+
+        Raises:
+            NeroAuthError: 401 — invalid API key.
+            NeroValidationError: 422 — malformed payload.
+            NeroTransportError: After retries exhausted on 5xx / timeout.
+        """
+        payload = self._build_payload(transcript, latency_metrics, tool_calls, metadata)
+        return await self._post_with_retry_async(payload)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _build_payload(
+        self,
+        transcript: List[Dict[str, Any]],
+        latency_metrics: Optional[Dict[str, Any]],
+        tool_calls: Optional[List[Dict[str, Any]]],
+        metadata: Optional[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        if not transcript:
+            raise NeroValidationError("transcript must be a non-empty list")
+
+        payload: Dict[str, Any] = {"transcript": transcript}
+        if latency_metrics is not None:
+            payload["latency_metrics"] = latency_metrics
+        if tool_calls is not None:
+            payload["tool_calls"] = tool_calls
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return payload
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _url(self) -> str:
+        return f"{self.base_url}{_SESSIONS_PATH}"
+
+    # ---- sync retry loop ---------------------------------------------
+
+    def _post_with_retry(self, payload: Dict[str, Any]) -> Dict[str, str]:
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                with httpx.Client(timeout=self.timeout) as client:
+                    resp = client.post(
+                        self._url(), json=payload, headers=self._headers()
+                    )
+                return self._handle_response(resp)
+            except (NeroAuthError, NeroValidationError):
+                raise
+            except httpx.HTTPStatusError as exc:
+                last_exc = exc
+            except httpx.TransportError as exc:
+                last_exc = exc
+
+            if attempt < self.max_retries:
+                delay = _BACKOFF_BASE * (_BACKOFF_MULTIPLIER**attempt)
+                logger.warning(
+                    "Nero: request failed (attempt %d/%d), retrying in %ds — %s",
+                    attempt + 1,
+                    self.max_retries + 1,
+                    delay,
+                    last_exc,
+                )
+                time.sleep(delay)
+
+        raise NeroTransportError(
+            f"Failed after {self.max_retries + 1} attempts: {last_exc}"
+        ) from last_exc
+
+    # ---- async retry loop --------------------------------------------
+
+    async def _post_with_retry_async(
+        self, payload: Dict[str, Any]
+    ) -> Dict[str, str]:
+        import asyncio
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    resp = await client.post(
+                        self._url(), json=payload, headers=self._headers()
+                    )
+                return self._handle_response(resp)
+            except (NeroAuthError, NeroValidationError):
+                raise
+            except httpx.HTTPStatusError as exc:
+                last_exc = exc
+            except httpx.TransportError as exc:
+                last_exc = exc
+
+            if attempt < self.max_retries:
+                delay = _BACKOFF_BASE * (_BACKOFF_MULTIPLIER**attempt)
+                logger.warning(
+                    "Nero: request failed (attempt %d/%d), retrying in %ds — %s",
+                    attempt + 1,
+                    self.max_retries + 1,
+                    delay,
+                    last_exc,
+                )
+                await asyncio.sleep(delay)
+
+        raise NeroTransportError(
+            f"Failed after {self.max_retries + 1} attempts: {last_exc}"
+        ) from last_exc
+
+    # ---- response handling -------------------------------------------
+
+    @staticmethod
+    def _handle_response(resp: httpx.Response) -> Dict[str, str]:
+        if resp.status_code == 401:
+            raise NeroAuthError("Invalid or revoked API key")
+        if resp.status_code == 422:
+            detail = resp.json().get("detail") if resp.content else None
+            raise NeroValidationError("Payload validation failed", detail=detail)
+        if resp.status_code >= 500:
+            resp.raise_for_status()  # raises httpx.HTTPStatusError → caught by retry
+        if resp.status_code >= 400:
+            resp.raise_for_status()
+
+        return resp.json()

nero_client-0.1.0/src/nero_client/exceptions.py

@@ -0,0 +1,23 @@
+"""Nero client exceptions."""
+
+from __future__ import annotations
+
+
+class NeroError(Exception):
+    """Base exception for all Nero client errors."""
+
+
+class NeroAuthError(NeroError):
+    """Raised on 401 — invalid or revoked API key. Not retried."""
+
+
+class NeroValidationError(NeroError):
+    """Raised on 422 — malformed payload. Not retried."""
+
+    def __init__(self, message: str, detail: object = None) -> None:
+        super().__init__(message)
+        self.detail = detail
+
+
+class NeroTransportError(NeroError):
+    """Raised after retries are exhausted on 5xx / timeout / connection error."""

nero_client-0.1.0/tests/test_client.py

@@ -0,0 +1,201 @@
+"""Tests for nero_client."""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+import respx
+
+from nero_client import (
+    NeroAuthError,
+    NeroClient,
+    NeroTransportError,
+    NeroValidationError,
+)
+
+API_KEY = "nero_test1234567890"
+BASE_URL = "https://api.nero.test"
+SESSIONS_URL = f"{BASE_URL}/v1/sessions"
+
+SAMPLE_TRANSCRIPT = [
+    {"role": "assistant", "content": "Hi there!", "timestamp": "2026-04-09T10:00:01Z"},
+    {"role": "user", "content": "Not interested", "timestamp": "2026-04-09T10:00:04Z"},
+]
+
+
+def _make_client(**kwargs) -> NeroClient:
+    defaults = {"api_key": API_KEY, "base_url": BASE_URL}
+    defaults.update(kwargs)
+    return NeroClient(**defaults)
+
+
+# ------------------------------------------------------------------
+# Initialization
+# ------------------------------------------------------------------
+
+
+class TestInit:
+    def test_requires_api_key(self):
+        with pytest.raises(NeroAuthError, match="API key is required"):
+            NeroClient()
+
+    def test_api_key_from_env(self, monkeypatch):
+        monkeypatch.setenv("NERO_API_KEY", API_KEY)
+        client = NeroClient(base_url=BASE_URL)
+        assert client.api_key == API_KEY
+
+    def test_base_url_from_env(self, monkeypatch):
+        monkeypatch.setenv("NERO_BASE_URL", "https://custom.nero.test")
+        client = NeroClient(api_key=API_KEY)
+        assert client.base_url == "https://custom.nero.test"
+
+    def test_defaults(self):
+        client = _make_client()
+        assert client.timeout == 10.0
+        assert client.max_retries == 3
+
+
+# ------------------------------------------------------------------
+# Sync end_session
+# ------------------------------------------------------------------
+
+
+class TestEndSession:
+    @respx.mock
+    def test_success(self):
+        respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(
+                202, json={"conversation_id": "conv-123"}
+            )
+        )
+        client = _make_client()
+        result = client.end_session(transcript=SAMPLE_TRANSCRIPT)
+        assert result == {"conversation_id": "conv-123"}
+
+    @respx.mock
+    def test_sends_full_payload(self):
+        route = respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(
+                202, json={"conversation_id": "conv-456"}
+            )
+        )
+        client = _make_client()
+        client.end_session(
+            transcript=SAMPLE_TRANSCRIPT,
+            latency_metrics={"stt_ms": 100, "llm_ms": 200, "tts_ms": 150, "round_trip_ms": 450},
+            tool_calls=[{"name": "lookup", "params": {"id": "1"}, "result": {"ok": True}}],
+            metadata={"caller_id": "+1234", "campaign": "test"},
+        )
+
+        sent = route.calls[0].request
+        import json
+        body = json.loads(sent.content)
+        assert body["transcript"] == SAMPLE_TRANSCRIPT
+        assert body["latency_metrics"]["stt_ms"] == 100
+        assert body["tool_calls"][0]["name"] == "lookup"
+        assert body["metadata"]["campaign"] == "test"
+
+    @respx.mock
+    def test_bearer_token_sent(self):
+        route = respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(202, json={"conversation_id": "c"})
+        )
+        _make_client().end_session(transcript=SAMPLE_TRANSCRIPT)
+        auth = route.calls[0].request.headers["authorization"]
+        assert auth == f"Bearer {API_KEY}"
+
+    def test_empty_transcript_raises(self):
+        client = _make_client()
+        with pytest.raises(NeroValidationError, match="non-empty"):
+            client.end_session(transcript=[])
+
+    @respx.mock
+    def test_401_raises_auth_error(self):
+        respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(401, json={"detail": "invalid key"})
+        )
+        with pytest.raises(NeroAuthError):
+            _make_client().end_session(transcript=SAMPLE_TRANSCRIPT)
+
+    @respx.mock
+    def test_422_raises_validation_error(self):
+        respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(
+                422, json={"detail": [{"msg": "bad field"}]}
+            )
+        )
+        with pytest.raises(NeroValidationError):
+            _make_client().end_session(transcript=SAMPLE_TRANSCRIPT)
+
+    @respx.mock
+    def test_retries_on_500(self):
+        route = respx.post(SESSIONS_URL)
+        route.side_effect = [
+            httpx.Response(500),
+            httpx.Response(500),
+            httpx.Response(202, json={"conversation_id": "conv-ok"}),
+        ]
+        client = _make_client(max_retries=2)
+        result = client.end_session(transcript=SAMPLE_TRANSCRIPT)
+        assert result == {"conversation_id": "conv-ok"}
+        assert route.call_count == 3
+
+    @respx.mock
+    def test_exhausts_retries_raises_transport_error(self):
+        respx.post(SESSIONS_URL).mock(return_value=httpx.Response(503))
+        client = _make_client(max_retries=1)
+        with pytest.raises(NeroTransportError, match="2 attempts"):
+            client.end_session(transcript=SAMPLE_TRANSCRIPT)
+
+    @respx.mock
+    def test_no_retry_on_401(self):
+        route = respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(401, json={"detail": "bad key"})
+        )
+        with pytest.raises(NeroAuthError):
+            _make_client().end_session(transcript=SAMPLE_TRANSCRIPT)
+        assert route.call_count == 1
+
+
+# ------------------------------------------------------------------
+# Async end_session_async
+# ------------------------------------------------------------------
+
+
+class TestEndSessionAsync:
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_success(self):
+        respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(
+                202, json={"conversation_id": "async-123"}
+            )
+        )
+        client = _make_client()
+        result = await client.end_session_async(transcript=SAMPLE_TRANSCRIPT)
+        assert result == {"conversation_id": "async-123"}
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_retries_on_500(self):
+        route = respx.post(SESSIONS_URL)
+        route.side_effect = [
+            httpx.Response(500),
+            httpx.Response(202, json={"conversation_id": "async-ok"}),
+        ]
+        client = _make_client(max_retries=1)
+        result = await client.end_session_async(transcript=SAMPLE_TRANSCRIPT)
+        assert result == {"conversation_id": "async-ok"}
+        assert route.call_count == 2
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_401_raises_immediately(self):
+        route = respx.post(SESSIONS_URL).mock(
+            return_value=httpx.Response(401, json={"detail": "bad"})
+        )
+        with pytest.raises(NeroAuthError):
+            await _make_client().end_session_async(transcript=SAMPLE_TRANSCRIPT)
+        assert route.call_count == 1