Python
The Raindrop SDK allows you to track user events and AI interactions in your app. This documentation provides a brief overview of how to use the Python SDK.
Installation
To use the Raindrop SDK, start by installing with pip:
Configuration
First, import the SDK and set the write key. You’ll see your write key when you log into app.raindrop.ai
Tracking AI Interactions
To track AI interactions, you can use the track_ai
function. It takes the following parameters:
user_id
(str): The unique identifier of the user.event
(str): The name of the AI event you want to track.event_id
(Optional[str]): A unique identifier for this specific event. If not provided, a UUID will be generated.model
(Optional[str]): The name of the AI model used.input
(Optional[str]): The input provided to the AI model. (Either this oroutput
is required if AI data is logged)output
(Optional[str]): The output generated by the AI. (Either this orinput
is required if AI data is logged)convo_id
(Optional[str]): The conversation ID associated with the interaction. Helpful in AI apps with multiple conversations per user (e.g. ChatGPT).properties
(Optional[Dict[str, Union[str, int, bool, float]]]): Additional properties associated with the AI event.timestamp
(Optional[str]): An ISO 8601 formatted timestamp for the event. If not provided, the SDK generates a UTC timestamp.attachments
(Optional[List[Attachment]]): A list of attachments associated with the event. See the Attachments section below.
Example usage:
Attachments
Attachments allow you to include context from the user (e.g. an attached image), or stuff that the model outputted (whether that is an image, document, code, or even an entire web page).
Each attachment is an object with the following properties:
type
(string): The type of attachment. Can be “code”, “text”, “image”, or “iframe”.name
(optional string): A name for the attachment.value
(string): The content or URL of the attachment.role
(string): Either “input” or “output”, indicating whether the attachment is part of the user input or AI output.language
(optional string): For code attachments, specifies the programming language.
Example of different attachment types:
Each event has a limit of 1 MB. Properties will be truncated for larger events.
Identifying Users
To associate traits with users, you can use the identify
function. It takes the following parameters:
user_id
(str): The unique identifier of the user.traits
(Dict[str, Union[str, int, bool, float]]): The traits associated with the user.
Example usage:
Partial Event Tracking (Interactions)
For multi-turn conversations or when event data arrives incrementally, you can use the begin()
and Interaction
object to send partial updates.
begin()
Starts or resumes an interaction and returns an Interaction
helper object.
user_id
(str): The user’s identifier.event
(str): The name of the event.event_id
(Optional[str]): A unique ID for the event. If not provided, one is generated.properties
(Optional[Dict[str, Any]]): Initial properties for the event.input
(Optional[str]): Initial input for the AI.attachments
(Optional[List[Attachment]]): Initial attachments.convo_id
(Optional[str]): Conversation ID.
resume_interaction()
If you already have an event_id
for an ongoing interaction, you can get an Interaction
object:
Interaction
Object Methods
The Interaction
object has the following methods to update the event:
interaction.set_input(text: str)
: Updates the AI input.interaction.add_attachments(attachments: List[Attachment])
: Adds more attachments.interaction.set_properties(props: Dict[str, Any])
: Merges new properties with existing ones.interaction.finish(output: Optional[str] = None, **extra)
: Marks the interaction as complete.output
: The final AI output.**extra
: Any other top-levelTrackAIEvent
fields to update (e.g.,properties
,attachments
).
The SDK automatically sends updates to the backend after a short period of inactivity or when finish()
is called.
Example usage:
Tracking Signals
Signals are used to attach user feedback (such as thumbs down or thumbs up) or other labels to existing events. Use the track_signal
function:
event_id
(str): The ID of the event to attach the signal to.name
(str): Name of the signal (e.g., “thumbs_up”, “copied_code”).signal_type
(Literal[“default”, “feedback”, “edit”]): Type of signal. Defaults to"default"
.- For
"feedback"
signals, a"comment"
string must be included in theproperties
. - For
"edit"
signals, an"after"
string (representing the content after edit) must be included in theproperties
.
- For
timestamp
(Optional[str]): ISO 8601 formatted timestamp. Defaults to current UTC time.properties
(Optional[Dict[str, Any]]): Additional properties for the signal.attachment_id
(Optional[str]): ID of a specific attachment within the original event to associate this signal with.comment
(Optional[str]): Convenience parameter for feedback signals. If provided, it’s added toproperties
as{"comment": "your comment"}
.after
(Optional[str]): Convenience parameter for edit signals. If provided, it’s added toproperties
as{"after": "new content"}
.
Example usage:
Shutting Down
To ensure all events are processed before your application exits, call the shutdown function:
This will also flush any pending partial events from interactions.
Error Handling
The SDK will retry a request up to 3 times. Failed requests will be logged, regardless of if debug_logs is true.
Configuration
The SDK has several configurable parameters:
max_queue_size
: Maximum number of events to store in the buffer (default: 10_000)upload_size
: Number of events to send in a single API request (default: 10)upload_interval
: Time interval in seconds between automatic flushes (default: 1.0) You can modify these parameters if needed:
Debugging
If you want to enable debug logs to see the events being added to the buffer, you can use the set_debug_logs
function:
That’s it! You should be ready to go. Please let us know if you have any questions.