trodo-python 2.16.0__tar.gz → 2.18.0__tar.gz

{trodo_python-2.16.0 → trodo_python-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.16.0
+Version: 2.18.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -123,7 +123,7 @@ Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinct_
 
 ```python
 user = trodo.identify('user@example.com', session_id=request.cookies.get('trodo_session'))
-# distinct_id is now id_user@example.com — merges with browser events
+# distinct_id is now user@example.com — merges with browser events
 user.track('login')
 ```
 
@@ -171,6 +171,59 @@ trodo.people_set('user-123', {'plan': 'pro'})
 trodo.set_group('user-123', 'company', 'acme')
 ```
 
+### `upsert_user` — identity and traits in one call
+
+Create-or-update a user and their traits idempotently. This is the call a
+stateless request handler makes; safe to run on every request.
+
+```python
+result = trodo.upsert_user(
+    'user-42',
+    properties={'plan': 'pro', 'company': 'Acme'},        # merged
+    set_once={'signup_date': '2026-01-04'},               # fill-if-absent
+    fixed_properties={'last_location_country': 'India'},
+)
+
+result['created']                  # True if this call created the user
+result['applied']['properties']    # ['plan', 'company']
+result['skipped']['fixedProperties']
+```
+
+All three bags are optional. With none of them it still ensures the user
+exists — what you want at signup, before they've produced any runs.
+
+**Fixed vs custom properties.** `properties` / `set_once` are free-form and live
+on the profile as custom properties. `fixed_properties` writes the real columns
+the dashboard filters on, and only a backend-knowable subset is accepted:
+
+| Settable from a backend | Browser-only |
+|---|---|
+| `first_location_country`, `last_location_country` | `device_type`, `browser_name`, `os` |
+| `first_location_city`, `last_location_city` | `first_referrer`, `last_referrer`, `utm_*` |
+
+A browser-only key isn't an error — it comes back in `skipped` with
+`reason: 'BROWSER_ONLY_PROPERTY'` and the rest of the batch still applies. The
+reasoning: a backend supplying a browser name is guessing, and a wrong guess
+silently corrupts attribution reporting.
+
+Where both a browser and a backend write the same column, **the browser wins** —
+it observed the value, the server supplied one — and the server write is
+reported as `BROWSER_OWNED_PROPERTY`.
+
+### Attributing and enriching in one call
+
+`wrap_agent` and `start_run` take an optional `user=` bag, so a request handler
+doesn't need a separate `upsert_user` call it has to sequence correctly:
+
+```python
+with trodo.wrap_agent('support-agent', distinct_id=user_id,
+                      user={'properties': {'plan': 'pro'}}) as run:
+    ...
+```
+
+Applied server-side and non-fatally — a failed trait write never costs you the
+trace. Use `upsert_user` directly when you need to know what landed.
+
 ---
 
 ## AI Agent Tracing (recommended)
@@ -617,10 +670,10 @@ Call `identify()` with the **same value** on the browser and server to merge all
 
 ```python
 # Python
-user.identify('user@example.com')   # → id_user@example.com
+user.identify('user@example.com')   # → user@example.com
 
 # Browser (same value)
-# Trodo.identify('user@example.com') → id_user@example.com
+# Trodo.identify('user@example.com') → user@example.com
 # Events from both sides now appear together in the dashboard
 ```
 

{trodo_python-2.16.0 → trodo_python-2.18.0}/README.md

@@ -92,7 +92,7 @@ Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinct_
 
 ```python
 user = trodo.identify('user@example.com', session_id=request.cookies.get('trodo_session'))
-# distinct_id is now id_user@example.com — merges with browser events
+# distinct_id is now user@example.com — merges with browser events
 user.track('login')
 ```
 
@@ -140,6 +140,59 @@ trodo.people_set('user-123', {'plan': 'pro'})
 trodo.set_group('user-123', 'company', 'acme')
 ```
 
+### `upsert_user` — identity and traits in one call
+
+Create-or-update a user and their traits idempotently. This is the call a
+stateless request handler makes; safe to run on every request.
+
+```python
+result = trodo.upsert_user(
+    'user-42',
+    properties={'plan': 'pro', 'company': 'Acme'},        # merged
+    set_once={'signup_date': '2026-01-04'},               # fill-if-absent
+    fixed_properties={'last_location_country': 'India'},
+)
+
+result['created']                  # True if this call created the user
+result['applied']['properties']    # ['plan', 'company']
+result['skipped']['fixedProperties']
+```
+
+All three bags are optional. With none of them it still ensures the user
+exists — what you want at signup, before they've produced any runs.
+
+**Fixed vs custom properties.** `properties` / `set_once` are free-form and live
+on the profile as custom properties. `fixed_properties` writes the real columns
+the dashboard filters on, and only a backend-knowable subset is accepted:
+
+| Settable from a backend | Browser-only |
+|---|---|
+| `first_location_country`, `last_location_country` | `device_type`, `browser_name`, `os` |
+| `first_location_city`, `last_location_city` | `first_referrer`, `last_referrer`, `utm_*` |
+
+A browser-only key isn't an error — it comes back in `skipped` with
+`reason: 'BROWSER_ONLY_PROPERTY'` and the rest of the batch still applies. The
+reasoning: a backend supplying a browser name is guessing, and a wrong guess
+silently corrupts attribution reporting.
+
+Where both a browser and a backend write the same column, **the browser wins** —
+it observed the value, the server supplied one — and the server write is
+reported as `BROWSER_OWNED_PROPERTY`.
+
+### Attributing and enriching in one call
+
+`wrap_agent` and `start_run` take an optional `user=` bag, so a request handler
+doesn't need a separate `upsert_user` call it has to sequence correctly:
+
+```python
+with trodo.wrap_agent('support-agent', distinct_id=user_id,
+                      user={'properties': {'plan': 'pro'}}) as run:
+    ...
+```
+
+Applied server-side and non-fatally — a failed trait write never costs you the
+trace. Use `upsert_user` directly when you need to know what landed.
+
 ---
 
 ## AI Agent Tracing (recommended)
@@ -586,10 +639,10 @@ Call `identify()` with the **same value** on the browser and server to merge all
 
 ```python
 # Python
-user.identify('user@example.com')   # → id_user@example.com
+user.identify('user@example.com')   # → user@example.com
 
 # Browser (same value)
-# Trodo.identify('user@example.com') → id_user@example.com
+# Trodo.identify('user@example.com') → user@example.com
 # Events from both sides now appear together in the dashboard
 ```
 

{trodo_python-2.16.0 → trodo_python-2.18.0}/pyproject.toml

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

{trodo_python-2.16.0 → trodo_python-2.18.0}/tests/test_experiments.py

@@ -118,3 +118,59 @@ def test_ingest_requires_item_position_and_output():
         ExperimentManager(FakeHttp()).ingest("ds", [{"output": "o"}])
     with pytest.raises(ValueError, match="requires an 'output'"):
         ExperimentManager(FakeHttp()).ingest("ds", [{"item_position": 0}])
+
+
+class FakeManagedHttp(FakeHttp):
+    def __init__(self):
+        super().__init__()
+        self.create_body = None
+        self.run_body = None
+        self.compare_args = None
+
+    def create_experiment(self, body):
+        self.create_body = body
+        return {"experiment": {"id": "exp_p", "status": "pending"}}
+
+    def run_experiment(self, body):
+        self.run_body = body
+        return {"experiment": {"id": "exp_done", "status": "completed"}}
+
+    def get_experiment(self, experiment_id):
+        return {"experiment": {"id": experiment_id, "status": "completed"}}
+
+    def compare_experiments(self, a_id, b_id, strict=False):
+        self.compare_args = (a_id, b_id, strict)
+        return {"a": {"id": a_id}, "b": {"id": b_id}, "join": "dataset_item_id"}
+
+
+def test_create_posts_managed_body():
+    http = FakeManagedHttp()
+    exp = ExperimentManager(http).create(
+        dataset="golden",
+        models=[{"credential_id": "1", "provider": "openai", "model": "gpt-4o"}],
+        prompt_ref={"name": "support", "version": "abc"},
+        scorer_ids=[1, 2],
+    )
+    assert http.create_body["dataset_id"] == "golden"
+    assert http.create_body["scorer_ids"] == [1, 2]
+    assert exp["status"] == "pending"
+
+
+def test_run_posts_and_returns_completed():
+    http = FakeManagedHttp()
+    exp = ExperimentManager(http).run(
+        dataset="golden",
+        models=[{"credential_id": "1", "provider": "openai", "model": "gpt-4o"}],
+        name="ci",
+    )
+    assert http.run_body["name"] == "ci"
+    assert exp["status"] == "completed"
+
+
+def test_get_and_compare():
+    http = FakeManagedHttp()
+    mgr = ExperimentManager(http)
+    assert mgr.get("exp_1")["id"] == "exp_1"
+    res = mgr.compare("a", "b", strict=True)
+    assert http.compare_args == ("a", "b", True)
+    assert res["join"] == "dataset_item_id"

trodo_python-2.18.0/tests/test_user_traits.py

@@ -0,0 +1,278 @@
+"""User traits — ``upsert_user``, the ``user`` bag on runs, and bounded caches.
+
+The stateless-backend story: a request handler knows who the user is and a few
+things about them for one request, and holds nothing between requests. These
+cover the ways that gets expressed, plus the memory ceiling that makes holding
+per-user state safe in a long-lived process.
+
+Mirrors ``sdks/trodo-node-sdk/tests/userTraits.test.ts``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from trodo.managers.user_manager import UserManager
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import start_run
+from trodo.otel.wrap_agent import wrap_agent as wrap_agent_ctx
+from trodo.util.lru import LruDict
+
+
+class UpsertRecorder:
+    """Stands in for HttpClient, recording exact wire payloads."""
+
+    def __init__(self) -> None:
+        self.calls = []
+
+    def post_user_upsert(self, payload):
+        self.calls.append(payload)
+        return {"success": True, "distinctId": payload["distinctId"], "created": False}
+
+
+class RunRecorder:
+    """Stands in for the processor's HTTP client."""
+
+    def __init__(self) -> None:
+        self.ingested = []
+        self.started = []
+
+    def post_run_ingest(self, payload):
+        self.ingested.append(payload)
+        return {"success": True}
+
+    def post_run_start(self, payload):
+        self.started.append(payload)
+        return {"success": True}
+
+    def post_run_end(self, run_id, payload):
+        return {"success": True}
+
+    def post_spans_append(self, run_id, spans):
+        return {"success": True}
+
+    def post_runless_spans(self, spans):
+        return {"success": True}
+
+
+# ---------------------------------------------------------------------------
+# upsert_user
+# ---------------------------------------------------------------------------
+
+
+def test_upsert_sends_every_bag():
+    http = UpsertRecorder()
+    users = UserManager(http)
+
+    users.upsert(
+        "user-42",
+        properties={"plan": "pro"},
+        set_once={"signup_date": "2026-01-04"},
+        fixed_properties={"last_location_country": "India"},
+    )
+
+    assert http.calls[0] == {
+        "distinctId": "user-42",
+        "properties": {"plan": "pro"},
+        "setOnce": {"signup_date": "2026-01-04"},
+        "fixedProperties": {"last_location_country": "India"},
+    }
+
+
+def test_upsert_omits_bags_not_supplied():
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-42", properties={"plan": "pro"})
+
+    # The server tells "no bag" from "empty bag" by presence.
+    assert sorted(http.calls[0].keys()) == ["distinctId", "properties"]
+
+
+def test_upsert_with_no_traits_still_ensures_the_user():
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-new")
+
+    assert http.calls == [{"distinctId": "user-new"}]
+
+
+def test_upsert_uses_camel_case_on_the_wire():
+    """Python callers write snake_case; the wire contract is camelCase."""
+    http = UpsertRecorder()
+    UserManager(http).upsert("user-42", set_once={"a": 1}, fixed_properties={"b": 2})
+
+    assert "setOnce" in http.calls[0]
+    assert "fixedProperties" in http.calls[0]
+    assert "set_once" not in http.calls[0]
+
+
+# ---------------------------------------------------------------------------
+# The `user` bag on runs
+# ---------------------------------------------------------------------------
+
+
+def test_user_bag_rides_on_the_run_payload():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {"plan": "pro"}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    payload = http.ingested[0]
+    assert payload["run"]["user"] == {"properties": {"plan": "pro"}}
+
+
+def test_user_bag_accepts_snake_case_from_python_callers():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"fixed_properties": {"last_location_country": "India"}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    # Normalised to the camelCase wire key.
+    assert http.ingested[0]["run"]["user"] == {
+        "fixedProperties": {"last_location_country": "India"}
+    }
+
+
+def test_user_bag_absent_when_not_passed():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    assert http.ingested[0]["run"].get("user") is None
+
+
+def test_empty_bag_is_dropped_rather_than_sent():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with wrap_agent_ctx(
+        processor=processor,
+        team_site_id="site_abc",
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {}},
+    ) as run:
+        run.set_output("done")
+
+    processor.force_flush()
+    assert http.ingested[0]["run"].get("user") is None
+
+
+def test_user_bag_travels_when_the_run_fails():
+    """A run that threw is exactly when you still want to know who the user was."""
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    with pytest.raises(ValueError):
+        with wrap_agent_ctx(
+            processor=processor,
+            team_site_id="site_abc",
+            agent_name="support",
+            distinct_id="user-42",
+            user={"properties": {"plan": "pro"}},
+        ):
+            raise ValueError("boom")
+
+    processor.force_flush()
+    run = http.ingested[0]["run"]
+    assert run["status"] == "error"
+    assert run["user"] == {"properties": {"plan": "pro"}}
+
+
+def test_start_run_carries_the_user_bag():
+    http = RunRecorder()
+    processor = TrodoSpanProcessor(http_client=http)
+
+    start_run(
+        processor=processor,
+        agent_name="support",
+        distinct_id="user-42",
+        user={"properties": {"plan": "pro"}},
+    )
+
+    payload = http.started[0]
+    run = payload.get("run", payload)
+    assert run["user"] == {"properties": {"plan": "pro"}}
+
+
+# ---------------------------------------------------------------------------
+# LruDict — the memory ceiling behind for_user()
+# ---------------------------------------------------------------------------
+
+
+def test_lru_holds_entries_below_the_cap():
+    d = LruDict(3)
+    d.set("a", 1)
+    d.set("b", 2)
+    d.set("c", 3)
+    assert len(d) == 3
+    assert d.get("a") == 1
+
+
+def test_lru_evicts_least_recently_used():
+    d = LruDict(3)
+    for k, v in [("a", 1), ("b", 2), ("c", 3)]:
+        d.set(k, v)
+    d.set("d", 4)
+
+    assert len(d) == 3
+    assert d.get("a") is None
+    assert d.get("d") == 4
+
+
+def test_lru_read_counts_as_use():
+    d = LruDict(3)
+    for k, v in [("a", 1), ("b", 2), ("c", 3)]:
+        d.set(k, v)
+    d.get("a")          # 'a' is newest now, 'b' is oldest
+    d.set("d", 4)
+
+    assert d.get("a") == 1
+    assert d.get("b") is None
+
+
+def test_lru_reset_refreshes_rather_than_duplicating():
+    d = LruDict(2)
+    d.set("a", 1)
+    d.set("b", 2)
+    d.set("a", 99)
+    d.set("c", 3)
+
+    assert d.get("a") == 99
+    assert d.get("b") is None
+    assert len(d) == 2
+
+
+def test_lru_footprint_stays_bounded_across_many_users():
+    d = LruDict(100)
+    for i in range(20_000):
+        d.set(f"user-{i}", i)
+    assert len(d) == 100
+
+
+def test_lru_falls_back_to_default_on_nonsense_cap():
+    d = LruDict(0)
+    d.set("a", 1)
+    assert d.get("a") == 1

