Quickstart Guide

Set up Your Account and Organization

Sign up for An Account and Log In

Navigate to https://app.tidepool.so/login. Click Login and then sign up for a Tidepool account. You can use any of email and password, Google, or Github to sign up.

📘

If someone at your organization has already signed up for Tidepool and you want to join their organization, skip this step and request that they invite you using the invite users to your organization guide.

Once you've signed up, finish setting up your account and log in to Tidepool.

Log in To Tidepool and Configure Your Settings

When you first log in to Tidepool, you'll see a screen that looks like this.

From your avatar in the top right, you can access your organization settings. Optionally configure things like

• Your account name
• Tidepool's appearance
• Your organization's name
• Your API keys
• The other members of your team
• Your billing tier (by default you're on the free tier).
  • Reference our pricing page for more information about upgraded plans.

Generate an API Key

To upload data, you'll need an API key. Generate a new key from the API Keys section of the Settings menu. Read our complete guide on managing API keys for more information.

Upload Data to Your Organization

The basic unit of data in Tidepool is an event. Events are user interactions, typically with a text interface like a large language model. Events are assigned to users (individual people performing actions in your app) and sessions (sets of events performed by a user in a single sitting).

There are a number of ways to get data into Tidepool. You can sync data from a data warehouse, you can stream data directly from an app, you can feed data from a Customer Data Platform (e.g. Segment), etc.

In this quickstart, we'll assume you're uploading data from a CSV using the Tidepool API. Read our data upload guide for more details on setting up integrations.

With your API key, you can submit data directly to Tidepool using a simple data upload script.

📘

Reach out to us via our Slack Community for help with data uploads or integration questions.

The sample script below assumes:

• You have event data with event IDs, user IDs, session IDs and event timestamps. Reference our API documentation for specifics about the expected schema and other details.
• Each event has associated text (representing the user input to the model, or the model's response to the user).

import requests # you might have to `pip install requests` if you don't have it installed
import csv
from time import sleep
from uuid import uuid4
from datetime import datetime

#################################
# Set up URLs + request headers #
#################################
DATA_FILEPATH = 'PATH_TO_YOUR_DATA.csv'

# submission and validation endpoints - reference https://docs.tidepool.so/reference/
API_BASE = 'https://shoreline.tidepool.so/api/v1/events'

# API keys are project specific - reference https://docs.tidepool.so/docs/manage-api-keys
headers = {
    "X-Tidepool-Api-Key": "YOUR_API_KEY_HERE",
    "Content-Type": "application/json",
}

############################################
# Load in data, batch it up, and format it #
############################################

# A little utility to batch data, since the API takes up to 100 events per batch
def make_batches(all_entries, n=100):
    return [all_entries[i : i + n] for i in range(0, len(all_entries), n)]

# Function to populate + verify a formatted event for upload
def make_event_from_dict(entry):
    # Set all required fields from the entry
    event = {}
    event['text'] = entry['text']
    # An iso timestamp with timezone, such as '2023-08-10T21:26:27.302Z'
    event['timestamp'] = entry['timestamp']
    
    # These fields must be set, but here are sane defaults if you don't have them on hand
    event['id'] = entry.get('id') or str(uuid4())
    event['session_id'] = entry.get('session_id') or str(uuid4())
    event['user_id'] = entry.get('user_id') or str(uuid4())
    event['event_name'] = entry.get('event_name') or 'USER_MESSAGE'
    return event

# Note: your CSV must have a header row with column names for csv.DictReader to work
with open(DATA_FILEPATH, 'r') as f:
    formatted_events = [make_event_from_dict(d) for d in csv.DictReader(f)]
    batched_events = make_batches(formatted_events)

######################
# Make the requests! #
######################

# Validate a single batch of data before going through the rest.
validate_resp = requests.post(f'{API_BASE}/validate', json=batched_events[0], headers=headers)
validate_resp.raise_for_status()

# Submit all the batches!
for i, batch in enumerate(batched_events):
    track_response = requests.post(f'{API_BASE}/track', json=batch, headers=headers)
    if not track_response.ok:
      print(track_response.text)
    track_response.raise_for_status()
    print(f"Submitted batch {i + 1} of {len(batched_events)}")
    sleep(0.2)

Analyze and Enrich Your Event Data

Once you've triggered the upload, you should see data start to appear in your organization within about 15 minutes.

Navigate to the Analyze page from the top menu bar, and you'll be able to see all of your events and sessions plotted by day. Click in to any row in the session table to see other events in that session.

At this stage, it's worth spending a few minutes scrolling through session and event data to get a feel for what the overall dataset looks like. This can help you pick up on potentially useful attributes to create in the next step.

Create An Attribute

Once you've gotten a feel for your dataset, you can start creating attributes to automatically group and categorize the unstructured text.

Navigate to the Discover page from the top menu bar and click the New Attribute button.

When creating a new attribute, you can either define your own attribute and categories or you can let Tidepool suggest potentially useful attributes and categories for you.

For the quickstart, try using the automatically suggested attributes. You'll be prompted to provide some context about your app and the feature the events are sourced from.

Writing detailed descriptions here will increase the quality of the attribute and category recommendations.

Choose whichever attribute you'd like to keep and click continue.

Reference the detailed attribute creation guide for more information about creating attributes.

Refine the Categories.

Once you've created an attribute, you'll automatically enter the category refinement workflow. You may need to wait a few minutes while the attribute's categories are calculated on a sample of the dataset.

Category refinement gives you an opportunity to see how events are mapped to categories within the attribute and either:

• confirm the category is working as expected
• update the category description
• break a subset of events from the category out into one or more new categories using the cluster view.

Review each category for the attribute and update the description or create a new category from the cluster view.

Once you've reviewed all of the attributes and are happy with the results, click the Finalize Attribute button in the bottom right of the screen.

Finalizing the attribute will lock the attribute's categories and being the process of calculating which category each event should be assigned to for the full dataset.

Any new event data submitted to the project will automatically be categorized for all finalized events.

Reference the expanded category refinement guide for more information about refining categories and finalizing attributes.

Analyzing the Categorized Events

Once the attribute is finalized, we'll assign each element in the full dataset to a category for the attribute. This process can take up to an hour, so you might want to check back later after you finalize an attribute.

Navigate to the Analyze page from the top menu bar. You should see your finalized attribute listed under the attributes section.

Click the attribute to segment the sessions chart by category. You can see the distribution of sessions by category for each attribute, as well as how the distribution changes over time.

Select an individual category to view the category level trend, as well as to filter the sessions in the summary table to just examples from the single category.

Selecting any row in the summary table will open the session and show the list of related events ordered by timestamp.

In addition to viewing category trends over time, you can also view the embedding distribution for an attribute.

Click an attribute to expand the list of categories, and then click the Clusters button.

The cluster view plots all events clustered by embedding similarity and colored by category.

The cluster view is useful to understand the relative distribution of your data across categories, as well as identify any significant outliers or poorly defined categories.

What's Next?

Now that you've completed the Tidepool quickstart, you should understand the basics of getting started managing your organization, uploading data to Tidepool, creating and refining attributes, and charting categorized event data for analysis.

As next steps:

• Join the Community to connect with the Aquarium team and stay up to date on the latest Tidepool news.
• Invite your team to collaborate on your enriched data in Tidepool.
• Continue adding new event data and creating new attributes to understand how your users are interacting with your app.