prodloop-observability-sdk 0.1.0__py3-none-any.whl

prodloop/__init__.py

@@ -0,0 +1,11 @@
+from prodloop.client import ProdloopClient
+from prodloop.exceptions import APIError, ProdloopError, ValidationError
+from prodloop.models import EvaluationParameter
+
+__all__ = [
+    "ProdloopClient",
+    "EvaluationParameter",
+    "ProdloopError",
+    "ValidationError",
+    "APIError",
+]

prodloop/client.py

@@ -0,0 +1,125 @@
+import json
+import mimetypes
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping, Optional, Sequence
+
+import requests
+
+from prodloop.exceptions import APIError, ValidationError
+from prodloop.models import EvaluationParameter, ParameterInput, coerce_parameter
+
+
+class ProdloopClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://asia-south1-prodloop.cloudfunctions.net/prodloop-evaluator-fn",
+        timeout_seconds: int = 180,
+        session: Optional[requests.Session] = None,
+    ):
+        if not api_key or not api_key.strip():
+            raise ValidationError("api_key is required.")
+        if not base_url or not base_url.strip():
+            raise ValidationError("base_url is required.")
+
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self._session = session or requests.Session()
+
+    def evaluate_call(
+        self,
+        audio_file_path: str,
+        parameters: Sequence[ParameterInput],
+        thresholds: Optional[Mapping[str, Any]] = None,
+        extraction_schema: Optional[Mapping[str, str]] = None,
+        bot_captured_variables: Optional[Mapping[str, Any]] = None,
+        timeout_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        normalized_parameters = self._normalize_parameters(parameters)
+        payload: Dict[str, Any] = {
+            "parameters": [param.value for param in normalized_parameters],
+        }
+
+        if thresholds:
+            payload["thresholds"] = dict(thresholds)
+        if extraction_schema:
+            payload["extraction_schema"] = dict(extraction_schema)
+        if bot_captured_variables:
+            payload["bot_captured_variables"] = dict(bot_captured_variables)
+
+        if EvaluationParameter.EXTRACTION_VARIABLES in normalized_parameters:
+            if not extraction_schema:
+                raise ValidationError(
+                    "extraction_schema is required when using 'extraction_variables'."
+                )
+            if not bot_captured_variables:
+                raise ValidationError(
+                    "bot_captured_variables is required when using 'extraction_variables'."
+                )
+            missing_keys = [
+                key for key in extraction_schema.keys() if key not in bot_captured_variables
+            ]
+            if missing_keys:
+                raise ValidationError(
+                    "bot_captured_variables is missing keys from extraction_schema: "
+                    + ", ".join(missing_keys)
+                )
+
+        audio_path = Path(audio_file_path)
+        if not audio_path.exists():
+            raise ValidationError(f"Audio file not found: {audio_file_path}")
+        if not audio_path.is_file():
+            raise ValidationError(f"Audio path is not a file: {audio_file_path}")
+
+        request_timeout = timeout_seconds or self.timeout_seconds
+        url = self.base_url
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        mime_type = self._guess_mime_type(audio_path)
+
+        with audio_path.open("rb") as audio_file:
+            files = {
+                "audio_file": (audio_path.name, audio_file, mime_type),
+                "metadata": (None, json.dumps(payload), "application/json"),
+            }
+            response = self._session.post(
+                url, headers=headers, files=files, timeout=request_timeout
+            )
+
+        self._raise_for_api_error(response)
+        return self._safe_json(response)
+
+    @staticmethod
+    def _normalize_parameters(parameters: Iterable[ParameterInput]) -> Sequence[EvaluationParameter]:
+        normalized = [coerce_parameter(param) for param in parameters]
+        if not normalized:
+            raise ValidationError("At least one evaluation parameter is required.")
+        return normalized
+
+    @staticmethod
+    def _guess_mime_type(audio_path: Path) -> str:
+        guessed, _ = mimetypes.guess_type(str(audio_path))
+        return guessed or "application/octet-stream"
+
+    @staticmethod
+    def _safe_json(response: requests.Response) -> Dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise APIError(response.status_code, "Backend returned non-JSON response.") from exc
+        if not isinstance(payload, dict):
+            raise APIError(response.status_code, "Backend response must be a JSON object.")
+        return payload
+
+    @staticmethod
+    def _raise_for_api_error(response: requests.Response) -> None:
+        if response.ok:
+            return
+
+        try:
+            payload = response.json()
+            message = payload.get("error") or payload.get("message") or str(payload)
+        except ValueError:
+            message = response.text or "Unknown backend error"
+
+        raise APIError(response.status_code, message)

prodloop/exceptions.py

@@ -0,0 +1,15 @@
+class ProdloopError(Exception):
+    """Base exception for SDK errors."""
+
+
+class ValidationError(ProdloopError):
+    """Raised when request inputs are invalid."""
+
+
+class APIError(ProdloopError):
+    """Raised when backend API returns an error response."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(f"Prodloop API error ({status_code}): {message}")
+        self.status_code = status_code
+        self.message = message

prodloop/models.py

@@ -0,0 +1,29 @@
+from enum import Enum
+from typing import Union
+
+
+class EvaluationParameter(str, Enum):
+    E2E_RESPONSE_TIME = "e2e_response_time"
+    TURN_BY_TURN_LATENCY = "turn_by_turn_latency"
+    HALLUCINATION = "hallucination"
+    EXTRACTION_VARIABLES = "extraction_variables"
+    INTERRUPTION_BEHAVIOR = "interruption_behavior"
+
+
+ParameterInput = Union[EvaluationParameter, str]
+
+SUPPORTED_PARAMETERS = tuple(param.value for param in EvaluationParameter)
+
+
+def coerce_parameter(value: ParameterInput) -> EvaluationParameter:
+    if isinstance(value, EvaluationParameter):
+        return value
+
+    normalized = str(value).strip().lower()
+    for parameter in EvaluationParameter:
+        if parameter.value == normalized:
+            return parameter
+
+    raise ValueError(
+        f"Unsupported parameter '{value}'. Supported values: {', '.join(SUPPORTED_PARAMETERS)}."
+    )

prodloop_observability_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: prodloop-observability-sdk
+Version: 0.1.0
+Summary: Python SDK for evaluating AI voice bot calls via Prodloop APIs.
+Project-URL: Homepage, https://prodloop.com
+Project-URL: Documentation, https://prodloop.com/docs
+Project-URL: Repository, https://github.com/prodloop/prodloop-observability-sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "docs"
+
+# Prodloop Observability SDK
+
+Python SDK to evaluate AI voice bot calls through the Prodloop evaluation service.
+
+## Install
+
+```bash
+pip install prodloop-observability-sdk
+```
+
+## Quickstart
+
+```python
+from prodloop import ProdloopClient, EvaluationParameter
+
+client = ProdloopClient(api_key="sk_live_...")
+
+result = client.evaluate_call(
+    audio_file_path="call.mp3",
+    parameters=[
+        EvaluationParameter.E2E_RESPONSE_TIME,
+        EvaluationParameter.HALLUCINATION,
+    ],
+    thresholds={"e2e_response_time_max_ms": 800},
+)
+
+print(result)
+```
+
+## Extraction Validation
+
+To validate extraction quality, pass both `extraction_schema` and `bot_captured_variables`:
+
+```python
+result = client.evaluate_call(
+    audio_file_path="call.mp3",
+    parameters=[EvaluationParameter.EXTRACTION_VARIABLES],
+    extraction_schema={"customer_name": "string"},
+    bot_captured_variables={"customer_name": "ram"},
+)
+```
+
+Response includes:
+
+- `extraction_variables`
+- `extraction_validation`
+
+## Supported Parameters
+
+- `e2e_response_time`
+- `turn_by_turn_latency`
+- `hallucination`
+- `extraction_variables`
+- `interruption_behavior`
+
+## Authentication
+
+Pass your Prodloop API key in the SDK constructor.  
+The SDK sends it as a `Bearer` token in the `Authorization` header.
+
+## Errors
+
+- `ValidationError`: invalid local inputs (file path, parameters, etc.)
+- `APIError`: backend/API-level failures (`status_code`, `message`)
+
+## Local Demo
+
+Use the included demo script:
+
+```bash
+export PRODLOOP_API_KEY="sk_live_..."
+python demo/use_sdk.py --audio-file "/absolute/path/to/call.mp3"
+```
+
+## Documentation Site
+
+This repo includes MkDocs docs under `docs/`.
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```

prodloop_observability_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+prodloop/__init__.py,sha256=YjKexKVjh20ShSwrinFpv4x0zzlRvFQ-PrYgx-NVLac,299
+prodloop/client.py,sha256=Vex9ftFmv1rEyGe6t-hN1nXqA7PTmRI84hLsAYZNYwA,4897
+prodloop/exceptions.py,sha256=N77tevCDy8gHUGZEmw1IImHyd1LHYn_wWNRatMHxiuI,474
+prodloop/models.py,sha256=Oes9YKRyAq9WtRHpG48oY8TGmLoQ4eZ9vqiEYviz0Co,897
+prodloop_observability_sdk-0.1.0.dist-info/METADATA,sha256=T7LVcXqbnzddEwVzxiW3faWbyadOIK_IhK85h1eZBCU,2309
+prodloop_observability_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+prodloop_observability_sdk-0.1.0.dist-info/top_level.txt,sha256=dDhEPtIqQuBgiiVeNB458bBuVZk_N3Uj6tzVGEiaPIA,9
+prodloop_observability_sdk-0.1.0.dist-info/RECORD,,

prodloop_observability_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

prodloop_observability_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+prodloop