trodo-python 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

trodo/__init__.py

@@ -1,134 +1,177 @@
-"""
-trodo-python — Trodo Analytics SDK for Python
-
-Usage (module-level singleton):
-    import trodo
-    trodo.init(site_id='your-site-id')
-    user = trodo.for_user('user-123')
-    user.track('purchase_completed', {'amount': 99.99})
-
-Usage (class):
-    from trodo import TrodoClient
-    client = TrodoClient(site_id='your-site-id')
-    user = client.for_user('user-123')
-    user.track('purchase_completed', {'amount': 99.99})
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, List, Optional, Union
-
-from .client import TrodoClient
-from .user_context import UserContext
-from .managers.group_manager import GroupProfile
-from .types import ApiResult, IdentifyResult, ResetResult, WalletAddressResult
-
-__all__ = [
-    "TrodoClient",
-    "UserContext",
-    "GroupProfile",
-    "init",
-    "for_user",
-    "track",
-    "identify",
-    "wallet_address",
-    "reset",
-    "enable_auto_events",
-    "disable_auto_events",
-    "flush",
-    "shutdown",
-]
-
-# ============================================================================
-# Singleton convenience API
-# ============================================================================
-
-_client: Optional[TrodoClient] = None
-
-
-def _get_client() -> TrodoClient:
-    if _client is None:
-        raise RuntimeError(
-            "trodo-python: Call trodo.init(site_id=...) before using the SDK."
-        )
-    return _client
-
-
-def init(
-    site_id: str,
-    api_base: str = "https://sdkapi.trodo.ai",
-    timeout: int = 10,
-    retries: int = 2,
-    batch_enabled: bool = False,
-    batch_size: int = 50,
-    batch_flush_interval: float = 5.0,
-    auto_events: bool = False,
-    on_error: Optional[Any] = None,
-    debug: bool = False,
-) -> TrodoClient:
-    """Initialise the singleton SDK instance."""
-    global _client
-    _client = TrodoClient(
-        site_id=site_id,
-        api_base=api_base,
-        timeout=timeout,
-        retries=retries,
-        batch_enabled=batch_enabled,
-        batch_size=batch_size,
-        batch_flush_interval=batch_flush_interval,
-        auto_events=auto_events,
-        on_error=on_error,
-        debug=debug,
-    )
-    return _client
-
-
-def for_user(
-    distinct_id: str,
-    session_id: Optional[str] = None,
-) -> UserContext:
-    """Return a UserContext bound to the given distinctId."""
-    return _get_client().for_user(distinct_id, session_id)
-
-
-def track(
-    distinct_id: str,
-    event_name: str,
-    properties: Optional[Dict[str, Any]] = None,
-    category: str = "custom",
-) -> None:
-    """Track an event for a user (direct-call pattern)."""
-    _get_client().track(distinct_id, event_name, properties, category)
-
-
-def identify(distinct_id: str, identify_id: str) -> IdentifyResult:
-    """Alias a user's distinctId to an external identifier."""
-    return _get_client().identify(distinct_id, identify_id)
-
-
-def wallet_address(distinct_id: str, wallet_addr: str) -> WalletAddressResult:
-    """Associate a wallet address with a user."""
-    return _get_client().wallet_address(distinct_id, wallet_addr)
-
-
-def reset(distinct_id: str) -> ResetResult:
-    """Reset a user's session."""
-    return _get_client().reset(distinct_id)
-
-
-def enable_auto_events() -> None:
-    _get_client().enable_auto_events()
-
-
-def disable_auto_events() -> None:
-    _get_client().disable_auto_events()
-
-
-def flush() -> None:
-    """Flush any queued batch events."""
-    _get_client().flush()
-
-
-def shutdown() -> None:
-    """Flush, stop timers, and disable auto events."""
-    _get_client().shutdown()
+"""
+trodo-python — Trodo Analytics SDK for Python
+
+Usage (module-level singleton):
+    import trodo
+    trodo.init(site_id='your-site-id')
+    user = trodo.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+
+Usage (class):
+    from trodo import TrodoClient
+    client = TrodoClient(site_id='your-site-id')
+    user = client.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .client import TrodoClient
+from .user_context import UserContext
+from .managers.group_manager import GroupProfile
+from .types import (
+    ApiResult, ResetResult, WalletAddressResult,
+    AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps,
+)
+
+__all__ = [
+    "TrodoClient",
+    "UserContext",
+    "GroupProfile",
+    "init",
+    "for_user",
+    "track",
+    "identify",
+    "wallet_address",
+    "reset",
+    "enable_auto_events",
+    "disable_auto_events",
+    "flush",
+    "shutdown",
+    # Agent analytics
+    "AgentCallProps",
+    "ToolUseProps",
+    "AgentResponseProps",
+    "AgentErrorProps",
+    "FeedbackProps",
+    "track_agent_call",
+    "track_tool_use",
+    "track_agent_response",
+    "track_agent_error",
+    "track_feedback",
+]
+
+# ============================================================================
+# Singleton convenience API
+# ============================================================================
+
+_client: Optional[TrodoClient] = None
+
+
+def _get_client() -> TrodoClient:
+    if _client is None:
+        raise RuntimeError(
+            "trodo-python: Call trodo.init(site_id=...) before using the SDK."
+        )
+    return _client
+
+
+def init(
+    site_id: str,
+    api_base: str = "https://sdkapi.trodo.ai",
+    timeout: int = 10,
+    retries: int = 2,
+    batch_enabled: bool = False,
+    batch_size: int = 50,
+    batch_flush_interval: float = 5.0,
+    auto_events: bool = False,
+    on_error: Optional[Any] = None,
+    debug: bool = False,
+) -> TrodoClient:
+    """Initialise the singleton SDK instance."""
+    global _client
+    _client = TrodoClient(
+        site_id=site_id,
+        api_base=api_base,
+        timeout=timeout,
+        retries=retries,
+        batch_enabled=batch_enabled,
+        batch_size=batch_size,
+        batch_flush_interval=batch_flush_interval,
+        auto_events=auto_events,
+        on_error=on_error,
+        debug=debug,
+    )
+    return _client
+
+
+def for_user(
+    distinct_id: str,
+    session_id: Optional[str] = None,
+) -> UserContext:
+    """Return a UserContext bound to the given distinctId."""
+    return _get_client().for_user(distinct_id, session_id)
+
+
+def track(
+    distinct_id: str,
+    event_name: str,
+    properties: Optional[Dict[str, Any]] = None,
+    category: str = "custom",
+) -> None:
+    """Track an event for a user (direct-call pattern)."""
+    _get_client().track(distinct_id, event_name, properties, category)
+
+
+def identify(identify_id: str, session_id: Optional[str] = None) -> UserContext:
+    """Create or retrieve a UserContext for an identified user. Fires identify API on first call."""
+    return _get_client().identify(identify_id, session_id)
+
+
+def wallet_address(distinct_id: str, wallet_addr: str) -> WalletAddressResult:
+    """Associate a wallet address with a user."""
+    return _get_client().wallet_address(distinct_id, wallet_addr)
+
+
+def reset(distinct_id: str) -> ResetResult:
+    """Reset a user's session."""
+    return _get_client().reset(distinct_id)
+
+
+def enable_auto_events() -> None:
+    _get_client().enable_auto_events()
+
+
+def disable_auto_events() -> None:
+    _get_client().disable_auto_events()
+
+
+def flush() -> None:
+    """Flush any queued batch events."""
+    _get_client().flush()
+
+
+def shutdown() -> None:
+    """Flush, stop timers, and disable auto events."""
+    _get_client().shutdown()
+
+
+# ----------------------------------------------------------------------------
+# Agent Analytics — singleton wrappers
+# ----------------------------------------------------------------------------
+
+def track_agent_call(props: AgentCallProps) -> None:
+    """Track an LLM invocation / inbound message."""
+    _get_client().track_agent_call(props)
+
+
+def track_tool_use(props: ToolUseProps) -> None:
+    """Track a tool invocation within an agent turn."""
+    _get_client().track_tool_use(props)
+
+
+def track_agent_response(props: AgentResponseProps) -> None:
+    """Track an LLM response / completion."""
+    _get_client().track_agent_response(props)
+
+
+def track_agent_error(props: AgentErrorProps) -> None:
+    """Track an error during an agent turn."""
+    _get_client().track_agent_error(props)
+
+
+def track_feedback(props: FeedbackProps) -> None:
+    """Track a user feedback reaction on an agent response."""
+    _get_client().track_feedback(props)

