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

trodo/__init__.py

@@ -21,7 +21,10 @@ 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
+from .types import (
+    ApiResult, ResetResult, WalletAddressResult,
+    AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps,
+)
 
 __all__ = [
     "TrodoClient",
@@ -37,6 +40,17 @@ __all__ = [
     "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",
 ]
 
 # ============================================================================
@@ -101,9 +115,9 @@ def track(
     _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 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:
@@ -132,3 +146,32 @@ def flush() -> None:
 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/endpoints.py

@@ -1,4 +1,5 @@
 TRACK = "/api/sdk/track"
+TRACK_AGENT = "/api/sdk/track-agent"
 EVENTS = "/api/events"
 EVENTS_BULK = "/api/events/bulk"
 IDENTIFY = "/api/sdk/identify"

trodo/api/http_client.py

@@ -85,3 +85,6 @@ class HttpClient:
 
     def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
         return self._request(path, payload)
+
+    def post_agent_event(self, payload: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/track-agent", payload)

trodo/client.py

@@ -14,9 +14,13 @@ from .auto.auto_event_manager import AutoEventManager
 from .user_context import UserContext
 from .types import (
     ApiResult,
-    IdentifyResult,
     ResetResult,
     WalletAddressResult,
+    AgentCallProps,
+    ToolUseProps,
+    AgentResponseProps,
+    AgentErrorProps,
+    FeedbackProps,
 )
 
 
@@ -107,8 +111,12 @@ class TrodoClient:
     ) -> 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 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)
@@ -193,3 +201,118 @@ class TrodoClient:
         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)

trodo/types.py

@@ -77,3 +77,78 @@ ApiResult = Dict[str, Any]
 IdentifyResult = Dict[str, Any]
 WalletAddressResult = Dict[str, Any]
 ResetResult = Dict[str, Any]
+
+
+# ----------------------------------------------------------------------------
+# Agent Analytics
+# ----------------------------------------------------------------------------
+
+@dataclass
+class AgentCallProps:
+    agent_id: str
+    conversation_id: str
+    message_id: str
+    distinct_id: Optional[str] = None
+    prompt: Optional[str] = None
+    model: Optional[str] = None
+    temperature: Optional[float] = None
+    system_prompt_version: Optional[str] = None
+    provider: Optional[str] = None
+    timestamp: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolUseProps:
+    agent_id: str
+    conversation_id: str
+    message_id: str
+    tool_name: str
+    distinct_id: Optional[str] = None
+    input: Optional[Any] = None
+    output: Optional[Any] = None
+    latency_ms: Optional[int] = None
+    status: Optional[str] = None      # 'success' | 'failure'
+    timestamp: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentResponseProps:
+    agent_id: str
+    conversation_id: str
+    message_id: str
+    distinct_id: Optional[str] = None
+    output: Optional[str] = None
+    model: Optional[str] = None
+    completion_tokens: Optional[int] = None
+    prompt_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    finish_reason: Optional[str] = None
+    timestamp: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentErrorProps:
+    agent_id: str
+    conversation_id: str
+    message_id: str
+    distinct_id: Optional[str] = None
+    error_type: Optional[str] = None
+    error_message: Optional[str] = None
+    failed_tool: Optional[str] = None
+    traceback: Optional[str] = None
+    timestamp: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class FeedbackProps:
+    agent_id: str
+    conversation_id: str
+    message_id: str
+    feedback: str                       # 'positive' | 'negative' | 'unreact'
+    distinct_id: Optional[str] = None
+    timestamp: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)

