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

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

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

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

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

trodo_python-2.25.0/tests/test_prompt_fingerprint.py

@@ -0,0 +1,198 @@
+"""Exact-match prompt linking for AUTO-INSTRUMENTED provider spans.
+
+Mirrors the Node promptFingerprint.test.ts. compile() before the run plus a
+provider call made by an auto-instrumentor leaves no run context at compile
+time and no carrier on the span's serialised input; compile() therefore
+registers a content fingerprint, and a model span whose input has identical
+(role, text) content is linked. Exact or nothing.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from trodo.managers.prompt_manager import PromptManager
+from trodo.otel import prompt_trace as pt
+from trodo.otel.auto_instrument import _OtelAdapter
+from trodo.otel.context import ActiveSpanContext, run_with_context
+
+RUN_ID = "11111111-1111-1111-1111-111111111111"
+ROOT = "22222222-2222-2222-2222-222222222222"
+
+WIRE = {
+    "name": "refund-agent",
+    "version": 3,
+    "version_hash": "a3f9c2e8d1b04756",
+    "content_hash": "ccccontent1234",
+    "labels": ["production"],
+    "tags": [],
+    "messages": [
+        {"role": "system", "content": [{"type": "text", "text": "You help with {{q}}"}]},
+        {"role": "user", "content": [{"type": "text", "text": "Hello {{q}}"}]},
+    ],
+    "model": {"provider": "openai", "model": "gpt-4o"},
+    "tools": [],
+    "response_format": None,
+    "variables": [{"name": "q", "type": "string"}],
+}
+
+
+class PromptHttp:
+    def __init__(self, fail=False):
+        self.fail = fail
+
+    def get_prompt(self, name, label=None, version=None):
+        if self.fail:
+            raise RuntimeError("unreachable")
+        return {"prompt": dict(WIRE)}
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    pt._reset_fingerprints_for_tests()
+    yield
+    pt._reset_fingerprints_for_tests()
+
+
+def provider_span(messages, extra=None):
+    attrs = {
+        "trodo.run_id": RUN_ID,
+        "trodo.parent_span_id": ROOT,
+        "gen_ai.request.model": "gpt-4o",
+        "gen_ai.system": "openai",
+        **(extra or {}),
+    }
+    for i, m in enumerate(messages):
+        attrs[f"gen_ai.prompt.{i}.role"] = m["role"]
+        attrs[f"gen_ai.prompt.{i}.content"] = m["content"]
+    span_context = SimpleNamespace(span_id=0xABCD1234ABCD1234)
+    return SimpleNamespace(
+        name="openai.chat",
+        get_span_context=lambda: span_context,
+        attributes=attrs,
+        start_time=1_000_000_000,
+        end_time=2_000_000_000,
+        status=None,
+        parent=None,
+    )
+
+
+def end_span(otel):
+    captured = []
+    proc = SimpleNamespace(enqueue_span=captured.append)
+    _OtelAdapter(proc).on_end(otel)
+    return captured[0] if captured else None
+
+
+def test_links_after_compile_before_run_with_identical_messages():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="my order")  # no run, no span
+    span = end_span(provider_span([
+        {"role": "system", "content": "You help with my order"},
+        {"role": "user", "content": "Hello my order"},
+    ]))
+    assert span.attributes["trodo.prompt.name"] == "refund-agent"
+    assert span.attributes["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+    assert span.attributes["trodo.prompt.label"] == "production"
+
+
+def test_matches_parts_arrays_and_anthropic_system_shape():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="x")
+    assert pt.prompt_ref_from_fingerprint(compiled.messages)["name"] == "refund-agent"
+    assert pt.prompt_ref_from_fingerprint({
+        "system": "You help with x",
+        "messages": [{"role": "user", "content": [{"type": "text", "text": "Hello x"}]}],
+    })["name"] == "refund-agent"
+
+
+def test_different_messages_do_not_link():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="my order")
+    span = end_span(provider_span([
+        {"role": "system", "content": "You help with my order"},
+        {"role": "user", "content": "Hello someone else"},
+    ]))
+    assert "trodo.prompt.name" not in (span.attributes or {})
+
+
+def test_fallback_is_never_linked():
+    mgr = PromptManager(PromptHttp(fail=True))
+    p = mgr.get(
+        "refund-agent",
+        cache_ttl_seconds=0,
+        fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}], "variables": []},
+    )
+    assert p.is_fallback
+    p.compile()
+    assert pt._fingerprint_count_for_tests() == 0
+    span = end_span(provider_span([{"role": "user", "content": "hi"}]))
+    assert "trodo.prompt.name" not in (span.attributes or {})
+
+
+def test_run_level_list_gets_the_prompt_via_on_start_state():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="a")
+    state = pt.new_prompt_state()
+    otel = provider_span([
+        {"role": "system", "content": "You help with a"},
+        {"role": "user", "content": "Hello a"},
+    ])
+    otel.set_attribute = lambda k, v: None
+    captured = []
+    adapter = _OtelAdapter(SimpleNamespace(enqueue_span=captured.append))
+    ctx = ActiveSpanContext(
+        run_id=RUN_ID, span_id=ROOT, parent_span_id=None,
+        team_site_id="site-x", processor=None, prompt_state=state,
+    )
+    with run_with_context(ctx):
+        adapter.on_start(otel)
+    adapter.on_end(otel)
+    assert captured[0].attributes["trodo.prompt.name"] == "refund-agent"
+    assert [r["name"] for r in state["all"]] == ["refund-agent"]
+
+
+def test_ttl_expiry(monkeypatch):
+    t = [1_000_000.0]
+    monkeypatch.setattr(pt, "_now", lambda: t[0])
+    ref = {"name": "p", "version_hash": "h1"}
+    msgs = [{"role": "user", "content": "hello"}]
+    pt.register_compiled_messages(msgs, ref)
+    assert pt.prompt_ref_from_fingerprint(msgs) == ref
+    t[0] += pt.FINGERPRINT_TTL_SECONDS + 1
+    assert pt.prompt_ref_from_fingerprint(msgs) is None
+    assert pt._fingerprint_count_for_tests() == 0
+
+
+def test_lru_eviction_beyond_cap():
+    for i in range(pt.FINGERPRINT_MAX_ENTRIES + 1):
+        pt.register_compiled_messages(
+            [{"role": "user", "content": f"m{i}"}], {"name": f"p{i}", "version_hash": f"h{i}"}
+        )
+    assert pt._fingerprint_count_for_tests() == pt.FINGERPRINT_MAX_ENTRIES
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "m0"}]) is None
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "m1"}])["name"] == "p1"
+
+
+def test_most_recent_compile_wins_on_identical_content():
+    msgs = [{"role": "user", "content": "same"}]
+    pt.register_compiled_messages(msgs, {"name": "p", "version_hash": "old"})
+    pt.register_compiled_messages(msgs, {"name": "p", "version_hash": "new"})
+    assert pt.prompt_ref_from_fingerprint(msgs)["version_hash"] == "new"
+    assert pt._fingerprint_count_for_tests() == 1
+
+
+def test_no_work_when_nothing_compiled(monkeypatch):
+    def boom(_):
+        raise AssertionError("should not fingerprint")
+
+    monkeypatch.setattr(pt, "fingerprint_messages", boom)
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "x"}]) is None
+
+
+def test_role_and_text_exact():
+    a = pt.fingerprint_messages([{"role": "user", "content": "x"}])
+    assert a != pt.fingerprint_messages([{"role": "assistant", "content": "x"}])
+    assert a != pt.fingerprint_messages([{"role": "user", "content": "x "}])
+    assert a == pt.fingerprint_messages('[{"role":"user","content":"x"}]')

trodo_python-2.25.0/tests/test_sender.py

@@ -0,0 +1,273 @@
+"""Background delivery (2.24): the agent's caller never waits on Trodo, and a
+trace is lost only when the queue is full, the server rejects it, or ten
+minutes of retrying did not get it accepted.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import pytest
+
+from trodo.delivery.sender import Sender, detect_mode, parse_retry_after_s
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import wrap_agent
+
+
+class Server:
+    """A fake /api/sdk/batch: a scripted list of replies, then 200 for everything."""
+
+    def __init__(self, script: Optional[List[Any]] = None, delay_s: float = 0.0) -> None:
+        self.script = list(script or [])
+        self.posts: List[Dict[str, Any]] = []
+        self.delay_s = delay_s
+        self.lock = threading.Lock()
+
+    def post_raw(self, path: str, body: Dict[str, Any], timeout: float = 0, gzip_body: bool = True):
+        if self.delay_s:
+            time.sleep(self.delay_s)
+        with self.lock:
+            self.posts.append({"path": path, "body": body, "at": time.time()})
+            nxt = self.script.pop(0) if self.script else None
+        if isinstance(nxt, Exception):
+            raise nxt
+        if nxt is not None:
+            return nxt
+        return 200, None, {"results": [{"status": 200} for _ in body["items"]]}
+
+    def post_run_ingest(self, p):
+        self.posts.append({"path": "legacy", "body": {"items": [p]}})
+        return {}
+
+
+def run(rid: str) -> Dict[str, Any]:
+    return {"run": {"run_id": rid, "agent_name": "bot"}, "spans": [{"span_id": f"{rid}-s1"}]}
+
+
+def fast(**o: Any) -> Dict[str, Any]:
+    """Sender options that make a test run in well under a second."""
+    return {"mode": "background", "on_error": lambda e: None, "register_atexit": False, "flush_interval_s": 0.05, **o}
+
+
+def wait_for(cond, timeout=3.0):
+    end = time.time() + timeout
+    while time.time() < end:
+        if cond():
+            return True
+        time.sleep(0.01)
+    return cond()
+
+
+def test_enqueue_returns_at_once_and_the_batch_follows():
+    s = Server(delay_s=0.2)
+    sender = Sender(s, **fast())
+    t0 = time.time()
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert time.time() - t0 < 0.05
+    assert s.posts == []
+    assert wait_for(lambda: len(s.posts) == 1)
+    assert s.posts[0]["path"] == "/api/sdk/batch"
+    assert s.posts[0]["body"]["items"] == [run("a"), run("b")]
+    sender.flush()
+    assert sender.stats()["sent"] == 2 and sender.stats()["dropped"] == 0
+
+
+def test_flush_at_items_sends_without_waiting_for_the_interval():
+    s = Server()
+    sender = Sender(s, **fast(flush_interval_s=60.0, flush_at=5))
+    for i in range(5):
+        sender.enqueue(run(f"r{i}"))
+    assert wait_for(lambda: len(s.posts) == 1)
+    assert len(s.posts[0]["body"]["items"]) == 5
+
+
+def test_429_pauses_the_sender_and_loses_nothing():
+    s = Server([(429, "0.3", {"error": "Rate ceiling exceeded"})])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: len(s.posts) == 1)
+    sender.enqueue(run("b"))
+    time.sleep(0.15)
+    assert len(s.posts) == 1          # still paused
+    assert sender.stats()["paused_until"] > time.time() - 0.01
+    assert wait_for(lambda: len(s.posts) == 2)
+    assert s.posts[1]["body"]["items"] == [run("a"), run("b")]
+    sender.flush()
+    assert sender.stats()["sent"] == 2 and sender.stats()["dropped"] == 0
+
+
+def test_outage_is_retried_with_backoff_until_the_server_is_back(monkeypatch):
+    import trodo.delivery.sender as m
+    monkeypatch.setattr(m, "_MIN_BACKOFF_S", 0.02)
+    s = Server([(503, None, None), RuntimeError("ECONNRESET"), RuntimeError("timeout")])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: sender.stats()["sent"] == 1, timeout=5)
+    assert len(s.posts) == 4
+    assert sender.stats()["dropped"] == 0
+
+
+def test_per_item_verdicts_accepted_rejected_deferred():
+    s = Server([(200, None, {"results": [{"status": 200}, {"status": 400, "error": "bad run"}, {"status": 429, "deferred": True}], "retry_after_ms": 100})])
+    sender = Sender(s, **fast(flush_at=3))
+    for rid in ("ok", "bad", "late"):
+        sender.enqueue(run(rid))
+    assert wait_for(lambda: len(s.posts) == 2)
+    assert s.posts[1]["body"]["items"] == [run("late")]
+    assert s.posts[1]["body"]["dropped"] == {"count": 1, "by_reason": {"rejected": 1}}   # the server is told
+    sender.flush()
+    st = sender.stats()
+    assert st["sent"] == 2 and st["dropped_by_reason"] == {"rejected": 1}
+
+
+def test_413_splits_the_batch_and_a_single_oversized_item_is_dropped():
+    s = Server([(413, None, {"error": "too large"}), (413, None, None)])
+    sender = Sender(s, **fast(flush_at=2))
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert wait_for(lambda: sender.stats()["sent"] == 1 and sender.stats()["dropped"] == 1)
+    assert [len(p["body"]["items"]) for p in s.posts] == [2, 1, 1]
+    assert sender.stats()["dropped_by_reason"] == {"too_large": 1}
+
+
+def test_a_full_queue_drops_the_oldest_and_counts_it():
+    s = Server([RuntimeError("down")])
+    sender = Sender(s, **fast(flush_interval_s=60.0, max_queue_items=3))
+    for rid in "abcde":
+        sender.enqueue(run(rid))
+    st = sender.stats()
+    assert st["queued"] == 3 and st["dropped_by_reason"] == {"queue_full": 2}
+    sender.flush(timeout_s=2)
+    sent = [i["run"]["run_id"] for p in s.posts for i in p["body"]["items"]]
+    assert sent[-3:] == ["c", "d", "e"]   # the newest survived
+
+
+def test_gives_up_after_max_retry(monkeypatch):
+    import trodo.delivery.sender as m
+    monkeypatch.setattr(m, "_MIN_BACKOFF_S", 0.01)
+    monkeypatch.setattr(m, "_MAX_BACKOFF_S", 0.02)
+    s = Server([RuntimeError("down")] * 100)
+    sender = Sender(s, **fast(max_retry_s=0.2))
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: sender.stats()["dropped"] == 1, timeout=5)
+    assert sender.stats()["dropped_by_reason"] == {"gave_up": 1}
+    assert sender.stats()["queued"] == 0
+
+
+def test_shutdown_flushes_then_stops_accepting():
+    s = Server()
+    sender = Sender(s, **fast(flush_interval_s=60.0))
+    sender.enqueue(run("a"))
+    sender.shutdown()
+    assert sender.stats()["sent"] == 1
+    sender.enqueue(run("b"))
+    time.sleep(0.1)
+    assert len(s.posts) == 1
+
+
+def test_legacy_server_without_batch_route_keeps_refused_items():
+    s = Server([(404, None, {"error": "Not found"}), (200, None, {"success": True}), (503, None, None)])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a")); sender.enqueue({"run_id": "a", "feedback": {"rating": 5}})
+    assert wait_for(lambda: sender.stats()["sent"] == 2, timeout=5)
+    assert [p["path"] for p in s.posts][:3] == ["/api/sdk/batch", "/api/sdk/runs/ingest", "/api/sdk/runs/a/feedback"]
+    assert sender.stats()["dropped"] == 0
+
+
+def test_on_error_sees_drops():
+    seen: List[str] = []
+    sender = Sender(Server(), mode="background", on_error=lambda e: seen.append(str(e)), register_atexit=False, max_queue_items=1)
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert len(seen) == 1 and "queue is full" in seen[0]
+
+
+def test_immediate_mode_blocks_only_within_its_budget():
+    s = Server([(503, None, None)] * 50)
+    slept: List[float] = []
+    clock = [0.0]
+
+    def sleep(x):
+        slept.append(x); clock[0] += x
+
+    sender = Sender(s, mode="immediate", on_error=lambda e: None, immediate_retry_s=15.0, now=lambda: clock[0], sleep=sleep)
+    sender.enqueue(run("a"))
+    assert sender.stats()["dropped_by_reason"] == {"gave_up": 1}
+    assert sum(slept) <= 15.0
+
+
+def test_immediate_mode_sends_before_returning():
+    s = Server([RuntimeError("blip")])
+    sender = Sender(s, mode="immediate", on_error=lambda e: None, sleep=lambda x: None)
+    sender.enqueue(run("a"))
+    assert len(s.posts) == 2 and sender.stats()["sent"] == 1
+
+
+def test_auto_mode_detection():
+    assert detect_mode({}) == "background"
+    assert detect_mode({"AWS_LAMBDA_FUNCTION_NAME": "fn"}) == "immediate"
+    assert detect_mode({"K_SERVICE": "svc"}) == "immediate"
+    assert detect_mode({"VERCEL": "1"}) == "immediate"
+    assert detect_mode({"KUBERNETES_SERVICE_HOST": "10.0.0.1"}) == "background"
+    assert parse_retry_after_s("12", 0) == 12.0
+    assert parse_retry_after_s("soon", 0) is None
+
+
+# ── through wrap_agent ───────────────────────────────────────────────────────
+
+def test_wrap_agent_returns_before_the_send_and_the_run_arrives_whole():
+    s = Server(delay_s=0.3)
+    sender = Sender(s, **fast())
+    processor = TrodoSpanProcessor(http_client=s, sender=sender)
+    t0 = time.time()
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat", distinct_id="u") as r:
+        r.set_input({"q": "hello"}); r.set_output({"a": "world"})
+    assert time.time() - t0 < 0.1     # not the server's 300 ms
+    sender.flush()
+    item = s.posts[0]["body"]["items"][0]
+    assert item["run"]["agent_name"] == "chat" and item["run"]["output"] == {"a": "world"}
+
+
+def test_async_with_wrap_agent_does_not_block_the_event_loop():
+    s = Server(delay_s=0.3)
+    sender = Sender(s, **fast())
+    processor = TrodoSpanProcessor(http_client=s, sender=sender)
+
+    async def main():
+        ticks = 0
+
+        async def ticker():
+            nonlocal ticks
+            for _ in range(5):
+                await asyncio.sleep(0.01); ticks += 1
+
+        t = asyncio.create_task(ticker())
+        async with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as r:
+            await asyncio.sleep(0.02)
+            r.set_output("done")
+        await t
+        return ticks
+
+    assert asyncio.run(main()) == 5
+    sender.flush()
+    assert s.posts[0]["body"]["items"][0]["run"]["output"] == "done"
+
+
+def test_agent_decorator_on_an_async_function_records_the_awaited_result():
+    from trodo.client import TrodoClient
+
+    s = Server()
+    client = TrodoClient(site_id="site-x", auto_instrument=False, delivery="background", delivery_options={"flush_interval_s": 0.05})
+    client._sender._http = s   # the fake server behind the real sender
+    client._sender._o["flush_interval_s"] = 0.05
+
+    @client.agent("async-bot")
+    async def bot(q: str) -> str:
+        await asyncio.sleep(0.01)
+        return q.upper()
+
+    assert asyncio.run(bot("hi")) == "HI"
+    client.flush(timeout=2)
+    item = s.posts[0]["body"]["items"][0]
+    assert item["run"]["agent_name"] == "async-bot"
+    assert item["run"]["output"] == "HI"     # not "<coroutine object ...>"

