trodo-python 2.25.0__tar.gz → 2.26.1__tar.gz

{trodo_python-2.25.0 → trodo_python-2.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.25.0
+Version: 2.26.1
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.25.0 → trodo_python-2.26.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.25.0"
+version = "2.26.1"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

{trodo_python-2.25.0 → trodo_python-2.26.1}/tests/test_datasets.py

@@ -100,3 +100,47 @@ def test_append_requires_items():
 def test_append_requires_input_on_each_item():
     with pytest.raises(ValueError, match="requires an 'input'"):
         DatasetManager(FakeHttp()).append("ds", [{"expected_output": "x"}])
+
+
+# ---------------------------------------------------------------------------
+# export — DatasetManager.export (the labelled JSONL, read with an export token)
+# ---------------------------------------------------------------------------
+
+class FakeExportHttp:
+    def __init__(self, response):
+        self._response = response
+        self.last = None
+
+    def export_dataset(self, ref, params, token):
+        self.last = (ref, params, token)
+        return self._response
+
+
+def test_export_sends_token_and_filters_and_parses_jsonl():
+    http = FakeExportHttp({"text": '{"id":"a","expected":"x"}\n{"id":"b","expected":null}\n', "status": 200, "rows": 2, "version": 3})
+    out = DatasetManager(http).export("support-eval", "trodo_dx_abc", labels="confirmed", include_unlabelled=True, version=3, since="2026-01-01T00:00:00Z")
+    assert http.last == ("support-eval", {"labels": "confirmed", "include_unlabelled": 1, "version": 3, "since": "2026-01-01T00:00:00Z"}, "trodo_dx_abc")
+    assert out == {"rows": [{"id": "a", "expected": "x"}, {"id": "b", "expected": None}], "version": 3}
+
+
+def test_export_requires_a_token_and_raises_on_http_errors():
+    with pytest.raises(ValueError):
+        DatasetManager(FakeExportHttp({})).export("ds", "")
+    with pytest.raises(RuntimeError, match="HTTP 404"):
+        DatasetManager(FakeExportHttp({"__error": True, "status": 404, "error": "not_found"})).export("ds", "trodo_dx_abc")
+
+
+def test_append_accepts_unit_references_without_input():
+    http = FakeHttp()
+    DatasetManager(http).append("ds", [
+        {"span_id": "s1", "tags": ["hard"]},
+        {"run_id": "r1"},
+        {"conversation_id": "c1", "metadata": {"k": 1}},
+        {"eval_run_id": "v1"},
+    ])
+    assert http.last_body["items"] == [
+        {"span_id": "s1", "tags": ["hard"]},
+        {"run_id": "r1"},
+        {"conversation_id": "c1", "metadata": {"k": 1}},
+        {"eval_run_id": "v1"},
+    ]

{trodo_python-2.25.0 → trodo_python-2.26.1}/trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.25.0"
+__version__ = "2.26.1"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -122,6 +122,7 @@ __all__ = [
     "PromptSummary",
     # Datasets & experiments
     "append_dataset",
+    "export_dataset",
     "ingest_experiment",
     "create_experiment",
     "run_experiment",
@@ -435,6 +436,30 @@ def append_dataset(
     return _get_client().datasets.append(ref, items, create=create)
 
 
+def export_dataset(
+    ref: str,
+    token: str,
+    labels: str = "all",
+    include_unlabelled: bool = False,
+    version: Optional[int] = None,
+    since: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Read a dataset's labelled export with an export token (Settings → Datasets).
+
+    Rows carry ``input``, ``output``, ``expected``, ``evaluations``,
+    ``label_source`` / ``label_status`` / ``label_weight`` and ``source``::
+
+        out = trodo.export_dataset("support-failures", token=os.environ["TRODO_EXPORT_TOKEN"], labels="confirmed")
+        for row in out["rows"]:
+            ...
+
+    Returns ``{"rows": [...], "version": int | None}``.
+    """
+    return _get_client().datasets.export(
+        ref, token, labels=labels, include_unlabelled=include_unlabelled, version=version, since=since,
+    )
+
+
 def ingest_experiment(
     dataset: str,
     outputs: List[Dict[str, Any]],

trodo_python-2.26.1/trodo/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "2.26.0"

{trodo_python-2.25.0 → trodo_python-2.26.1}/trodo/api/http_client.py

@@ -180,6 +180,45 @@ class HttpClient:
             f"/api/sdk/datasets/{quote(str(ref), safe='')}/items", body
         )
 
+    def export_dataset(self, ref: str, params: Dict[str, Any], token: str) -> Dict[str, Any]:
+        """Read a dataset's labelled export (GET /datasets/:ref/export) as JSONL
+        text, authenticated with an EXPORT TOKEN (``trodo_dx_…``), never the
+        site id. Returns ``{"text", "status", "rows", "version"}`` or
+        ``{"__error": True, "status", ...}``. No retries on 4xx."""
+        from urllib.parse import quote
+        url = f"{self.api_base}/api/sdk/datasets/{quote(str(ref), safe='')}/export"
+        clean = {k: v for k, v in (params or {}).items() if v is not None and v != ""}
+        self._log(f"GET {url}")
+        try:
+            resp = requests.get(
+                url,
+                params=clean,
+                headers={"Authorization": f"Bearer {token}", "User-Agent": f"trodo-python/{SDK_VERSION}"},
+                timeout=max(self.timeout, 60),
+            )
+        except Exception as exc:  # network
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {"__error": True, "message": str(exc)}
+        if resp.status_code >= 400:
+            base: Dict[str, Any] = {"__error": True, "status": resp.status_code}
+            try:
+                data = resp.json()
+                if isinstance(data, dict):
+                    base.update(data)
+            except Exception:
+                base["message"] = resp.text[:300]
+            return base
+        rows = resp.headers.get("x-trodo-export-rows")
+        version = resp.headers.get("x-trodo-dataset-version")
+        return {
+            "text": resp.text,
+            "status": resp.status_code,
+            "rows": int(rows) if rows and rows.isdigit() else None,
+            "version": int(version) if version and version.isdigit() else None,
+        }
+
     def ingest_experiment(self, body: Dict[str, Any]) -> ApiResult:
         return self._request("/api/sdk/experiments/ingest", body)
 

trodo_python-2.26.1/trodo/managers/dataset_manager.py

@@ -0,0 +1,134 @@
+"""Dataset ingest — append evaluation items to a Trodo dataset.
+
+Datasets are the fixed inputs an experiment runs against: each item is a set of
+variable values (``input``) plus an optional gold answer (``expected_output``)
+and free-form ``metadata``. This manager appends items to a dataset addressed by
+UUID or by name; when a name is used and no such dataset exists it is
+auto-created (``create=True``, the default), so a first append bootstraps the
+dataset without a separate create call.
+
+Mirrors ``sdks/trodo-node-sdk/src/managers/DatasetManager.ts`` in shape.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Union
+
+__all__ = ["DatasetManager"]
+
+# The optional per-item fields, in wire order. ``input`` is required on a row.
+_ITEM_OPTIONAL = ("output", "expected_output", "metadata", "source_trace_ref", "tags")
+# A reference to production instead of content: the item becomes that unit's
+# row (Input, Output and Evaluations filled by Trodo). ``eval_run_id`` names a
+# verdict: Output is what the eval said, Expected its correction.
+_UNIT_REF_KEYS = ("span_id", "run_id", "conversation_id", "eval_run_id")
+_UNIT_REF_OPTIONAL = ("tags", "metadata")
+
+
+def _clean_item(item: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(item, dict):
+        raise ValueError("trodo: each dataset item must be a dict")
+    ref = [k for k in _UNIT_REF_KEYS if item.get(k)]
+    if ref and ("input" not in item or item["input"] is None):
+        out: Dict[str, Any] = {ref[0]: str(item[ref[0]])}
+        for key in _UNIT_REF_OPTIONAL:
+            if item.get(key) is not None:
+                out[key] = item[key]
+        return out
+    if "input" not in item or item["input"] is None:
+        raise ValueError("trodo: each dataset item requires an 'input' dict, or a span_id / run_id / conversation_id / eval_run_id")
+    out = {"input": item["input"]}
+    for key in _ITEM_OPTIONAL:
+        if item.get(key) is not None:
+            out[key] = item[key]
+    return out
+
+
+class DatasetManager:
+    """Append items to the team's evaluation datasets."""
+
+    def __init__(self, http_client: Any) -> None:
+        self._http = http_client
+
+    def append(
+        self,
+        ref: str,
+        items: Union[Dict[str, Any], List[Dict[str, Any]]],
+        create: bool = True,
+    ) -> Dict[str, Any]:
+        """Append one or more items to the dataset *ref* (a UUID or a name).
+
+        *items* is a list of dicts shaped ``{"input": {<var>: value, ...},
+        "expected_output"?: str, "metadata"?: dict, "source_trace_ref"?: dict}``;
+        a single dict is accepted and wrapped into a one-item list. ``None``
+        optional fields are dropped from the wire payload.
+
+        When *ref* is a name that doesn't exist yet, ``create=True`` (default)
+        auto-creates the dataset; pass ``create=False`` to require it to exist.
+
+        Returns the parsed response dict:
+        ``{"dataset_id", "dataset_name", "appended", "item_count"}``.
+
+        :raises ValueError: if *ref* is empty, *items* is empty, or an item has
+            no ``input``.
+        """
+        if not ref:
+            raise ValueError("trodo: append_dataset(ref) requires a dataset ref")
+        if isinstance(items, dict):
+            items = [items]
+        if not items:
+            raise ValueError("trodo: append_dataset(ref, items) requires items")
+
+        body = {
+            "items": [_clean_item(i) for i in items],
+            "create": bool(create),
+        }
+        return self._http.append_dataset_items(ref, body)
+
+    def export(
+        self,
+        ref: str,
+        token: str,
+        labels: str = "all",
+        include_unlabelled: bool = False,
+        version: Optional[int] = None,
+        since: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Read the dataset *ref*'s labelled export.
+
+        Each row is the dataset's training shape: ``input``, ``output``,
+        ``expected``, ``evaluations`` (the Evals v3 verdicts snapshotted onto
+        the row), ``label_source`` / ``label_status`` / ``label_weight``,
+        ``source``. *token* is an export token from Settings → Datasets
+        (``trodo_dx_…``); the site id cannot read exports. *labels* is one of
+        ``all, confirmed, explicit, derived, implicit, proposed, unlabelled,
+        failed_only, passed_only``; *version* pins a snapshot.
+
+        Returns ``{"rows": [...], "version": int | None}``.
+
+        :raises ValueError: if *ref* or *token* is empty.
+        :raises RuntimeError: on a non-2xx response (the message carries the status and body).
+        """
+        if not ref:
+            raise ValueError("trodo: export_dataset(ref) requires a dataset ref")
+        if not token:
+            raise ValueError("trodo: export_dataset requires an export token (Settings → Datasets)")
+        params: Dict[str, Any] = {"labels": labels}
+        if include_unlabelled:
+            params["include_unlabelled"] = 1
+        if version is not None:
+            params["version"] = int(version)
+        if since:
+            params["since"] = since
+        res = self._http.export_dataset(ref, params, token)
+        if res.get("__error"):
+            raise RuntimeError(
+                f"trodo: export of {ref!r} failed: HTTP {res.get('status')} {res.get('message') or res.get('error') or ''}".strip()
+            )
+        rows: List[Dict[str, Any]] = []
+        for line in (res.get("text") or "").split("\n"):
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+        return {"rows": rows, "version": res.get("version")}

{trodo_python-2.25.0 → trodo_python-2.26.1}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.25.0
+Version: 2.26.1
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

trodo_python-2.25.0/trodo/_version.py

@@ -1 +0,0 @@
-SDK_VERSION = "2.25.0"

trodo_python-2.25.0/trodo/managers/dataset_manager.py

@@ -1,74 +0,0 @@
-"""Dataset ingest — append evaluation items to a Trodo dataset.
-
-Datasets are the fixed inputs an experiment runs against: each item is a set of
-variable values (``input``) plus an optional gold answer (``expected_output``)
-and free-form ``metadata``. This manager appends items to a dataset addressed by
-UUID or by name; when a name is used and no such dataset exists it is
-auto-created (``create=True``, the default), so a first append bootstraps the
-dataset without a separate create call.
-
-Mirrors ``sdks/trodo-node-sdk/src/managers/DatasetManager.ts`` in shape.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, List, Union
-
-__all__ = ["DatasetManager"]
-
-# The optional per-item fields, in wire order. ``input`` is always required.
-_ITEM_OPTIONAL = ("expected_output", "metadata", "source_trace_ref")
-
-
-def _clean_item(item: Dict[str, Any]) -> Dict[str, Any]:
-    if not isinstance(item, dict):
-        raise ValueError("trodo: each dataset item must be a dict")
-    if "input" not in item or item["input"] is None:
-        raise ValueError("trodo: each dataset item requires an 'input' dict")
-    out: Dict[str, Any] = {"input": item["input"]}
-    for key in _ITEM_OPTIONAL:
-        if item.get(key) is not None:
-            out[key] = item[key]
-    return out
-
-
-class DatasetManager:
-    """Append items to the team's evaluation datasets."""
-
-    def __init__(self, http_client: Any) -> None:
-        self._http = http_client
-
-    def append(
-        self,
-        ref: str,
-        items: Union[Dict[str, Any], List[Dict[str, Any]]],
-        create: bool = True,
-    ) -> Dict[str, Any]:
-        """Append one or more items to the dataset *ref* (a UUID or a name).
-
-        *items* is a list of dicts shaped ``{"input": {<var>: value, ...},
-        "expected_output"?: str, "metadata"?: dict, "source_trace_ref"?: dict}``;
-        a single dict is accepted and wrapped into a one-item list. ``None``
-        optional fields are dropped from the wire payload.
-
-        When *ref* is a name that doesn't exist yet, ``create=True`` (default)
-        auto-creates the dataset; pass ``create=False`` to require it to exist.
-
-        Returns the parsed response dict:
-        ``{"dataset_id", "dataset_name", "appended", "item_count"}``.
-
-        :raises ValueError: if *ref* is empty, *items* is empty, or an item has
-            no ``input``.
-        """
-        if not ref:
-            raise ValueError("trodo: append_dataset(ref) requires a dataset ref")
-        if isinstance(items, dict):
-            items = [items]
-        if not items:
-            raise ValueError("trodo: append_dataset(ref, items) requires items")
-
-        body = {
-            "items": [_clean_item(i) for i in items],
-            "create": bool(create),
-        }
-        return self._http.append_dataset_items(ref, body)