trodo_python-1.2.0.dist-info/METADATA

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: trodo-python
+Version: 1.2.0
+Summary: Trodo Analytics SDK for Python — server-side event tracking
+License: ISC
+Keywords: analytics,tracking,trodo,server-side
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.27.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# trodo-python
+
+Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, manage people/groups, and instrument AI agents — all unified with your frontend data under the same `site_id`.
+
+## Installation
+
+```bash
+pip install trodo-python
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+import trodo
+
+trodo.init(site_id='your-site-id')
+
+# User-bound context (recommended)
+user = trodo.for_user('user-123')
+user.track('purchase_completed', {'amount': 99.99, 'plan': 'pro'})
+user.people.set({'plan': 'pro', 'company': 'Acme'})
+
+# Flush before process exit if using batching
+trodo.shutdown()
+```
+
+## Core API
+
+### `trodo.init(config)`
+
+Call once at app startup.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `site_id` | required | Your Trodo site ID |
+| `api_base` | `https://sdkapi.trodo.ai` | API base URL |
+| `timeout` | `10` s | HTTP request timeout |
+| `retries` | `2` | Retries on network/5xx errors |
+| `auto_events` | `False` | Hook `sys.excepthook` / `threading.excepthook` as `server_error` events |
+| `batch_enabled` | `False` | Queue events and flush in batches |
+| `batch_size` | `50` | Flush when this many events are queued |
+| `batch_flush_interval` | `5.0` s | Also flush every N seconds |
+| `on_error` | — | Callable on API errors (silent by default) |
+| `debug` | `False` | Log API calls to stderr |
+
+### `trodo.for_user(distinct_id, session_id=None)`
+
+Returns a user-bound context. No API call is made until you track an event.
+
+```python
+user = trodo.for_user('user-123', session_id=request.cookies.get('trodo_session'))
+```
+
+### `trodo.identify(identify_id, session_id=None)`
+
+Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinct_id` to an external identifier (email, DB id). Returns the user context.
+
+```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
+user.track('login')
+```
+
+### User context methods
+
+```python
+user.track(event_name, properties=None)         # Custom event
+user.identify(identify_id)                      # Merge identity
+user.wallet_address(address)                    # Set wallet address
+user.reset()                                    # Clear session
+user.capture_error(exc, severity='error')       # Track server_error ('critical' | 'error' | 'warning')
+
+# People profile
+user.people.set(properties)
+user.people.set_once(properties)
+user.people.unset(keys)
+user.people.increment(key, amount=1)
+user.people.append(key, values)
+user.people.union(key, values)
+user.people.remove(key, values)
+user.people.track_charge(amount, properties=None)
+user.people.clear_charges()
+user.people.delete_user()
+
+# Groups
+user.set_group(group_key, group_id)
+user.add_group(group_key, group_id)
+user.remove_group(group_key, group_id)
+group = user.get_group(group_key, group_id)
+group.set(properties)
+group.set_once(properties)
+group.increment(key, amount=1)
+group.append(key, values)
+group.union(key, values)
+group.remove(key, values)
+group.unset(keys)
+group.delete()
+```
+
+### Direct call pattern
+
+```python
+trodo.track('user-123', 'event_name', {'key': 'value'})
+trodo.people_set('user-123', {'plan': 'pro'})
+trodo.set_group('user-123', 'company', 'acme')
+```
+
+---
+
+## Agent Analytics
+
+Track every step of your LLM agents. Each call counts as one event toward your plan limit.
+
+**Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
+
+```python
+from trodo import (
+    AgentCallProps, ToolUseProps, AgentResponseProps,
+    AgentErrorProps, FeedbackProps,
+)
+```
+
+### `track_agent_call` — inbound message / LLM invocation
+
+```python
+trodo.track_agent_call(AgentCallProps(
+    agent_id='agt_abc12345',
+    conversation_id='conv_xyz',
+    message_id='msg_001',
+    prompt=user_message,
+    model='claude-3-5-sonnet',
+    provider='anthropic',
+    system_prompt_version='v2',   # optional — track prompt iterations
+    distinct_id=user_id,          # optional — link to a Trodo user
+))
+```
+
+### `track_tool_use` — tool/function call within a turn
+
+```python
+trodo.track_tool_use(ToolUseProps(
+    agent_id='agt_abc12345',
+    conversation_id='conv_xyz',
+    message_id='msg_001',
+    tool_name='fetch_billing_info',
+    latency_ms=143,
+    status='success',             # 'success' | 'failure'
+    input={'user_id': '123'},     # optional
+    output={'plan': 'pro'},       # optional
+))
+```
+
+### `track_agent_response` — LLM output and token usage
+
+```python
+trodo.track_agent_response(AgentResponseProps(
+    agent_id='agt_abc12345',
+    conversation_id='conv_xyz',
+    message_id='msg_001',
+    model='claude-3-5-sonnet',
+    completion_tokens=response.usage.output_tokens,
+    prompt_tokens=response.usage.input_tokens,
+    total_tokens=response.usage.input_tokens + response.usage.output_tokens,
+    finish_reason=response.stop_reason,
+    distinct_id=user_id,
+))
+```
+
+### `track_agent_error` — errors and failures
+
+```python
+import traceback
+
+trodo.track_agent_error(AgentErrorProps(
+    agent_id='agt_abc12345',
+    conversation_id='conv_xyz',
+    message_id='msg_001',
+    error_type='rate_limit',       # 'timeout' | 'rate_limit' | 'guardrail_block' | ...
+    error_message=str(exc),
+    failed_tool='fetch_billing_info',  # optional
+    traceback=traceback.format_exc(),  # optional
+))
+```
+
+### `track_feedback` — user thumbs up/down
+
+```python
+trodo.track_feedback(FeedbackProps(
+    agent_id='agt_abc12345',
+    conversation_id='conv_xyz',
+    message_id='msg_001',          # same message_id as the response it refers to
+    feedback='positive',           # 'positive' | 'negative' | 'unreact'
+    distinct_id=user_id,
+))
+```
+
+### Full turn example
+
+```python
+import traceback
+from trodo import AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps
+
+def run_agent_turn(user_id, conversation_id, user_message):
+    agent_id = 'agt_abc12345'
+    message_id = f'msg_{int(time.time() * 1000)}'
+
+    trodo.track_agent_call(AgentCallProps(
+        agent_id=agent_id, conversation_id=conversation_id,
+        message_id=message_id, prompt=user_message, distinct_id=user_id,
+    ))
+
+    try:
+        trodo.track_tool_use(ToolUseProps(
+            agent_id=agent_id, conversation_id=conversation_id,
+            message_id=message_id, tool_name='search', status='success', latency_ms=80,
+        ))
+
+        response = llm_client.complete(user_message)
+
+        trodo.track_agent_response(AgentResponseProps(
+            agent_id=agent_id, conversation_id=conversation_id, message_id=message_id,
+            model=response.model,
+            completion_tokens=response.usage.output_tokens,
+            prompt_tokens=response.usage.input_tokens,
+            total_tokens=response.usage.input_tokens + response.usage.output_tokens,
+            distinct_id=user_id,
+        ))
+
+        return response.text
+
+    except Exception as exc:
+        trodo.track_agent_error(AgentErrorProps(
+            agent_id=agent_id, conversation_id=conversation_id, message_id=message_id,
+            error_type=type(exc).__name__, error_message=str(exc),
+            traceback=traceback.format_exc(), distinct_id=user_id,
+        ))
+        raise
+```
+
+---
+
+## Identity Merging (Cross-SDK)
+
+Call `identify()` with the **same value** on the browser and server to merge all events under one user profile:
+
+```python
+# Python
+user.identify('user@example.com')   # → id_user@example.com
+
+# Browser (same value)
+# Trodo.identify('user@example.com') → id_user@example.com
+# Events from both sides now appear together in the dashboard
+```
+
+---
+
+## Flask / FastAPI Example
+
+```python
+# Flask
+from flask import Flask, request
+import trodo
+
+app = Flask(__name__)
+trodo.init(site_id='your-site-id')
+
+@app.route('/purchase', methods=['POST'])
+def purchase():
+    user = trodo.for_user(request.json['user_id'])
+    user.track('purchase_completed', {'amount': request.json['amount']})
+    return {'ok': True}
+```
+
+```python
+# FastAPI
+from fastapi import FastAPI, Request
+import trodo
+
+app = FastAPI()
+trodo.init(site_id='your-site-id')
+
+@app.post('/purchase')
+async def purchase(request: Request):
+    body = await request.json()
+    user = trodo.for_user(body['user_id'])
+    user.track('purchase_completed', {'amount': body['amount']})
+    return {'ok': True}
+```
+
+---
+
+## Batching
+
+```python
+trodo.init(
+    site_id='your-site-id',
+    batch_enabled=True,
+    batch_size=50,
+    batch_flush_interval=5.0,
+)
+
+# Always flush before process exit
+import atexit
+atexit.register(trodo.shutdown)
+```
+
+---
+
+## Auto Events
+
+```python
+trodo.init(site_id='your-site-id', auto_events=True)
+# Hooks sys.excepthook and threading.excepthook
+# Sends server_error events with distinct_id: 'server_global'
+
+# Toggle at runtime
+trodo.enable_auto_events()
+trodo.disable_auto_events()
+```
+
+---
+
+## Thread Safety
+
+The SDK is thread-safe. `SessionManager`, `EventQueue`, and `BatchFlusher` all use `threading.Lock` internally. Safe for multi-threaded Flask/Django/FastAPI apps.
+
+## License
+
+ISC

{trodo_python-1.0.1.dist-info → trodo_python-1.2.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-trodo/__init__.py,sha256=RkATreCecKMFz7ZgJATq52CWVxkWn5ANWzNIGOEweaQ,3499
-trodo/client.py,sha256=8EodhgXyBeVhouFytmnuSVUJlp7tTvyC_szSJ8h0yns,7056
-trodo/types.py,sha256=6XjAU9-ue7uRUMcW4aFq93t80d41jdTmCLEGks4R5n4,2438
+trodo/__init__.py,sha256=xbXCxPZtQfCgJeB1Yg_Rv067DOXCDztLXpo-f8XkL68,4837
+trodo/client.py,sha256=FkcUYymCMVJA9U509I5Lba9EZAYkjHb5-Fpoi3fI3oc,12122
+trodo/types.py,sha256=aX8aQrENDwSpouxqshHxDbjjzkvAveeClSSL0TDEygQ,4610
 trodo/user_context.py,sha256=9la6azzwEanVmdP4ps_xMoufbeWVeIGU-M8ychmgajg,7859
 trodo/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/api/async_client.py,sha256=rZN4aJ2QiKyrHBK260bApCUB9JaMWU6BQtzoSJZh7xk,3408
-trodo/api/endpoints.py,sha256=ZdEQh-aH62DVO5zSn8-HOKAjnxqAA4z_YXktfFgmEXw,798
-trodo/api/http_client.py,sha256=oKh3YXVQJG2TlFf6euRG92F91JU7DCnD7eeduQsIYOo,3119
+trodo/api/endpoints.py,sha256=JaJ5hjjKPi4aO6R25oasQTasEptg1FFFkDUIqO7uOXs,835
+trodo/api/http_client.py,sha256=h1p37Z-kmVxwCnodb5j8MXiP-cRwOKiF2lznoIW1bFI,3252
 trodo/auto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/auto/auto_event_manager.py,sha256=cztuRsRkNoJE5R4NfSfTrTJTGl4jx2Yb-Ncy0aVAPo8,4247
 trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -17,7 +17,7 @@ trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,87
 trodo/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/session/server_session.py,sha256=uBAq1QSYPUUaHFSeoOyM5Yr65dLb8T82OOx3D1BrdrE,1970
 trodo/session/session_manager.py,sha256=JrgH1VeicmtlxPR4dXEuJbxhi23OelkgwW3-9Slv80o,2525
-trodo_python-1.0.1.dist-info/METADATA,sha256=ja5ICQgHmloQMv8O8hA8cbBJT5uSSwc_CXPSgCaeEPo,6620
-trodo_python-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-trodo_python-1.0.1.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-1.0.1.dist-info/RECORD,,
+trodo_python-1.2.0.dist-info/METADATA,sha256=GNdzVrFziphK3z0HtY02YyMNNBgGrFuYpsf8EgML54Y,10179
+trodo_python-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trodo_python-1.2.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-1.2.0.dist-info/RECORD,,

trodo_python-1.0.1.dist-info/METADATA

@@ -1,227 +0,0 @@
-Metadata-Version: 2.4
-Name: trodo-python
-Version: 1.0.1
-Summary: Trodo Analytics SDK for Python — server-side event tracking
-License: ISC
-Keywords: analytics,tracking,trodo,server-side
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: ISC License (ISCL)
-Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28.0
-Provides-Extra: async
-Requires-Dist: httpx>=0.27.0; extra == "async"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: responses>=0.25.0; extra == "dev"
-Requires-Dist: httpx>=0.27.0; extra == "dev"
-
-# trodo-python
-
-Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, and manage people/groups — all merging seamlessly with your frontend Trodo data under the same `site_id`.
-
-## Installation
-
-```bash
-pip install trodo-python
-```
-
-For async support (optional):
-
-```bash
-pip install trodo-python[async]
-```
-
-Requires Python 3.8+.
-
-## Quick Start
-
-```python
-import trodo
-
-# Initialize once at app startup
-trodo.init(
-    site_id='your-site-id',
-    debug=False,        # optional: log API calls
-    auto_events=True,   # optional: hook sys.excepthook
-)
-
-# Get a user context
-user = trodo.for_user('user-123')
-
-# Track a custom event
-user.track('purchase_completed', {'amount': 99.99, 'plan': 'pro'})
-
-# Identify the user (merges with frontend events under the same identity)
-user.identify('user@example.com')   # distinct_id becomes id_user@example.com
-
-# Update people profile
-user.people.set({'plan': 'pro', 'company': 'Acme'})
-
-# Track a server-side error
-user.capture_error(Exception('payment failed'))
-
-# Flush queued events before process exit
-trodo.shutdown()
-```
-
-## Flask / FastAPI Example
-
-```python
-# Flask
-from flask import Flask, request
-import trodo
-
-app = Flask(__name__)
-trodo.init(site_id='your-site-id')
-
-@app.route('/purchase', methods=['POST'])
-def purchase():
-    user_id = request.json['user_id']
-    user = trodo.for_user(user_id)
-    user.track('purchase_completed', {'amount': request.json['amount']})
-    return {'ok': True}
-```
-
-## Cross-SDK Identity Merging
-
-Frontend and backend events merge when both sides call `identify()` with the same value:
-
-```python
-# Python SDK
-user.identify('user@example.com')    # → id_user@example.com
-
-# Browser SDK (same value)
-# Trodo.identify('user@example.com') → id_user@example.com
-
-# Both event streams now appear together in the Trodo dashboard
-```
-
-## API Reference
-
-### `trodo.init(config)`
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `site_id` | `str` | required | Your Trodo site ID |
-| `api_base` | `str` | `https://sdkapi.trodo.ai` | API base URL |
-| `debug` | `bool` | `False` | Log API requests/responses |
-| `auto_events` | `bool` | `False` | Hook `sys.excepthook` + `threading.excepthook` |
-| `retries` | `int` | `3` | HTTP retry attempts on 5xx errors |
-| `timeout` | `int` | `10` | HTTP timeout in seconds |
-| `batch_enabled` | `bool` | `False` | Queue events and flush in bulk |
-| `batch_size` | `int` | `50` | Max events per batch flush |
-| `batch_flush_interval` | `float` | `5.0` | Flush interval in seconds |
-| `on_error` | `callable` | `None` | Callback for SDK errors |
-
-### `trodo.for_user(distinct_id, session_id=None)`
-
-Returns a user-bound context. All subsequent calls use this user's session.
-
-```python
-user = trodo.for_user(
-    'user-123',
-    session_id=request.cookies.get('trodo_session'),  # optional: correlate with browser session
-)
-```
-
-### User Context Methods
-
-```python
-user.track(event_name, properties=None)          # Track custom event
-user.track_event(event_name, properties=None)    # Alias for track()
-user.identify(identify_id)                       # Merge identity
-user.wallet_address(address)                     # Set crypto wallet address
-user.reset()                                     # Clear session context
-user.capture_error(exception)                    # Track server_error event
-
-# People profile
-user.people.set(properties)
-user.people.set_once(properties)
-user.people.unset(keys)
-user.people.increment(properties)
-user.people.append(properties)
-user.people.union(properties)
-user.people.remove(properties)
-user.people.track_charge(amount, properties=None)
-user.people.clear_charges()
-user.people.delete_user()
-
-# Groups
-user.set_group(group_key, group_id)
-user.add_group(group_key, group_id)
-user.remove_group(group_key, group_id)
-group = user.get_group(group_key, group_id)
-group.set(properties)
-group.set_once(properties)
-group.union(properties)
-group.remove(properties)
-group.unset(keys)
-group.increment(properties)
-group.append(properties)
-group.delete()
-```
-
-### Direct Call Pattern (for pipelines/scripts)
-
-```python
-trodo.track('user-123', 'event_name', {'key': 'value'})
-trodo.identify('user-123', 'identify_id')
-trodo.people_set('user-123', {'plan': 'pro'})
-trodo.set_group('user-123', 'company', 'acme')
-```
-
-### Global Methods
-
-```python
-trodo.enable_auto_events()    # Enable sys.excepthook hooks
-trodo.disable_auto_events()   # Disable hooks
-trodo.flush()                 # Flush pending batch queue
-trodo.shutdown()              # Flush + stop background timers
-```
-
-## Auto Events
-
-When `auto_events=True`, the SDK wraps Python's exception hooks and sends `server_error` events to Trodo:
-
-- `sys.excepthook` — unhandled exceptions in the main thread
-- `threading.excepthook` — unhandled exceptions in threads
-
-These events use `distinct_id: 'server_global'` in the dashboard.
-
-Per-user error capture: `user.capture_error(e)` uses the user's own `distinct_id`.
-
-## Batching
-
-```python
-trodo.init(
-    site_id='your-site-id',
-    batch_enabled=True,
-    batch_size=100,
-    batch_flush_interval=3.0,
-)
-
-# Events are queued and flushed every 3s or when 100 events accumulate
-user.track('page_view')
-
-# Always flush before process exit
-import atexit
-atexit.register(trodo.shutdown)
-```
-
-## Thread Safety
-
-The SDK is thread-safe. `SessionManager`, `EventQueue`, and `BatchFlusher` all use `threading.Lock` internally. Safe to use in multi-threaded Flask/Django/FastAPI applications.
-
-## License
-
-ISC