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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.17.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.17.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.17.0 → trodo_python-2.18.0}/pyproject.toml

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

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.17.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",
@@ -256,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

{trodo_python-2.17.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"

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/api/http_client.py

@@ -9,6 +9,7 @@ from typing import Any, Callable, Dict, Optional
 import requests
 
 from ..types import ApiResult, EventPayload
+from . import endpoints
 
 
 class HttpClient:
@@ -183,6 +184,17 @@ class HttpClient:
     def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
         return self._request("/api/sdk/reset", payload)
 
+    def post_user_upsert(self, payload: Dict[str, Any]) -> ApiResult:
+        """Create-or-update a user and their traits.
+
+        Degrades gracefully against a backend that predates the endpoint:
+        ``_request`` never raises, so a 404 surfaces through ``on_error`` and
+        returns an empty result rather than breaking the caller's request
+        handler. Users on an older backend lose the trait write, not their
+        application.
+        """
+        return self._request(endpoints.USERS_UPSERT, payload)
+
     def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
         return self._request(path, payload)
 

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/client.py

@@ -7,6 +7,7 @@ from typing import Any, Callable, Dict, List, Optional, Union
 
 from .api.http_client import HttpClient
 from .session.session_manager import SessionManager
+from .util.lru import LruDict
 from .managers.group_manager import GroupProfile
 from .queue.event_queue import EventQueue
 from .queue.batch_flusher import BatchFlusher
@@ -59,6 +60,7 @@ class TrodoClient:
         auto_instrument: bool = True,
         disable_instrumentations: Optional[List[str]] = None,
         otel_mode: str = "trodo",
+        max_cached_users: int = 10_000,
     ) -> None:
         if not site_id:
             raise ValueError("trodo-python: site_id is required")
@@ -75,10 +77,11 @@ class TrodoClient:
             debug=debug,
         )
 
-        self._session_manager = SessionManager()
+        self._session_manager = SessionManager(max_cached_users)
         self._prompts = None  # lazily-built PromptManager
         self._datasets = None  # lazily-built DatasetManager
         self._experiments = None  # lazily-built ExperimentManager
+        self._users = None  # lazily-built UserManager
 
         if batch_enabled:
             self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
@@ -97,7 +100,10 @@ class TrodoClient:
         if auto_events:
             self._auto_event_manager.enable()
 
-        self._user_context_cache: Dict[str, UserContext] = {}
+        # LRU-bounded (max_cached_users, default 10k). ``for_user`` caches a
+        # context per distinct id; unbounded that is a slow leak in a long-lived
+        # API server. An evicted user is simply rebuilt on next use.
+        self._user_context_cache: LruDict[str, UserContext] = LruDict(max_cached_users)
 
         self._span_processor = TrodoSpanProcessor(http_client=self._http)
         if auto_instrument:
@@ -143,6 +149,15 @@ class TrodoClient:
             self._experiments = ExperimentManager(self._http)
         return self._experiments
 
+    @property
+    def users(self):
+        """Create-or-update a user and their traits — the stateless-backend
+        primitive. See :class:`~trodo.managers.user_manager.UserManager`."""
+        if self._users is None:
+            from .managers.user_manager import UserManager
+            self._users = UserManager(self._http)
+        return self._users
+
     # --------------------------------------------------------------------------
     # Primary pattern: for_user()
     # --------------------------------------------------------------------------
@@ -152,8 +167,9 @@ class TrodoClient:
         distinct_id: str,
         session_id: Optional[str] = None,
     ) -> UserContext:
-        if distinct_id in self._user_context_cache:
-            return self._user_context_cache[distinct_id]
+        cached = self._user_context_cache.get(distinct_id)
+        if cached is not None:
+            return cached
 
         ctx = UserContext(
             distinct_id=distinct_id,
@@ -165,7 +181,7 @@ class TrodoClient:
             auto_event_manager=self._auto_event_manager,
             session_id=session_id,
         )
-        self._user_context_cache[distinct_id] = ctx
+        self._user_context_cache.set(distinct_id, ctx)
         return ctx
 
     # --------------------------------------------------------------------------
@@ -182,8 +198,9 @@ class TrodoClient:
         self.for_user(distinct_id).track(event_name, properties, category)
 
     def identify(self, identify_id: str, session_id: Optional[str] = None) -> "UserContext":
-        if identify_id in self._user_context_cache:
-            return self._user_context_cache[identify_id]
+        cached = self._user_context_cache.get(identify_id)
+        if cached is not None:
+            return cached
         ctx = self.for_user(identify_id, session_id)
         ctx.identify(identify_id)
         return ctx
@@ -195,6 +212,26 @@ class TrodoClient:
         self._user_context_cache.pop(distinct_id, None)
         return self.for_user(distinct_id).reset()
 
