Install & Compatibility
Where this runs
tested against v2.22.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 23.38s
441MB installed
● package 441MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from kumoai.experimental.rfm import LocalGraph
✗ from kumoai.graph import LocalGraph
LocalGraph is part of the `experimental.rfm` submodule for the KumoRFM API, not directly under `kumoai.graph` for this use case.
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())
Debug
Known issues
gotchaKumo 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.fixGenerate 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.
affects: All
breakingThe 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.fixAlways 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.
affects: All versions, especially between minor releases (e.g., 0.x to 0.y)
gotchaData 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.fixEnsure 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.
affects: All
Errors
Common errors & fixes
HTTP 429 Too Many Requests
The client has sent too many requests within a given timeframe, exceeding the Kumo API's rate limits.
fixImplement 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
The provided API key is invalid, expired, or the request is unauthorized for another reason.
fixVerify 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'
Attempting to import `LocalGraph` directly from the top-level `kumoai` package or an incorrect submodule.
fixThe `LocalGraph` class (for KumoRFM) is located under `kumoai.experimental.rfm`. Use `from kumoai.experimental.rfm import LocalGraph` or `kumoai.experimental.rfm.LocalGraph`.
Upgrade
Version history
2.22.0latest on PyPI · released May 11, 2026
Audit
Dependencies
pandasoptionalCommonly used for data loading and manipulation in quickstart examples and typical ML workflows.