raindrop-ai 0.0.19__py3-none-any.whl → 0.0.21__py3-none-any.whl

raindrop/analytics.py

@@ -1,14 +1,19 @@
 import sys
 import time
 import threading
-from typing import Union, List, Dict, Optional, Literal
+from typing import Union, List, Dict, Optional, Literal, Any
 import requests
 from datetime import datetime, timezone
 import logging
 import json
 import uuid
 import atexit
+from pydantic import ValidationError
+from threading import Timer
 from raindrop.version import VERSION
+from raindrop.models import TrackAIEvent, Attachment, SignalEvent, DefaultSignal, FeedbackSignal, EditSignal, PartialTrackAIEvent, PartialAIData
+from raindrop.interaction import Interaction
+
 
 
 # Configure logging
@@ -27,6 +32,10 @@ flush_thread = None
 shutdown_event = threading.Event()
 max_ingest_size_bytes = 1 * 1024 * 1024  # 1 MB
 
+_partial_buffers: dict[str, PartialTrackAIEvent] = {}
+_partial_timers: dict[str, Timer] = {}
+_PARTIAL_TIMEOUT = 2  # 2 seconds 
+
 def set_debug_logs(value: bool):
     global debug_logs
     debug_logs = value
@@ -125,58 +134,49 @@ def identify(user_id: str, traits: Dict[str, Union[str, int, bool, float]]) -> N
     data = {"user_id": user_id, "traits": traits}
     save_to_buffer({"type": "users/identify", "data": data})
 
-def track(
-    user_id: str,
-    event: str,
-    properties: Optional[Dict[str, Union[str, int, bool, float]]] = None,
-    timestamp: Optional[str] = None,
-) -> None:
-    if not _check_write_key():
-        return
-
-    data = {
-        "event_id": str(uuid.uuid4()),
-        "user_id": user_id,
-        "event": event,
-        "properties": properties,
-        "timestamp": timestamp if timestamp else _get_timestamp(),
-    }
-    data.setdefault("properties", {})["$context"] = _get_context()
-
-    save_to_buffer({"type": "events/track", "data": data})
 
 def track_ai(
     user_id: str,
     event: str,
+    event_id: Optional[str] = None,
     model: Optional[str] = None,
-    user_input: Optional[str] = None,
+    input: Optional[str] = None,
     output: Optional[str] = None,
     convo_id: Optional[str] = None,
     properties: Optional[Dict[str, Union[str, int, bool, float]]] = None,
     timestamp: Optional[str] = None,
-) -> None:
+    attachments: Optional[List[Attachment]] = None,
+) -> str:
     if not _check_write_key():
         return
+    
+    event_id = event_id or str(uuid.uuid4())
 
-    if not user_input and not output:
-        raise ValueError("One of user_input or output must be provided and not empty.")
+    try:
+        payload = TrackAIEvent(
+            event_id=event_id,
+            user_id=user_id,
+            event=event,
+            timestamp=timestamp or _get_timestamp(),
+            properties=properties or {},
+            ai_data=dict(          # Pydantic will coerce to AIData
+                model=model,
+                input=input,
+                output=output,
+                convo_id=convo_id,
+            ),
+            attachments=attachments,
+        )
+    except ValidationError as err:
+        logger.error(f"[raindrop] Invalid data passed to track_ai: {err}")
+        return None
 
-    event_id = str(uuid.uuid4())
 
-    data = {
-        "event_id": event_id,
-        "user_id": user_id,
-        "event": event,
-        "properties": properties or {},
-        "timestamp": timestamp if timestamp else _get_timestamp(),
-        "ai_data": {
-            "model": model,
-            "input": user_input,
-            "output": output,
-            "convo_id": convo_id,
-        },
-    }
-    data.setdefault("properties", {})["$context"] = _get_context()
+    if payload.properties is None:
+        payload.properties = {}
+    payload.properties["$context"] = _get_context()
+
+    data = payload.model_dump()
 
     size = _get_size(data)
     if size > max_ingest_size_bytes:
@@ -191,6 +191,9 @@ def track_ai(
 
 def shutdown():
     logger.info("Shutting down raindrop analytics")
+    for eid in list(_partial_timers.keys()):
+        _flush_partial_event(eid) 
+
     shutdown_event.set()
     if flush_thread:
         flush_thread.join(timeout=10)
@@ -219,24 +222,25 @@ def _get_timestamp():
 
 def _get_size(event: dict[str, any]) -> int:
     try:
-        data = json.dumps(event)
+        # Add default=str to handle types like datetime
+        data = json.dumps(event, default=str)
         return len(data.encode('utf-8'))
     except (TypeError, OverflowError) as e:
         logger.error(f"Error serializing event for size calculation: {e}")
         return 0 
 
-# Signal types
-SignalType = Literal["default", "feedback", "edit"]
+# Signal types - This is now defined in models.py
+# SignalType = Literal["default", "feedback", "edit"]
 
 def track_signal(
     event_id: str,
     name: str,
-    signal_type: Optional[SignalType] = "default",
+    signal_type: Literal["default", "feedback", "edit"] = "default",
     timestamp: Optional[str] = None,
-    properties: Optional[Dict[str, any]] = None,
+    properties: Optional[Dict[str, Any]] = None,
     attachment_id: Optional[str] = None,
     comment: Optional[str] = None,
-    after: Optional[str] = None,
+    after: Optional[str] = None
 ) -> None:
     """
     Track a signal event.
@@ -245,31 +249,55 @@ def track_signal(
         event_id: The ID of the event to attach the signal to
         name: Name of the signal (e.g. "thumbs_up", "thumbs_down")
         signal_type: Type of signal ("default", "feedback", or "edit")
-        timestamp: Optional timestamp for the signal
-        properties: Optional properties for the signal
+        timestamp: Optional timestamp for the signal (ISO 8601 format)
+        properties: Optional dictionary of additional properties.
         attachment_id: Optional ID of an attachment
-        comment: Optional comment (only for feedback signals)
-        after: Optional after content (only for edit signals)
+        comment: Optional comment string (required and used only if signal_type is 'feedback').
+        after: Optional after content string (required and used only if signal_type is 'edit').
     """
     if not _check_write_key():
         return
 
-    # Prepare properties with optional comment and after fields
-    signal_properties = properties or {}
-    if comment is not None:
-        signal_properties["comment"] = comment
-    if after is not None:
-        signal_properties["after"] = after
-
-    data = {
+    # Prepare the final properties dictionary
+    final_properties = properties.copy() if properties else {}
+    if signal_type == "feedback" and comment is not None:
+        if "comment" in final_properties:
+             logger.warning("'comment' provided as both argument and in properties; argument value used.")
+        final_properties["comment"] = comment
+    elif signal_type == "edit" and after is not None:
+        if "after" in final_properties:
+             logger.warning("'after' provided as both argument and in properties; argument value used.")
+        final_properties["after"] = after
+
+    # Prepare base arguments for all signal types
+    base_args = {
         "event_id": event_id,
         "signal_name": name,
-        "signal_type": signal_type,
-        "timestamp": timestamp if timestamp else _get_timestamp(),
-        "properties": signal_properties,
+        "timestamp": timestamp or _get_timestamp(),
+        "properties": final_properties,
         "attachment_id": attachment_id,
     }
 
+    try:
+        # Construct the specific signal model based on signal_type
+        if signal_type == "feedback":
+            payload = FeedbackSignal(**base_args, signal_type=signal_type)
+        elif signal_type == "edit":
+            payload = EditSignal(**base_args, signal_type=signal_type)
+        else: # signal_type == "default"
+            if comment is not None:
+                logger.warning("'comment' argument provided for non-feedback signal type; ignored.")
+            if after is not None:
+                logger.warning("'after' argument provided for non-edit signal type; ignored.")
+            payload = DefaultSignal(**base_args, signal_type=signal_type)
+
+    except ValidationError as err:
+        logger.error(f"[raindrop] Invalid data passed to track_signal: {err}")
+        return None
+
+    # model_dump handles the timestamp correctly
+    data = payload.model_dump(mode='json')
+
     size = _get_size(data)
     if size > max_ingest_size_bytes:
         logger.warning(
@@ -280,4 +308,98 @@ def track_signal(
 
     save_to_buffer({"type": "signals/track", "data": data})
 
+def begin(
+    user_id: str,
+    event: str,
+    event_id: str | None = None,
+    properties: Optional[Dict[str, Any]] = None,
+    input: Optional[str] = None,
+    attachments: Optional[List[Attachment]] = None,
+) -> Interaction:
+    """
+    Starts (or resumes) an interaction and returns a helper object.
+    """
+    eid = event_id or str(uuid.uuid4())
+    
+    # Prepare ai_data if input is provided
+    ai_data_partial = None
+    if input:
+        ai_data_partial = PartialAIData(input=input)
+
+    # Combine properties with initial_fields, giving precedence to initial_fields if keys clash
+    final_properties = (properties or {}).copy()
+
+    partial_event = PartialTrackAIEvent(
+        event_id=eid,
+        user_id=user_id,
+        event=event,
+        ai_data=ai_data_partial,
+        properties=final_properties or None, # Pass None if empty, matching PartialTrackAIEvent defaults
+        attachments=attachments
+    )
+
+    _track_ai_partial(partial_event)
+    return Interaction(eid)
+
+def resume_interaction(event_id: str) -> Interaction:
+    """Return an Interaction wrapper for an existing eventId."""
+    return Interaction(event_id)
+
+def _track_ai_partial(event: PartialTrackAIEvent) -> None:
+    """
+    Merge the incoming patch into an in-memory doc and flush to backend:
+      • on `.finish()`  (is_pending == False)
+      • or after 20 s of inactivity
+    """
+    eid = event.event_id
+
+    # 1. merge
+    existing = _partial_buffers.get(eid, PartialTrackAIEvent(event_id=eid))
+    existing.is_pending = existing.is_pending if existing.is_pending is not None else True
+    merged_dict = existing.model_dump(exclude_none=True)
+    incoming = event.model_dump(exclude_none=True)
+
+    # deep merge ai_data / properties
+    def _deep(d: dict, u: dict):
+        for k, v in u.items():
+            d[k] = _deep(d.get(k, {}) if isinstance(v, dict) else v, v) if isinstance(v, dict) else v
+        return d
+    merged = _deep(merged_dict, incoming)
+    merged_obj = PartialTrackAIEvent(**merged)
+
+    _partial_buffers[eid] = merged_obj
+
+    # 2. timer handling
+    if t := _partial_timers.get(eid):
+        t.cancel()
+    if merged_obj.is_pending is False:
+        _flush_partial_event(eid)
+    else:
+        _partial_timers[eid] = Timer(_PARTIAL_TIMEOUT, _flush_partial_event, args=[eid])
+        _partial_timers[eid].daemon = True
+        _partial_timers[eid].start()
+
+    if debug_logs:
+        logger.debug(f"[raindrop] updated partial {eid}: {merged_obj.model_dump(exclude_none=True)}")
+
+def _flush_partial_event(event_id: str) -> None:
+    """
+    Send the accumulated patch as a single object to `events/track_partial`.
+    """
+    if t := _partial_timers.pop(event_id, None):
+        t.cancel()
+
+    evt = _partial_buffers.pop(event_id, None)
+    if not evt:
+        return
+
+    # convert to ordinary TrackAIEvent-ish dict before send
+    data = evt.model_dump(mode="json", exclude_none=True)
+    size = _get_size(data)
+    if size > max_ingest_size_bytes:
+        logger.warning(f"[raindrop] partial event {event_id} > 1 MB; skipping")
+        return
+    
+    send_request("events/track_partial", data)
+
 atexit.register(shutdown)

raindrop/interaction.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, Callable
+from uuid import uuid4
+
+from .models import Attachment, PartialTrackAIEvent
+from . import analytics as _core
+
+
+class Interaction:
+    """
+    Thin helper returned by analytics.begin().
+    Each mutator just relays a partial update back to Analytics.
+    """
+    __slots__ = ("_event_id", "_analytics")
+
+    def __init__(self, event_id: Optional[str] = None):
+        self._event_id = event_id or str(uuid4())
+        self._analytics = _core
+        
+
+    # -- mutators ----------------------------------------------------------- #
+    def set_input(self, text: str) -> None:
+        self._analytics._track_ai_partial(
+            PartialTrackAIEvent(event_id=self._event_id, ai_data={"input": text})
+        )
+
+    def add_attachments(self, attachments: List[Attachment]) -> None:
+        self._analytics._track_ai_partial(
+            PartialTrackAIEvent(event_id=self._event_id, attachments=attachments)
+        )
+
+    def set_properties(self, props: Dict[str, Any]) -> None:
+        self._analytics._track_ai_partial(
+            PartialTrackAIEvent(event_id=self._event_id, properties=props)
+        )
+
+    def finish(self, *, output: str | None = None, **extra) -> None:
+        payload = PartialTrackAIEvent(
+            event_id=self._event_id,
+            ai_data={"output": output} if output is not None else None,
+            is_pending=False,
+            **extra,
+        )
+        self._analytics._track_ai_partial(payload)
+
+    # convenience
+    @property
+    def id(self) -> str:
+        return self._event_id

raindrop/models.py

@@ -0,0 +1,133 @@
+from pydantic import BaseModel, Field, ValidationError, model_validator, field_validator
+from typing import Any, Optional, Dict, Literal, List, Union
+from datetime import datetime, timezone
+
+class _Base(BaseModel):
+    model_config = dict(extra="forbid", validate_default=True)
+
+
+class Attachment(BaseModel):
+    type: Literal["code", "text", "image", "iframe"]
+    value: str                       # URL, raw code, etc.
+    name: Optional[str] = None       # e.g. "Generated SQL"
+    role: Optional[Literal["input", "output", "context"]] = None
+    language: Optional[str] = None   # for code snippets
+
+    @model_validator(mode="after")
+    def _require_value(cls, values):
+        if not values.value:
+            raise ValueError("value must be non-empty.")
+        return values
+
+class AIData(_Base):
+    model: Optional[str]
+    input: Optional[str]
+    output: Optional[str]
+    convo_id: Optional[str]
+
+    @model_validator(mode="after")
+    def _require_input_or_output(cls, values):
+        if not (values.input or values.output):
+            raise ValueError("Either 'input' or 'output' must be non-empty.")
+        return values
+    
+class TrackAIEvent(_Base):
+    event_id: Optional[str] = None
+    user_id: str
+    event: str
+    ai_data: AIData
+    properties: Dict[str, Any] = Field(default_factory=dict)
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+    )
+    attachments: Optional[List[Attachment]] = None
+
+    # Ensure user_id and event are non-empty strings
+    @field_validator("user_id", "event")
+    def _non_empty(cls, v, info):
+        if v is None or (isinstance(v, str) and v.strip() == ""):
+            raise ValueError(f"'{info.field_name}' must be a non-empty string.")
+        return v
+
+    # No need to duplicate input/output check here; AIData already enforces it
+    # but keep method to return values unchanged so that pydantic doesn't complain about unused return
+
+
+# --- Signal Tracking Models --- #
+
+class BaseSignal(_Base):
+    """Base model for signal events, containing common fields."""
+    event_id: str
+    signal_name: str
+    timestamp: datetime = Field(
+        # Return a datetime object; Pydantic's model_dump will handle serialization to string
+        default_factory=lambda: datetime.now(timezone.utc).replace(microsecond=0)
+    )
+    properties: Dict[str, Any] = Field(default_factory=dict)
+    attachment_id: Optional[str] = None
+
+    @field_validator("event_id", "signal_name")
+    def _non_empty_strings(cls, v, info):
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError(f"'{info.field_name}' must be a non-empty string.")
+        return v
+
+class DefaultSignal(BaseSignal):
+    """Model for default signal events."""
+    signal_type: Literal["default"] = "default"
+
+class FeedbackSignal(BaseSignal):
+    """Model for feedback signal events, requiring a comment."""
+    signal_type: Literal["feedback"]
+
+    @model_validator(mode="after")
+    def _check_comment_in_properties(cls, values):
+        # Check properties safely after potential initialization
+        # Use getattr to safely access properties, returning None if not present
+        props = getattr(values, 'properties', None) 
+        if not isinstance(props, dict):
+             raise ValueError("'properties' must be a dictionary for feedback signals.")
+        comment = props.get("comment")
+        if not comment or not isinstance(comment, str) or not comment.strip():
+            raise ValueError("'properties' must contain a non-empty string 'comment' for feedback signals.")
+        return values
+
+class EditSignal(BaseSignal):
+    """Model for edit signal events, requiring after content."""
+    signal_type: Literal["edit"]
+
+    @model_validator(mode="after")
+    def _check_after_in_properties(cls, values):
+        # Check properties safely after potential initialization
+        props = getattr(values, 'properties', None)
+        if not isinstance(props, dict):
+             raise ValueError("'properties' must be a dictionary for edit signals.")
+        after = props.get("after")
+        if not after or not isinstance(after, str) or not after.strip():
+             raise ValueError("'properties' must contain a non-empty string 'after' for edit signals.")
+        return values
+
+# Discriminated Union for Signal Events
+# Pydantic will automatically use the 'signal_type' field to determine which model to use.
+SignalEvent = Union[DefaultSignal, FeedbackSignal, EditSignal]
+
+# --- End Signal Tracking Models --- #
+
+
+class PartialAIData(_Base):
+    """Looser version for incremental updates."""
+    model: Optional[str] = None
+    input: Optional[str] = None
+    output: Optional[str] = None
+    convo_id: Optional[str] = None 
+
+class PartialTrackAIEvent(_Base):
+    """Accepts *any subset* of TrackAIEvent fields."""
+    event_id: str                                 # always required for merge-key
+    user_id: Optional[str] = None
+    event: Optional[str] = None
+    ai_data: Optional[PartialAIData] = None
+    timestamp: Optional[datetime] = None
+    properties: Optional[Dict[str, Any]] = None
+    attachments: Optional[List[Attachment]] = None
+    is_pending: Optional[bool] = True

raindrop_ai-0.0.21.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.1
+Name: raindrop-ai
+Version: 0.0.21
+Summary: Raindrop AI (Python SDK)
+License: MIT
+Author: Raindrop AI
+Author-email: sdk@raindrop.ai
+Requires-Python: >=3.11, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*, !=3.8.*, !=3.9.*, !=3.10.*
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pydantic (>=2.11,<3)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Raindrop Python SDK
+
+## Installation dependencies
+
+
+```bash
+pip install poetry
+```
+
+```bash
+poetry install
+```
+
+
+## Run tests
+
+```bash
+poetry run green -vv
+```
+
+
+
+
+
+

raindrop_ai-0.0.21.dist-info/RECORD

@@ -0,0 +1,8 @@
+raindrop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raindrop/analytics.py,sha256=IgxyvcbMa92FO5GFL3AcBnK1qv36NwxCQSiFbIh-9XU,13410
+raindrop/interaction.py,sha256=U8OapN5tZGSMVkn-dTLum5sIg_AgSYKX9lrtwgXJOuI,1613
+raindrop/models.py,sha256=THs3VQXGfJAdfg99rEBlqUzDh_F1HBC2hMOQx49l6BQ,5229
+raindrop/version.py,sha256=zKIDJIJluqVEGWC_VXIxFo3Hrk5Q7UGBBqP5uigDAN8,18
+raindrop_ai-0.0.21.dist-info/METADATA,sha256=8aH4lRYs-zEXfj0XSmrwlD4LTj5G-3pp3ahdwHL-k8c,774
+raindrop_ai-0.0.21.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+raindrop_ai-0.0.21.dist-info/RECORD,,

{raindrop_ai-0.0.19.dist-info → raindrop_ai-0.0.21.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (79.0.1)
+Generator: poetry-core 1.9.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

raindrop_ai-0.0.19.dist-info/METADATA

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: raindrop-ai
-Version: 0.0.19
-Summary: Raindrop AI (Python SDK)
-Home-page: https://raindrop.ai
-Author: Raindrop AI
-Author-email: sdk@raindrop.ai
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: requires-dist
-Dynamic: summary
-
-For questions, email us at sdk@raindrop.ai

raindrop_ai-0.0.19.dist-info/RECORD

@@ -1,7 +0,0 @@
-raindrop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-raindrop/analytics.py,sha256=zrhvoAM65KSFTc9VWwBTGKhfMtB0H_7J-QmApRXpOKc,8585
-raindrop/version.py,sha256=zKIDJIJluqVEGWC_VXIxFo3Hrk5Q7UGBBqP5uigDAN8,18
-raindrop_ai-0.0.19.dist-info/METADATA,sha256=CXtCww_mqKXivz4eIhbwymtWo2Y-XM28tSUzBoWSzp4,881
-raindrop_ai-0.0.19.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-raindrop_ai-0.0.19.dist-info/top_level.txt,sha256=yyf4RASIufJ0tUhUJ1-X3R05s9BuOU6dXCmv08UVpo8,9
-raindrop_ai-0.0.19.dist-info/RECORD,,

raindrop_ai-0.0.19.dist-info/top_level.txt

@@ -1 +0,0 @@
-raindrop