+    def upsert_user(
+        self,
+        distinct_id: str,
+        *,
+        properties: Optional[Dict[str, Any]] = None,
+        set_once: Optional[Dict[str, Any]] = None,
+        fixed_properties: Optional[Dict[str, Any]] = None,
+    ) -> ApiResult:
+        """Create-or-update a user and their traits in one idempotent call.
+
+        Flat alias for ``client.users.upsert(...)``, matching the ``people_set``
+        convention.
+        """
+        return self.users.upsert(
+            distinct_id,
+            properties=properties,
+            set_once=set_once,
+            fixed_properties=fixed_properties,
+        )
+
     # People (direct)
     def people_set(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
         return self.for_user(distinct_id).people.set(properties)
@@ -289,11 +326,19 @@ class TrodoClient:
         conversation_id: Optional[str] = None,
         parent_run_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
+        user: Optional[Dict[str, Any]] = None,
     ) -> wrap_agent_ctx:
         """Context manager that captures the wrapped block as an agent run.
 
         Every OTel-instrumented call (Anthropic, OpenAI, LangChain…) made
         inside the ``with`` is auto-captured as a nested span.
+
+        ``user`` optionally carries profile traits — ``{"properties": ...,
+        "set_once": ..., "fixed_properties": ...}`` — so a stateless request
+        handler can attribute the run AND enrich the profile in one round trip
+        instead of a separate ``upsert_user`` call it has to sequence
+        correctly. Applied server-side and non-fatally: a failed trait write
+        never costs you the trace. Use ``upsert_user`` when you need the result.
         """
         return wrap_agent_ctx(
             processor=self._span_processor,
@@ -303,6 +348,7 @@ class TrodoClient:
             conversation_id=conversation_id,
             parent_run_id=parent_run_id,
             metadata=metadata,
+            user=user,
         )
 
     def agent(
@@ -352,10 +398,13 @@ class TrodoClient:
         parent_run_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         input: Any = None,
+        user: Optional[Dict[str, Any]] = None,
     ) -> str:
         """Open a Run record outside a context manager. Returns the run_id.
 
         Use ``end_run`` to finalise, ``join_run`` from any process to add spans.
+
+        ``user`` carries profile traits alongside the run — see ``wrap_agent``.
         """
         return start_run_fn(
             processor=self._span_processor,
@@ -366,6 +415,7 @@ class TrodoClient:
             parent_run_id=parent_run_id,
             metadata=metadata,
             input=input,
+            user=user,
         )
 
     def end_run(

trodo_python-2.18.0/trodo/managers/user_manager.py

@@ -0,0 +1,70 @@
+"""User upsert — create-or-update a user and their traits in one call.
+
+Backend services are stateless: a request handler knows who the user is and a
+few things about them for the duration of one request, and holds nothing between
+requests. This is the call that expresses that.
+
+    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 —
+useful at signup, before they have produced any agent runs. Safe to call on
+every request: it is idempotent, and ``set_once`` keys are only written the
+first time.
+
+Mirrors ``sdks/trodo-node-sdk/src/managers/UserManager.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ..types import ApiResult
+
+__all__ = ["UserManager"]
+
+
+class UserManager:
+    def __init__(self, http_client: object) -> None:
+        self._http = http_client
+
+    def upsert(
+        self,
+        distinct_id: str,
+        *,
+        properties: Optional[Dict[str, Any]] = None,
+        set_once: Optional[Dict[str, Any]] = None,
+        fixed_properties: Optional[Dict[str, Any]] = None,
+    ) -> ApiResult:
+        """Create or update ``distinct_id`` and apply the supplied traits.
+
+        :param distinct_id: The user's id — the same value passed as
+            ``distinct_id`` to ``wrap_agent``, and the same one the browser SDK
+            calls ``identify()`` with. Matching them is what merges a user's
+            agent runs and product events into one profile.
+        :param properties: Merged into the user's custom properties.
+        :param set_once: Written only where the key is absent.
+        :param fixed_properties: Allowlisted real columns —
+            ``first/last_location_country`` and ``first/last_location_city``.
+            Device, browser, OS, referrer and UTM are browser observations and
+            come back in ``skipped`` rather than being stored; a backend
+            supplying them is guessing.
+
+        :returns: ``{"success", "distinctId", "created", "applied", "skipped"}``.
+            A skipped fixed key is a normal outcome (browser-owned or
+            browser-only), not an error.
+        """
+        # Absent bags are omitted rather than sent as null: the server
+        # distinguishes "no bag" from "empty bag" by presence.
+        payload: Dict[str, Any] = {"distinctId": distinct_id}
+        if properties is not None:
+            payload["properties"] = properties
+        if set_once is not None:
+            payload["setOnce"] = set_once
+        if fixed_properties is not None:
+            payload["fixedProperties"] = fixed_properties
+        return self._http.post_user_upsert(payload)  # type: ignore[attr-defined]

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/otel/processor.py

@@ -36,6 +36,10 @@ class TrodoRun:
     # Free-form run-level attributes (e.g. {"trodo.prompts": [...]} — the set of
     # managed-prompt versions used across the run, for prompt traceability).
     attributes: Optional[Dict[str, Any]] = None
+    # Optional user traits applied alongside the run (see wrap_agent's `user`
+    # kwarg). Forwarded verbatim to the backend, which applies them
+    # non-fatally — this is not a run column.
+    user: Optional[Dict[str, Any]] = None
     # Aggregates summed from child spans at finalisation.
     total_tokens_in: Optional[int] = None
     total_tokens_out: Optional[int] = None

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/otel/wrap_agent.py

@@ -212,6 +212,30 @@ def _aggregate(spans: list[TrodoSpan]) -> Dict[str, Any]:
     }
 
 
+def _user_bag(user: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Normalise a user-traits bag for the wire, or None when it carries
+    nothing.
+
+    Accepts both snake_case (``set_once`` / ``fixed_properties``, natural in
+    Python) and the camelCase the wire uses, so callers can write either.
+    Omitting an empty bag keeps the payload honest — the backend distinguishes
+    "no traits" from "empty traits" by presence.
+    """
+    if not isinstance(user, dict):
+        return None
+    out: Dict[str, Any] = {}
+    props = user.get("properties")
+    once = user.get("set_once", user.get("setOnce"))
+    fixed = user.get("fixed_properties", user.get("fixedProperties"))
+    if isinstance(props, dict) and props:
+        out["properties"] = props
+    if isinstance(once, dict) and once:
+        out["setOnce"] = once
+    if isinstance(fixed, dict) and fixed:
+        out["fixedProperties"] = fixed
+    return out or None
+
+
 def _mint_anon_distinct_id() -> str:
     """Mint a server-side anonymous distinct_id for an agent run.
 
@@ -420,6 +444,7 @@ def start_run(
     parent_run_id: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
     input: Any = None,
+    user: Optional[Dict[str, Any]] = None,
 ) -> str:
     """Open a Run record without holding a context manager.
 
@@ -448,6 +473,7 @@ def start_run(
         input=_prepare_value(input),
         started_at=_now_iso(),
         metadata=metadata,
+        user=_user_bag(user),
     )
     processor.mark_joined(rid)
     processor.start_run(run)
@@ -503,6 +529,7 @@ class wrap_agent:
         conversation_id: Optional[str] = None,
         parent_run_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
+        user: Optional[Dict[str, Any]] = None,
     ) -> None:
         self._processor = processor
         self._team_site_id = team_site_id
