Kumo AI Python SDK

0.79.0 · active · verified Thu Apr 16

The Kumo Python SDK (`kumoai`) provides a composable, modular interface for interacting with the Kumo machine learning platform. This platform leverages Graph Neural Networks (GNNs) to generate predictive analytics and insights directly from relational data. The SDK is currently at version 0.79.0 and receives frequent updates, often including new features and stability enhancements.

Common errors

```
HTTP 429 Too Many Requests
```
cause The client has sent too many requests within a given timeframe, exceeding the Kumo API's rate limits.

fix Implement rate limiting or exponential backoff in your application. Check your Kumo account's daily query limit (e.g., 1000/day for free tier) and consider upgrading your plan if higher throughput is needed.
```
HTTP 403 Forbidden
```
cause The provided API key is invalid, expired, or the request is unauthorized for another reason.

fix Verify that your `KUMO_API_KEY` is correct and current. Generate a new API key from the Kumo AI Admin tab if necessary, as old keys are invalidated upon rotation. Ensure no VPN or network policy is blocking access.
```
AttributeError: module 'kumoai' has no attribute 'LocalGraph'
```
cause Attempting to import `LocalGraph` directly from the top-level `kumoai` package or an incorrect submodule.

fix The `LocalGraph` class (for KumoRFM) is located under `kumoai.experimental.rfm`. Use `from kumoai.experimental.rfm import LocalGraph` or `kumoai.experimental.rfm.LocalGraph`.

Warnings

gotcha Kumo AI requires an API key for authentication, which should be treated as sensitive. Free accounts typically have daily query limits (e.g., 1000/day). Exceeding these limits will result in HTTP 429 Too Many Requests errors.
Fix: Generate your API key from the Kumo UI (kumorfm.ai/api-keys). Store it securely, preferably as an environment variable (e.g., `KUMO_API_KEY`). Monitor your usage to stay within rate limits, or upgrade your plan for higher limits.
breaking The Kumo AI SDK is under active development. Minor version updates can introduce breaking changes, particularly in submodules marked 'experimental'. Pay close attention to release notes for changes in API structure or required parameters.
Fix: Always check the official documentation and release notes before upgrading, especially when moving between minor versions. Pin your `kumoai` dependency to a specific version (e.g., `kumoai==0.79.0`) to prevent unexpected breakage.
gotcha Data quality significantly impacts prediction accuracy. Kumo expects genuinely missing values to be represented by completely blank entries. Using 'null', 'N/A', '-1', or similar strings for missing data will cause these to be treated as actual values, leading to erroneous model training and predictions.
Fix: Ensure that your input data adheres to Kumo's data quality guidelines. Specifically, for missing values, leave fields entirely blank. Review Kumo's documentation on data types and semantic types for best practices.

Install

pip install kumoai Install core SDK
pip install kumoai pandas Install with pandas (recommended for quickstart)

Imports

rfm
```
import kumoai.experimental.rfm as rfm
```
Primary import for KumoRFM client and graph operations.
kumoai
```
import kumoai as kumo
```
General import for broader SDK functionalities.
LocalGraph
wrong:
```
from kumoai.graph import LocalGraph
```
correct:
```
from kumoai.experimental.rfm import LocalGraph
```
LocalGraph is part of the `experimental.rfm` submodule for the KumoRFM API, not directly under `kumoai.graph` for this use case.

Quickstart

This quickstart demonstrates how to install the Kumo SDK, initialize a client with an API key, load an example dataset using pandas, create a local graph, and make a predictive query using KumoRFM.

import os
import pandas as pd
import kumoai.experimental.rfm as rfm

# Retrieve API key from environment variable for security
KUMO_API_KEY = os.environ.get('KUMO_API_KEY', '')

# Initialize the KumoRFM client
# You can generate an API key at https://kumorfm.ai/api-keys
rfm.init(api_key=KUMO_API_KEY)

# Example: Load E-Commerce dataset using pandas
dataset_url = "s3://kumo-sdk-public/rfm-datasets/online-shopping"
users_df = pd.read_parquet(f"{dataset_url}/users.parquet")
items_df = pd.read_parquet(f"{dataset_url}/items.parquet")
orders_df = pd.read_parquet(f"{dataset_url}/orders.parquet")

# Create a local graph from dataframes
graph = rfm.LocalGraph.from_data({
    "users": users_df,
    "items": items_df,
    "orders": orders_df,
})

# Initialize the KumoRFM model with the graph
model = rfm.KumoRFM(graph)

# Make a prediction (e.g., forecast 30-day product demand)
query = "PREDICT SUM(orders.price, 0, 30, days) FOR items.item_id=1"
result = model.predict(query)

print("Prediction Result:")
print(result.head())

view raw JSON →