KumoRFM SDK

Setup

View as Markdown

This guide walks you through setting up and making your first prediction with KumoRFM.

Authentication

Before using KumoRFM, you need to authenticate. There are several ways to do this:

Option 1: API Key

1import kumoai.rfm as rfm
2
3rfm.init(api_key="YOUR_API_KEY")

Option 2: OAuth2 Browser Login

1import kumoai.rfm as rfm
2
3rfm.authenticate()  # Opens a browser window for login

Option 3: Google Colab

In Google Colab, authenticate() automatically detects the environment and provides a widget-based login flow.

Option 4: Environment Variables

Set the KUMO_API_KEY and optionally RFM_API_URL environment variables before running your script:

$export KUMO_API_KEY="YOUR_API_KEY"

Then simply call:

1import kumoai.rfm as rfm
2
3rfm.init()

Option 5: Snowflake Native App

When running inside a Snowflake notebook with KumoRFM deployed as a Snowflake Native App:

1import kumoai.rfm as rfm
2
3rfm.init(snowflake_application="YOUR_APP_NAME")

End-to-End Example

Here is a complete example using local pandas DataFrames to predict customer churn:

1import pandas as pd
2import kumoai.rfm as rfm
3
4# 1. Authenticate
5rfm.init(api_key="YOUR_API_KEY")
6
7# 2. Prepare your data as pandas DataFrames
8df_users = pd.DataFrame({
9    "user_id": [1, 2, 3],
10    "signup_date": pd.to_datetime(["2023-01-01", "2023-02-15", "2023-03-20"]),
11    "location": ["US", "UK", "US"],
12})
13
14df_orders = pd.DataFrame({
15    "order_id": [101, 102, 103, 104],
16    "user_id": [1, 1, 2, 3],
17    "price": [50.0, 30.0, 100.0, 75.0],
18    "timestamp": pd.to_datetime([
19        "2024-01-10", "2024-02-15", "2024-01-20", "2024-03-05"
20    ]),
21})
22
23# 3. Create a Graph (automatically infers metadata and links)
24graph = rfm.Graph.from_data({
25    "users": df_users,
26    "orders": df_orders,
27})
28
29# 4. Initialize KumoRFM
30model = rfm.KumoRFM(graph)
31
32# 5. Make a prediction
33query = "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR users.user_id=1"
34result = model.predict(query)
35print(result)

The result is a pandas DataFrame containing the prediction for each entity.

Using Other Data Sources

KumoRFM supports multiple data backends beyond pandas DataFrames:

1# From a SQLite database:
2graph = rfm.Graph.from_sqlite("my_database.db")
3
4# From Snowflake:
5graph = rfm.Graph.from_snowflake(database="MY_DATABASE", schema="MY_SCHEMA")
6
7# From Databricks (Unity Catalog):
8graph = rfm.Graph.from_databricks(catalog="MY_CATALOG", schema="MY_SCHEMA")
9
10# From DuckDB:
11graph = rfm.Graph.from_duckdb("my_database.duckdb")
12
13# From a RelBench benchmark dataset:
14graph = rfm.Graph.from_relbench("f1")

See Data Requirements for full details on each data connector.

Next Steps