@@ -515,6 +542,7 @@ class wrap_agent:
         self._conversation_id = conversation_id
         self._parent_run_id = parent_run_id
         self._metadata = metadata
+        self._user = _user_bag(user)
         self._ctx_mgr: Optional[run_with_context] = None
         self._ctx: Optional[ActiveSpanContext] = None
         self._started_ms: float = 0.0
@@ -600,6 +628,9 @@ class wrap_agent:
             error_summary=error_summary,
             error_type=error_type,
             metadata={**(self._metadata or {}), **self.handle.metadata} or None,
+            # Traits travel on the failure path too — a run that threw is
+            # exactly when you still want to know who the user was.
+            user=self._user,
             attributes=(
                 {"trodo.prompts": self._ctx.prompt_state["all"]}
                 if self._ctx is not None

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/session/session_manager.py

@@ -6,12 +6,17 @@ import threading
 from typing import Dict, Optional
 
 from ..types import ServerSession
+from ..util.lru import DEFAULT_MAX_SIZE, LruDict
 from .server_session import build_session_payload, create_server_session
 
 
 class SessionManager:
-    def __init__(self) -> None:
-        self._sessions: Dict[str, ServerSession] = {}
+    def __init__(self, max_cached_users: int = DEFAULT_MAX_SIZE) -> None:
+        # LRU-bounded: one entry per distinct id, and a long-lived backend can
+        # see unbounded distinct ids. Evicted users are rebuilt on next use, and
+        # the server session id is deterministic (``server:{distinct_id}``), so a
+        # rebuild resolves to the same session rather than creating a duplicate.
+        self._sessions: LruDict[str, ServerSession] = LruDict(max_cached_users)
         self._lock = threading.Lock()
         self._confirmation_locks: Dict[str, threading.Event] = {}
         self._confirmation_started: Dict[str, bool] = {}
@@ -23,10 +28,11 @@ class SessionManager:
         session_id: Optional[str] = None,
     ) -> ServerSession:
         with self._lock:
-            if distinct_id in self._sessions:
-                return self._sessions[distinct_id]
+            existing = self._sessions.get(distinct_id)
+            if existing is not None:
+                return existing
             session = create_server_session(site_id, distinct_id, session_id)
-            self._sessions[distinct_id] = session
+            self._sessions.set(distinct_id, session)
             return session
 
     def ensure_confirmed(self, session: ServerSession, http_client: object) -> None:

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo/user_context.py

@@ -45,13 +45,16 @@ class UserContext:
         self._batch_flusher = batch_flusher
         self._auto_event_manager = auto_event_manager
         self._session_id_override = session_id
+        # Created on first use, not here.
+        #
+        # The session used to be built eagerly, which meant
+        # ``for_user(id).people.set(...)`` constructed a session object it never
+        # sent or read — pure waste on the stateless-backend path, where setting
+        # a property on a user you will not otherwise touch is a common call.
+        # Sessions are now created by the first operation that needs one
+        # (track / identify / wallet_address / capture_error).
         self._session: Optional["ServerSession"] = None
 
-        # Eagerly initialise session
-        self._session = self._session_manager.get_or_create(
-            distinct_id, site_id, session_id
-        )
-
         self.people = PeopleManager(
             http_client, site_id, lambda: self._get_distinct_id()
         )

trodo_python-2.18.0/trodo/util/__init__.py

@@ -0,0 +1 @@
+"""Internal utilities. Not part of the public API."""

trodo_python-2.18.0/trodo/util/lru.py

@@ -0,0 +1,71 @@
+"""A dict with a size ceiling that evicts least-recently-used entries.
+
+The SDK caches one context and one session per distinct id so repeated calls for
+the same user reuse them. Unbounded, that is a slow leak in exactly the
+deployment this SDK targets: a long-lived API server whose user cardinality
+grows without limit. A worker touching ten users never noticed; a service
+touching a million did.
+
+Eviction is safe because every cached value is reconstructible — an evicted user
+is rebuilt on next use, and server session ids are deterministic
+(``server:{distinct_id}``), so rebuilding produces the same session rather than a
+duplicate. The only cost of a miss is re-creating a small object.
+
+Backed by :class:`collections.OrderedDict`, whose ``move_to_end`` gives the
+recency ordering directly. Guarded by a lock because backend SDK users routinely
+call from a thread pool.
+
+Mirrors ``sdks/trodo-node-sdk/src/util/LruMap.ts``.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import Any, Generic, Optional, TypeVar
+
+__all__ = ["LruDict"]
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+DEFAULT_MAX_SIZE = 10_000
+
+
+class LruDict(Generic[K, V]):
+    def __init__(self, max_size: int = DEFAULT_MAX_SIZE) -> None:
+        # A non-positive cap would evict on every set and defeat the cache;
+        # treat it as "no caching is not a supported mode".
+        self._max_size = max_size if isinstance(max_size, int) and max_size > 0 else DEFAULT_MAX_SIZE
+        self._data: "OrderedDict[K, V]" = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: K) -> Optional[V]:
+        with self._lock:
+            if key not in self._data:
+                return None
+            self._data.move_to_end(key)
+            return self._data[key]
+
+    def set(self, key: K, value: V) -> None:
+        with self._lock:
+            self._data[key] = value
+            self._data.move_to_end(key)
+            while len(self._data) > self._max_size:
+                self._data.popitem(last=False)
+
+    def pop(self, key: K, default: Any = None) -> Any:
+        with self._lock:
+            return self._data.pop(key, default)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._data.clear()
+
+    def __contains__(self, key: object) -> bool:
+        with self._lock:
+            return key in self._data
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._data)

{trodo_python-2.17.0 → trodo_python-2.18.0}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.17.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.17.0 → trodo_python-2.18.0}/trodo_python.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ tests/test_prompt_trace.py
 tests/test_prompts.py
 tests/test_register_otel.py
 tests/test_start_run.py
+tests/test_user_traits.py
 tests/test_wrap_agent_unchanged.py
 trodo/__init__.py
 trodo/client.py
@@ -30,6 +31,7 @@ trodo/managers/experiment_manager.py
 trodo/managers/group_manager.py
 trodo/managers/people_manager.py
 trodo/managers/prompt_manager.py
+trodo/managers/user_manager.py
 trodo/otel/__init__.py
 trodo/otel/auto_instrument.py
 trodo/otel/context.py
@@ -49,6 +51,8 @@ trodo/queue/event_queue.py
 trodo/session/__init__.py
 trodo/session/server_session.py
 trodo/session/session_manager.py
+trodo/util/__init__.py
+trodo/util/lru.py
 trodo_python.egg-info/PKG-INFO
 trodo_python.egg-info/SOURCES.txt
 trodo_python.egg-info/dependency_links.txt