​
Installation

To use the Raindrop SDK, start by installing with pip:

pip install raindrop-ai

​
Configuration

First, import the SDK and set the write key. You’ll see your write key when you log into app.raindrop.ai

import raindrop.analytics as raindrop
raindrop.write_key = "YOUR_WRITE_KEY"

​
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.
  • model (Optional[str]): The name of the AI model used.
  • user_input (Optional[str]): The input provided by the user. (Either this or output is required)
  • output (Optional[str]): The output generated by the AI. (Either this or user_input is required)
  • convo_id (Optional[str]): The conversation ID associated with the interaction.
  • properties (Optional[Dict[str, Union[str, int, bool, float]]]): Additional properties associated with the AI event.

Example usage:

raindrop.track_ai(
    user_id="user123",
    event="user_message",
    model="gpt_4",
    user_input="What is the weather like today?", # this or output is required
    output="The weather is sunny and warm.", # this or user_input is required
    convo_id="conv789", # optional
    properties={
        "os_build": "17.1",
        "attachments": [
            {
                "type": "text",
                "name": "Additional Info",
                "value": "A very long document",
                "role": "input",
            },
            {
                "type": "image",
                "value": "https://example.com/image.png",
                "role": "output"
            },
            {
                "type": "iframe",
                "name": "Generated UI",
                "value": "https://newui.generated.com",
                "role": "output",
            },
        ]
    }
)

​
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:

attachments = [
    {
        "type": "code",
        "name": "Example Code",
        "value": "console.log('Hello, World!');",
        "role": "input",
        "language": "javascript",
    },
    {
        "type": "text",
        "name": "Additional Info",
        "value": "Some extra text",
        "role": "input",
    },
    {"type": "image", "value": "https://example.com/image.png", "role": "output"},
    {"type": "iframe", "value": "https://example.com/embed", "role": "output"},
]

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:

raindrop.identify(
    user_id="user123",
    traits={
        "name": "John Doe",
        "email": "john@example.com",
        "age": 30,
        "plan": "paid" #we recommend 'free', 'paid', 'trial'
    }
)

​
Tracking Other Events

To track normal events, you can use the track function. It takes the following parameters:

  • user_id (str): The unique identifier of the user.
  • event (str): The name of the event you want to track.
  • properties (Optional[Dict[str, Union[str, int, bool, float]]]): Additional properties associated with the event like location, OS version, etc.

Example usage:

raindrop.track(user_id="user123", event="product_viewed", properties={"product_id": "item456", "price": 9.99})

​
Timestamp

Note: You can optionally provide a timestamp parameter if you need to specify a custom time for the event. If not provided, the server will generate the timestamp.

​
Flushing Events

The Raindrop SDK uses a buffering mechanism to efficiently send events in batches. The events are automatically flushed when the buffer reaches a certain size (buffer_size) or after a specified timeout (buffer_timeout).

You can manually flush the events by calling the flush function. Make sure this happens before the process exits or you will lose events:

raindrop.flush()

​
Shutting Down

To ensure all events are processed before your application exits, call the shutdown function: 

raindrop.shutdown()

​
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: 10000)
  • upload_size: Number of events to send in a single API request (default: 100)
  • upload_interval: Time interval in seconds between automatic flushes (default: 1.0) You can modify these parameters if needed: 
raindrop.max_queue_size = 20000
raindrop.upload_size = 200
raindrop.upload_interval = 2.0

​
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:

raindrop.set_debug_logs(True)

That’s it! You should be ready to go. Please let us know if you have any questions.