{trodo_python-2.16.0 → trodo_python-2.18.0}/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.16.0"
+__version__ = "2.18.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -80,6 +80,7 @@ __all__ = [
     "for_user",
     "track",
     "identify",
+    "upsert_user",
     "people_set",
     "people_set_once",
     "wallet_address",
@@ -119,9 +120,14 @@ __all__ = [
     "TemplateError",
     "ManagedPrompt",
     "PromptSummary",
-    # Datasets & experiments ingest
+    # Datasets & experiments
     "append_dataset",
     "ingest_experiment",
+    "create_experiment",
+    "run_experiment",
+    "get_experiment",
+    "wait_experiment",
+    "compare_experiments",
 ]
 
 # ============================================================================
@@ -251,6 +257,44 @@ def identify(identify_id: str, session_id: Optional[str] = None) -> UserContext:
     return _get_client().identify(identify_id, session_id)
 
 
+def upsert_user(
+    distinct_id: str,
+    *,
+    properties: Optional[Dict[str, Any]] = None,
+    set_once: Optional[Dict[str, Any]] = None,
+    fixed_properties: Optional[Dict[str, Any]] = None,
+):
+    """Create-or-update a user and their traits in one idempotent call.
+
+    The stateless-backend primitive: a request handler knows who the user is and
+    a few things about them for the duration of one request, and this is how you
+    say so. Safe to call on every request.
+
+        trodo.upsert_user(
+            "user-42",
+            properties={"plan": "pro"},
+            set_once={"signup_date": "2026-01-04"},
+            fixed_properties={"last_location_country": "India"},
+        )
+
+    Every bag is optional — with none of them it still ensures the user exists,
+    which is useful at signup, before they have produced any agent runs.
+
+    ``fixed_properties`` writes the real profile columns the dashboard filters
+    on, limited to what a backend can honestly know (country, city). Device,
+    browser, OS, referrer and UTM are browser observations and come back in
+    ``skipped`` instead of being stored.
+
+    Mirrors ``trodo.users.upsert(...)`` in trodo-node.
+    """
+    return _get_client().upsert_user(
+        distinct_id,
+        properties=properties,
+        set_once=set_once,
+        fixed_properties=fixed_properties,
+    )
+
+
 def people_set(distinct_id: str, properties: Dict[str, Any]):
     """Set profile properties for a user — module-level convenience mirroring
     ``trodo.people.set(distinctId, props)`` in trodo-node. Equivalent to
@@ -405,6 +449,54 @@ def ingest_experiment(
     )
 
 
+def create_experiment(
+    *,
+    dataset: Optional[str] = None,
+    dataset_id: Optional[str] = None,
+    models: List[Dict[str, Any]],
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """Create an experiment (immutable refs, status pending)."""
+    return _get_client().experiments.create(
+        dataset=dataset, dataset_id=dataset_id, models=models, **kwargs
+    )
+
+
+def run_experiment(
+    *,
+    dataset: Optional[str] = None,
+    dataset_id: Optional[str] = None,
+    models: List[Dict[str, Any]],
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """Create and run an experiment synchronously."""
+    return _get_client().experiments.run(
+        dataset=dataset, dataset_id=dataset_id, models=models, **kwargs
+    )
+
+
+def get_experiment(experiment_id: str) -> Dict[str, Any]:
+    """Fetch an experiment by id."""
+    return _get_client().experiments.get(experiment_id)
+
+
+def wait_experiment(
+    experiment_id: str,
+    *,
+    interval_ms: int = 2500,
+    timeout_ms: int = 600_000,
+) -> Dict[str, Any]:
+    """Poll until the experiment completes or fails."""
+    return _get_client().experiments.wait(
+        experiment_id, interval_ms=interval_ms, timeout_ms=timeout_ms
+    )
+
+
+def compare_experiments(a_id: str, b_id: str, *, strict: bool = False) -> Dict[str, Any]:
+    """Compare two experiments side by side."""
+    return _get_client().experiments.compare(a_id, b_id, strict=strict)
+
+
 def enable_auto_events() -> None:
     _get_client().enable_auto_events()
 

{trodo_python-2.16.0 → trodo_python-2.18.0}/trodo/api/endpoints.py

@@ -4,6 +4,8 @@ EVENTS_BULK = "/api/events/bulk"
 IDENTIFY = "/api/sdk/identify"
 WALLET_ADDRESS = "/api/sdk/wallet-address"
 RESET = "/api/sdk/reset"
+# Identity + traits in one idempotent call.
+USERS_UPSERT = "/api/sdk/users/upsert"
 PEOPLE_SET = "/api/sdk/people/set"
 PEOPLE_SET_ONCE = "/api/sdk/people/set_once"
 PEOPLE_UNSET = "/api/sdk/people/unset"
@@ -23,6 +25,10 @@ RUNS_INGEST = "/api/sdk/runs/ingest"
 RUNS_START = "/api/sdk/runs/start"
 RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
 OTLP_TRACES = "/api/sdk/otel/v1/traces"
-# Datasets & experiments ingest
+# Datasets & experiments
 DATASETS_BASE = "/api/sdk/datasets"  # /datasets/{ref}/items
+EXPERIMENTS = "/api/sdk/experiments"
 EXPERIMENTS_INGEST = "/api/sdk/experiments/ingest"
+EXPERIMENTS_CREATE = "/api/sdk/experiments/create"
+EXPERIMENTS_RUN = "/api/sdk/experiments/run"
+EXPERIMENTS_COMPARE = "/api/sdk/experiments/compare"