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

trodo/client.py

@@ -1,195 +1,318 @@
-"""TrodoClient — main SDK class for Python."""
-
-from __future__ import annotations
-
-from typing import Any, Dict, List, Optional, Union
-
-from .api.http_client import HttpClient
-from .session.session_manager import SessionManager
-from .managers.people_manager import PeopleManager
-from .managers.group_manager import GroupManager, GroupProfile
-from .queue.event_queue import EventQueue
-from .queue.batch_flusher import BatchFlusher
-from .auto.auto_event_manager import AutoEventManager
-from .user_context import UserContext
-from .types import (
-    ApiResult,
-    IdentifyResult,
-    ResetResult,
-    WalletAddressResult,
-)
-
-
-class TrodoClient:
-    def __init__(
-        self,
-        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,
-    ) -> None:
-        if not site_id:
-            raise ValueError("trodo-python: site_id is required")
-
-        self.site_id = site_id
-
-        self._http = HttpClient(
-            api_base=api_base,
-            site_id=site_id,
-            timeout=timeout,
-            retries=retries,
-            on_error=on_error,
-            debug=debug,
-        )
-
-        self._session_manager = SessionManager()
-
-        if batch_enabled:
-            self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
-            self._batch_flusher: Optional[BatchFlusher] = BatchFlusher(
-                self._event_queue, self._http, batch_flush_interval
-            )
-            self._batch_flusher.start()
-        else:
-            self._event_queue = None
-            self._batch_flusher = None
-
-        self._auto_event_manager = AutoEventManager(
-            site_id, self._http, self._session_manager
-        )
-
-        if auto_events:
-            self._auto_event_manager.enable()
-
-        self._user_context_cache: Dict[str, UserContext] = {}
-
-    # --------------------------------------------------------------------------
-    # Primary pattern: for_user()
-    # --------------------------------------------------------------------------
-
-    def for_user(
-        self,
-        distinct_id: str,
-        session_id: Optional[str] = None,
-    ) -> UserContext:
-        if distinct_id in self._user_context_cache:
-            return self._user_context_cache[distinct_id]
-
-        ctx = UserContext(
-            distinct_id=distinct_id,
-            site_id=self.site_id,
-            http_client=self._http,
-            session_manager=self._session_manager,
-            event_queue=self._event_queue,
-            batch_flusher=self._batch_flusher,
-            auto_event_manager=self._auto_event_manager,
-            session_id=session_id,
-        )
-        self._user_context_cache[distinct_id] = ctx
-        return ctx
-
-    # --------------------------------------------------------------------------
-    # Direct-call pattern (distinct_id as first arg)
-    # --------------------------------------------------------------------------
-
-    def track(
-        self,
-        distinct_id: str,
-        event_name: str,
-        properties: Optional[Dict[str, Any]] = None,
-        category: str = "custom",
-    ) -> None:
-        self.for_user(distinct_id).track(event_name, properties, category)
-
-    def identify(self, distinct_id: str, identify_id: str) -> IdentifyResult:
-        return self.for_user(distinct_id).identify(identify_id)
-
-    def wallet_address(self, distinct_id: str, wallet_addr: str) -> WalletAddressResult:
-        return self.for_user(distinct_id).wallet_address(wallet_addr)
-
-    def reset(self, distinct_id: str) -> ResetResult:
-        self._user_context_cache.pop(distinct_id, None)
-        return self.for_user(distinct_id).reset()
-
-    # People (direct)
-    def people_set(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
-        return self.for_user(distinct_id).people.set(properties)
-
-    def people_set_once(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
-        return self.for_user(distinct_id).people.set_once(properties)
-
-    def people_unset(self, distinct_id: str, keys: Union[str, List[str]]) -> ApiResult:
-        return self.for_user(distinct_id).people.unset(keys)
-
-    def people_increment(self, distinct_id: str, key: str, amount: float = 1) -> ApiResult:
-        return self.for_user(distinct_id).people.increment(key, amount)
-
-    def people_append(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
-        return self.for_user(distinct_id).people.append(key, values)
-
-    def people_union(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
-        return self.for_user(distinct_id).people.union(key, values)
-
-    def people_remove(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
-        return self.for_user(distinct_id).people.remove(key, values)
-
-    def people_track_charge(
-        self,
-        distinct_id: str,
-        amount: float,
-        properties: Optional[Dict[str, Any]] = None,
-    ) -> ApiResult:
-        return self.for_user(distinct_id).people.track_charge(amount, properties)
-
-    def people_clear_charges(self, distinct_id: str) -> ApiResult:
-        return self.for_user(distinct_id).people.clear_charges()
-
-    def people_delete_user(self, distinct_id: str) -> ApiResult:
-        return self.for_user(distinct_id).people.delete_user()
-
-    # Groups (direct)
-    def set_group(
-        self, distinct_id: str, group_key: str, group_id: Union[str, List[str]]
-    ) -> ApiResult:
-        return self.for_user(distinct_id).set_group(group_key, group_id)
-
-    def add_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
-        return self.for_user(distinct_id).add_group(group_key, group_id)
-
-    def remove_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
-        return self.for_user(distinct_id).remove_group(group_key, group_id)
-
-    def get_group(
-        self, distinct_id: str, group_key: str, group_id: str
-    ) -> GroupProfile:
-        return self.for_user(distinct_id).get_group(group_key, group_id)
-
-    # --------------------------------------------------------------------------
-    # Auto events
-    # --------------------------------------------------------------------------
-
-    def enable_auto_events(self) -> None:
-        self._auto_event_manager.enable()
-
-    def disable_auto_events(self) -> None:
-        self._auto_event_manager.disable()
-
-    # --------------------------------------------------------------------------
-    # Lifecycle
-    # --------------------------------------------------------------------------
-
-    def flush(self) -> None:
-        if self._batch_flusher:
-            self._batch_flusher.flush()
-
-    def shutdown(self) -> None:
-        self._auto_event_manager.disable()
-        if self._batch_flusher:
-            self._batch_flusher.stop()
-            self._batch_flusher.flush()
+"""TrodoClient — main SDK class for Python."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .api.http_client import HttpClient
+from .session.session_manager import SessionManager
+from .managers.people_manager import PeopleManager
+from .managers.group_manager import GroupManager, GroupProfile
+from .queue.event_queue import EventQueue
+from .queue.batch_flusher import BatchFlusher
+from .auto.auto_event_manager import AutoEventManager
+from .user_context import UserContext
+from .types import (
+    ApiResult,
+    ResetResult,
+    WalletAddressResult,
+    AgentCallProps,
+    ToolUseProps,
+    AgentResponseProps,
+    AgentErrorProps,
+    FeedbackProps,
+)
+
+
+class TrodoClient:
+    def __init__(
+        self,
+        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,
+    ) -> None:
+        if not site_id:
+            raise ValueError("trodo-python: site_id is required")
+
+        self.site_id = site_id
+
+        self._http = HttpClient(
+            api_base=api_base,
+            site_id=site_id,
+            timeout=timeout,
+            retries=retries,
+            on_error=on_error,
+            debug=debug,
+        )
+
+        self._session_manager = SessionManager()
+
+        if batch_enabled:
+            self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
+            self._batch_flusher: Optional[BatchFlusher] = BatchFlusher(
+                self._event_queue, self._http, batch_flush_interval
+            )
+            self._batch_flusher.start()
+        else:
+            self._event_queue = None
+            self._batch_flusher = None
+
+        self._auto_event_manager = AutoEventManager(
+            site_id, self._http, self._session_manager
+        )
+
+        if auto_events:
+            self._auto_event_manager.enable()
+
+        self._user_context_cache: Dict[str, UserContext] = {}
+
+    # --------------------------------------------------------------------------
+    # Primary pattern: for_user()
+    # --------------------------------------------------------------------------
+
+    def for_user(
+        self,
+        distinct_id: str,
+        session_id: Optional[str] = None,
+    ) -> UserContext:
+        if distinct_id in self._user_context_cache:
+            return self._user_context_cache[distinct_id]
+
+        ctx = UserContext(
+            distinct_id=distinct_id,
+            site_id=self.site_id,
+            http_client=self._http,
+            session_manager=self._session_manager,
+            event_queue=self._event_queue,
+            batch_flusher=self._batch_flusher,
+            auto_event_manager=self._auto_event_manager,
+            session_id=session_id,
+        )
+        self._user_context_cache[distinct_id] = ctx
+        return ctx
+
+    # --------------------------------------------------------------------------
+    # Direct-call pattern (distinct_id as first arg)
+    # --------------------------------------------------------------------------
+
+    def track(
+        self,
+        distinct_id: str,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        category: str = "custom",
+    ) -> None:
+        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]
+        ctx = self.for_user(identify_id, session_id)
+        ctx.identify(identify_id)
+        return ctx
+
+    def wallet_address(self, distinct_id: str, wallet_addr: str) -> WalletAddressResult:
+        return self.for_user(distinct_id).wallet_address(wallet_addr)
+
+    def reset(self, distinct_id: str) -> ResetResult:
+        self._user_context_cache.pop(distinct_id, None)
+        return self.for_user(distinct_id).reset()
+
+    # People (direct)
+    def people_set(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.set(properties)
+
+    def people_set_once(self, distinct_id: str, properties: Dict[str, Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.set_once(properties)
+
+    def people_unset(self, distinct_id: str, keys: Union[str, List[str]]) -> ApiResult:
+        return self.for_user(distinct_id).people.unset(keys)
+
+    def people_increment(self, distinct_id: str, key: str, amount: float = 1) -> ApiResult:
+        return self.for_user(distinct_id).people.increment(key, amount)
+
+    def people_append(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.append(key, values)
+
+    def people_union(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.union(key, values)
+
+    def people_remove(self, distinct_id: str, key: str, values: List[Any]) -> ApiResult:
+        return self.for_user(distinct_id).people.remove(key, values)
+
+    def people_track_charge(
+        self,
+        distinct_id: str,
+        amount: float,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> ApiResult:
+        return self.for_user(distinct_id).people.track_charge(amount, properties)
+
+    def people_clear_charges(self, distinct_id: str) -> ApiResult:
+        return self.for_user(distinct_id).people.clear_charges()
+
+    def people_delete_user(self, distinct_id: str) -> ApiResult:
+        return self.for_user(distinct_id).people.delete_user()
+
+    # Groups (direct)
+    def set_group(
+        self, distinct_id: str, group_key: str, group_id: Union[str, List[str]]
+    ) -> ApiResult:
+        return self.for_user(distinct_id).set_group(group_key, group_id)
+
+    def add_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
+        return self.for_user(distinct_id).add_group(group_key, group_id)
+
+    def remove_group(self, distinct_id: str, group_key: str, group_id: str) -> ApiResult:
+        return self.for_user(distinct_id).remove_group(group_key, group_id)
+
+    def get_group(
+        self, distinct_id: str, group_key: str, group_id: str
+    ) -> GroupProfile:
+        return self.for_user(distinct_id).get_group(group_key, group_id)
+
+    # --------------------------------------------------------------------------
+    # Auto events
+    # --------------------------------------------------------------------------
+
+    def enable_auto_events(self) -> None:
+        self._auto_event_manager.enable()
+
+    def disable_auto_events(self) -> None:
+        self._auto_event_manager.disable()
+
+    # --------------------------------------------------------------------------
+    # Lifecycle
+    # --------------------------------------------------------------------------
+
+    def flush(self) -> None:
+        if self._batch_flusher:
+            self._batch_flusher.flush()
+
+    def shutdown(self) -> None:
+        self._auto_event_manager.disable()
+        if self._batch_flusher:
+            self._batch_flusher.stop()
+            self._batch_flusher.flush()
+
+    # --------------------------------------------------------------------------
+    # Agent Analytics
+    # --------------------------------------------------------------------------
+
+    def _build_agent_base(
+        self,
+        agent_id: str,
+        conversation_id: str,
+        message_id: str,
+        event_type: str,
+        distinct_id: Optional[str] = None,
+        timestamp: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "event_type": event_type,
+            "agent_id": agent_id,
+            "conversation_id": conversation_id,
+            "message_id": message_id,
+        }
+        if distinct_id is not None:
+            payload["distinct_id"] = distinct_id
+        if timestamp is not None:
+            payload["timestamp"] = timestamp
+        return payload
+
+    def track_agent_call(self, props: AgentCallProps) -> None:
+        """Track an LLM invocation / inbound message."""
+        payload = self._build_agent_base(
+            props.agent_id, props.conversation_id, props.message_id,
+            "agent_call", props.distinct_id, props.timestamp,
+        )
+        if props.prompt is not None:
+            payload["prompt"] = props.prompt
+        if props.model is not None:
+            payload["model"] = props.model
+        if props.temperature is not None:
+            payload["temperature"] = props.temperature
+        if props.system_prompt_version is not None:
+            payload["system_prompt_version"] = props.system_prompt_version
+        if props.provider is not None:
+            payload["provider"] = props.provider
+        if props.properties:
+            payload.update(props.properties)
+        self._http.post_agent_event(payload)
+
+    def track_tool_use(self, props: ToolUseProps) -> None:
+        """Track a tool invocation within an agent turn."""
+        payload = self._build_agent_base(
+            props.agent_id, props.conversation_id, props.message_id,
+            "tool_use", props.distinct_id, props.timestamp,
+        )
+        payload["tool_name"] = props.tool_name
+        if props.input is not None:
+            payload["input"] = props.input
+        if props.output is not None:
+            payload["output"] = props.output
+        if props.latency_ms is not None:
+            payload["latency_ms"] = props.latency_ms
+        if props.status is not None:
+            payload["status"] = props.status
+        if props.properties:
+            payload.update(props.properties)
+        self._http.post_agent_event(payload)
+
+    def track_agent_response(self, props: AgentResponseProps) -> None:
+        """Track an LLM response / completion."""
+        payload = self._build_agent_base(
+            props.agent_id, props.conversation_id, props.message_id,
+            "agent_response", props.distinct_id, props.timestamp,
+        )
+        if props.output is not None:
+            payload["output"] = props.output
+        if props.model is not None:
+            payload["model"] = props.model
+        if props.completion_tokens is not None:
+            payload["completion_tokens"] = props.completion_tokens
+        if props.prompt_tokens is not None:
+            payload["prompt_tokens"] = props.prompt_tokens
+        if props.total_tokens is not None:
+            payload["total_tokens"] = props.total_tokens
+        if props.finish_reason is not None:
+            payload["finish_reason"] = props.finish_reason
+        if props.properties:
+            payload.update(props.properties)
+        self._http.post_agent_event(payload)
+
+    def track_agent_error(self, props: AgentErrorProps) -> None:
+        """Track an error during an agent turn."""
+        payload = self._build_agent_base(
+            props.agent_id, props.conversation_id, props.message_id,
+            "agent_error", props.distinct_id, props.timestamp,
+        )
+        if props.error_type is not None:
+            payload["error_type"] = props.error_type
+        if props.error_message is not None:
+            payload["error_message"] = props.error_message
+        if props.failed_tool is not None:
+            payload["failed_tool"] = props.failed_tool
+        if props.traceback is not None:
+            payload["traceback"] = props.traceback
+        if props.properties:
+            payload.update(props.properties)
+        self._http.post_agent_event(payload)
+
+    def track_feedback(self, props: FeedbackProps) -> None:
+        """Track a user feedback reaction on an agent response."""
+        payload = self._build_agent_base(
+            props.agent_id, props.conversation_id, props.message_id,
+            "feedback", props.distinct_id, props.timestamp,
+        )
+        payload["feedback"] = props.feedback
+        if props.properties:
+            payload.update(props.properties)
+        self._http.post_agent_event(payload)