trodo/api/async_client.py

@@ -1,96 +1,96 @@
-"""Async HTTP client using httpx (optional dependency)."""
-
-from __future__ import annotations
-
-import sys
-import asyncio
-from typing import Any, Callable, Dict, Optional
-
-from ..types import ApiResult, EventPayload
-
-
-class AsyncHttpClient:
-    def __init__(
-        self,
-        api_base: str,
-        site_id: str,
-        timeout: int = 10,
-        retries: int = 2,
-        on_error: Optional[Callable[[Exception], None]] = None,
-        debug: bool = False,
-    ) -> None:
-        try:
-            import httpx  # noqa: F401
-        except ImportError:
-            raise ImportError(
-                "trodo-python async support requires httpx: pip install trodo-python[async]"
-            )
-
-        self.api_base = api_base.rstrip("/")
-        self.site_id = site_id
-        self.timeout = timeout
-        self.retries = retries
-        self.on_error = on_error
-        self.debug = debug
-
-    def _log(self, *args: Any) -> None:
-        if self.debug:
-            sys.stderr.write(f"[trodo-python-async] {' '.join(str(a) for a in args)}\n")
-
-    async def _request(
-        self, path: str, body: Dict[str, Any], attempt: int = 0
-    ) -> ApiResult:
-        import httpx
-
-        url = f"{self.api_base}{path}"
-        self._log(f"POST {url}")
-        headers = {
-            "Content-Type": "application/json",
-            "X-Trodo-Site-Id": self.site_id,
-        }
-        try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                resp = await client.post(url, json=body, headers=headers)
-            if resp.status_code >= 500 and attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s")
-                await asyncio.sleep(delay)
-                return await self._request(path, body, attempt + 1)
-            try:
-                return resp.json()
-            except Exception:
-                return {}
-        except Exception as exc:
-            if attempt < self.retries:
-                await asyncio.sleep(2 ** attempt)
-                return await self._request(path, body, attempt + 1)
-            self._log(f"Error: {exc}")
-            if self.on_error:
-                self.on_error(exc)
-            return {}
-
-    async def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
-        return await self._request("/api/sdk/track", {"sessionData": session_data})
-
-    async def post_event(self, event: EventPayload) -> ApiResult:
-        return await self._request("/api/events", event.to_dict())
-
-    async def post_bulk_events(self, events: list) -> ApiResult:
-        return await self._request(
-            "/api/events/bulk", {"events": [e.to_dict() for e in events]}
-        )
-
-    async def post_identify(self, payload: Dict[str, Any]) -> ApiResult:
-        return await self._request("/api/sdk/identify", payload)
-
-    async def post_wallet_address(self, payload: Dict[str, Any]) -> ApiResult:
-        return await self._request("/api/sdk/wallet-address", payload)
-
-    async def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
-        return await self._request("/api/sdk/reset", payload)
-
-    async def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
-        return await self._request(path, payload)
-
-    async def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
-        return await self._request(path, payload)
+"""Async HTTP client using httpx (optional dependency)."""
+
+from __future__ import annotations
+
+import sys
+import asyncio
+from typing import Any, Callable, Dict, Optional
+
+from ..types import ApiResult, EventPayload
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        api_base: str,
+        site_id: str,
+        timeout: int = 10,
+        retries: int = 2,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        debug: bool = False,
+    ) -> None:
+        try:
+            import httpx  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "trodo-python async support requires httpx: pip install trodo-python[async]"
+            )
+
+        self.api_base = api_base.rstrip("/")
+        self.site_id = site_id
+        self.timeout = timeout
+        self.retries = retries
+        self.on_error = on_error
+        self.debug = debug
+
+    def _log(self, *args: Any) -> None:
+        if self.debug:
+            sys.stderr.write(f"[trodo-python-async] {' '.join(str(a) for a in args)}\n")
+
+    async def _request(
+        self, path: str, body: Dict[str, Any], attempt: int = 0
+    ) -> ApiResult:
+        import httpx
+
+        url = f"{self.api_base}{path}"
+        self._log(f"POST {url}")
+        headers = {
+            "Content-Type": "application/json",
+            "X-Trodo-Site-Id": self.site_id,
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(url, json=body, headers=headers)
+            if resp.status_code >= 500 and attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s")
+                await asyncio.sleep(delay)
+                return await self._request(path, body, attempt + 1)
+            try:
+                return resp.json()
+            except Exception:
+                return {}
+        except Exception as exc:
+            if attempt < self.retries:
+                await asyncio.sleep(2 ** attempt)
+                return await self._request(path, body, attempt + 1)
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {}
+
+    async def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/track", {"sessionData": session_data})
+
+    async def post_event(self, event: EventPayload) -> ApiResult:
+        return await self._request("/api/events", event.to_dict())
+
+    async def post_bulk_events(self, events: list) -> ApiResult:
+        return await self._request(
+            "/api/events/bulk", {"events": [e.to_dict() for e in events]}
+        )
+
+    async def post_identify(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/identify", payload)
+
+    async def post_wallet_address(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/wallet-address", payload)
+
+    async def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/reset", payload)
+
+    async def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)
+
+    async def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)

trodo/api/endpoints.py

@@ -1,20 +1,21 @@
-TRACK = "/api/sdk/track"
-EVENTS = "/api/events"
-EVENTS_BULK = "/api/events/bulk"
-IDENTIFY = "/api/sdk/identify"
-WALLET_ADDRESS = "/api/sdk/wallet-address"
-RESET = "/api/sdk/reset"
-PEOPLE_SET = "/api/sdk/people/set"
-PEOPLE_SET_ONCE = "/api/sdk/people/set_once"
-PEOPLE_UNSET = "/api/sdk/people/unset"
-PEOPLE_INCREMENT = "/api/sdk/people/increment"
-PEOPLE_APPEND = "/api/sdk/people/append"
-PEOPLE_UNION = "/api/sdk/people/union"
-PEOPLE_REMOVE = "/api/sdk/people/remove"
-PEOPLE_TRACK_CHARGE = "/api/sdk/people/track_charge"
-PEOPLE_CLEAR_CHARGES = "/api/sdk/people/clear_charges"
-PEOPLE_DELETE_USER = "/api/sdk/people/delete_user"
-GROUPS_SET = "/api/sdk/groups/set_group"
-GROUPS_ADD = "/api/sdk/groups/add_group"
-GROUPS_REMOVE = "/api/sdk/groups/remove_group"
-GROUPS_PROFILE = "/api/sdk/groups/profile"
+TRACK = "/api/sdk/track"
+TRACK_AGENT = "/api/sdk/track-agent"
+EVENTS = "/api/events"
+EVENTS_BULK = "/api/events/bulk"
+IDENTIFY = "/api/sdk/identify"
+WALLET_ADDRESS = "/api/sdk/wallet-address"
+RESET = "/api/sdk/reset"
+PEOPLE_SET = "/api/sdk/people/set"
+PEOPLE_SET_ONCE = "/api/sdk/people/set_once"
+PEOPLE_UNSET = "/api/sdk/people/unset"
+PEOPLE_INCREMENT = "/api/sdk/people/increment"
+PEOPLE_APPEND = "/api/sdk/people/append"
+PEOPLE_UNION = "/api/sdk/people/union"
+PEOPLE_REMOVE = "/api/sdk/people/remove"
+PEOPLE_TRACK_CHARGE = "/api/sdk/people/track_charge"
+PEOPLE_CLEAR_CHARGES = "/api/sdk/people/clear_charges"
+PEOPLE_DELETE_USER = "/api/sdk/people/delete_user"
+GROUPS_SET = "/api/sdk/groups/set_group"
+GROUPS_ADD = "/api/sdk/groups/add_group"
+GROUPS_REMOVE = "/api/sdk/groups/remove_group"
+GROUPS_PROFILE = "/api/sdk/groups/profile"