{trodo_python-2.23.4 → trodo_python-2.25.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.23.4"
+__version__ = "2.25.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -163,6 +163,8 @@ def init(
     auto_instrument: bool = True,
     disable_instrumentations: Optional[List[str]] = None,
     otel_mode: str = "trodo",
+    delivery: str = "auto",
+    delivery_options: Optional[Dict[str, Any]] = None,
 ) -> TrodoClient:
     """Initialise the singleton SDK instance.
 
@@ -171,6 +173,19 @@ def init(
     any other installed opentelemetry-instrumentation-* package, so
     LLM calls emit token/cost spans with no further code.
 
+    ``delivery`` (2.24): how traces reach Trodo.
+      'background' — wrap_agent returns at once; a daemon thread posts queued
+                     runs in batches every second, retries while nobody waits,
+                     and flushes at exit. The default on servers.
+      'immediate'  — the run is sent before wrap_agent returns, with short
+                     retries (≤ 15 s), for platforms that freeze between
+                     requests: Lambda, Cloud Functions, Cloud Run, Vercel.
+      'auto'       — 'immediate' when such a platform's environment variables
+                     are present, otherwise 'background'. Default.
+    ``delivery_options``: flush_interval_s (1), flush_at (50), max_batch_bytes
+    (4 MB), max_queue_items (10,000), max_queue_bytes (64 MB), max_retry_s
+    (600), exit_flush_s (5).
+
     ``disable_instrumentations`` turns OFF specific instrumentors by id
     (e.g. ``['openai']`` when LangChain is your primary framework, to avoid
     double-counting the same model call). Mirrors Node's
@@ -191,6 +206,8 @@ def init(
         auto_instrument=auto_instrument,
         disable_instrumentations=disable_instrumentations,
         otel_mode=otel_mode,
+        delivery=delivery,
+        delivery_options=delivery_options,
     )
     return _client
 

trodo_python-2.25.0/trodo/_version.py

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

{trodo_python-2.23.4 → trodo_python-2.25.0}/trodo/api/endpoints.py

@@ -22,8 +22,11 @@ GROUPS_REMOVE = "/api/sdk/groups/remove_group"
 GROUPS_PROFILE = "/api/sdk/groups/profile"
 # Agent run tracking (Lemma-style, run-centric)
 RUNS_INGEST = "/api/sdk/runs/ingest"
+# Many writes in one request — the background sender (delivery/sender.py).
+BATCH = "/api/sdk/batch"
 RUNS_START = "/api/sdk/runs/start"
 RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
+SPANS_APPEND = "/api/sdk/spans/append"
 OTLP_TRACES = "/api/sdk/otel/v1/traces"
 # Datasets & experiments
 DATASETS_BASE = "/api/sdk/datasets"  # /datasets/{ref}/items

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

@@ -11,6 +11,7 @@ import requests
 from ..types import ApiResult, EventPayload
 from . import endpoints
 from ._retry import jittered_backoff, retry_delay
+from .._version import SDK_VERSION
 
 
 class HttpClient:
@@ -82,9 +83,40 @@ class HttpClient:
                 return self._request(path, body, attempt + 1)
             self._log(f"Error: {exc}")
             if self.on_error:
-                self.on_error(exc)
+                try:
+                    self.on_error(exc)
+                except Exception:
+                    pass  # a handler that raises must not surface into user code
             return {}
 
+    def post_raw(
+        self, path: str, body: Dict[str, Any], timeout: Optional[float] = None, gzip_body: bool = True,
+    ) -> tuple:
+        """One attempt, the status told: ``(status, retry_after, parsed_body)``.
+
+        The background sender (delivery/sender.py) decides what to do with a
+        429, a 5xx or a timeout, so unlike ``_request`` this neither retries
+        nor swallows: it raises only on a network error or a timeout. Bodies
+        over 8 KB are gzipped.
+        """
+        import gzip as _gzip
+        import json as _json
+
+        url = f"{self.api_base}{path}"
+        raw = _json.dumps(body, default=str).encode("utf-8")
+        headers: Dict[str, str] = {"User-Agent": f"trodo-python/{SDK_VERSION}"}
+        data = raw
+        if gzip_body and len(raw) > 8 * 1024:
+            data = _gzip.compress(raw)
+            headers["Content-Encoding"] = "gzip"
+        self._log(f"POST {url} ({len(raw)} bytes{', gzip' if 'Content-Encoding' in headers else ''})")
+        resp = self._session.post(url, data=data, headers=headers, timeout=timeout or self.timeout)
+        try:
+            parsed = resp.json() if resp.text else None
+        except Exception:
+            parsed = {"body": resp.text[:300]}
+        return resp.status_code, resp.headers.get("retry-after"), parsed
+
     def _get(
         self, path: str, params: Optional[Dict[str, Any]] = None, attempt: int = 0
     ) -> ApiResult: