Configuration

This page covers the runtime configuration options for KumoRFM, including run modes, temporal behavior, inference behavior, batch prediction, and retry handling.

Run Modes

The run_mode parameter controls the trade-off between prediction quality and speed by adjusting how much context data is sampled.

1
# Use the fastest mode for quick testing
2
result = model.predict(query, run_mode="DEBUG")
3
4
# Use the highest quality mode for production
5
result = model.predict(query, run_mode="BEST")

You can also fine-tune the neighbor sampling directly:

1
result = model.predict(
2
    query,
3
    num_neighbors=[64, 64, 8, 8, 4, 4],
4
)

Temporal and Context Timing

Use these parameters in KumoRFM.predict() and KumoRFM.evaluate() when you need to control the prediction timestamp or the historical examples used as model context.

For example, set anchor_time when you want to predict as of a specific point in time:

1
result = model.predict(
2
    query,
3
    indices=[0, 1, 2],
4
    anchor_time=pd.Timestamp("2024-06-01"),
5
)

Use context_anchor_time when the prediction date and the latest available context data should differ:

1
result = model.predict(
2
    query,
3
    indices=[0, 1, 2],
4
    anchor_time=pd.Timestamp("2024-06-01"),
5
    context_anchor_time=pd.Timestamp("2024-03-01"),
6
)

Set lag_timesteps when recent historical target values should be available to the model as additional context. For example, lag_timesteps=3 adds the previous three target windows as lagged features:

1
result = model.predict(
2
    query,
3
    indices=[0, 1, 2],
4
    lag_timesteps=3,
5
)

Inference Configuration

The inference_config parameter controls inference-time model behavior, including ensembling. You can pass either a dictionary or a configuration object from kumoapi.rfm.

When you pass a dictionary, KumoRFM casts it based on the task type:

• Classification tasks use ClassificationInferenceConfig.
• Regression and forecasting tasks use RegressionInferenceConfig.

If you omit inference_config, KumoRFM selects defaults automatically based on the task type.

Common options:

Classification option:

Regression and forecasting options:

When output_type="quantiles", the prediction output contains 27 quantile columns instead of a single TARGET_PRED column:

q_0.005 q_0.01  q_0.02  q_0.025 q_0.05  q_0.1   q_0.15
q_0.2   q_0.25  q_0.3   q_0.35  q_0.4   q_0.45  q_0.5
q_0.55  q_0.6   q_0.65  q_0.7   q_0.75  q_0.8   q_0.85
q_0.9   q_0.95  q_0.975 q_0.98  q_0.99  q_0.995

Classification example:

1
result = model.predict(
2
    query,
3
    indices=[0, 1, 2],
4
    inference_config=dict(
5
        num_estimators=4,
6
        column_shuffle=True,
7
        hop_shuffle=True,
8
        class_shuffle=True,
9
    ),
10
)

Regression example:

1
result = model.predict(
2
    regression_query,
3
    indices=[0, 1, 2],
4
    inference_config=dict(
5
        num_estimators=4,
6
        column_shuffle=True,
7
        target_transforms=["quantile", "clip", "power", None],
8
        output_type="median",
9
    ),
10
)

Output and Collection Controls

These options control what predict() returns and how KumoRFM collects valid context labels.

1
result = model.predict(
2
    query,
3
    indices=[0, 1, 2],
4
    return_embeddings=True,
5
    max_pq_iterations=20,
6
    random_seed=42,
7
)

Batch Mode

For predictions over many entities, use KumoRFM.batch_mode() to automatically split the workload into batches:

1
with model.batch_mode(batch_size='max', num_retries=1):
2
    result = model.predict(
3
        "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR users.user_id=1",
4
        indices=list(range(1, 1001)),
5
    )

Parameters:

• batch_size: The number of entities per batch. Set to "max" (default) to use the maximum applicable batch size for the task type.
• num_retries: Number of retries for failed batches due to server issues.

The maximum prediction sizes per task type are:

Retry

Use KumoRFM.retry() to automatically retry failed queries due to transient server issues:

1
with model.retry(num_retries=2):
2
    result = model.predict(query, indices=[1, 2, 3])

This is useful for long-running batch predictions where occasional failures are expected.

Size Limits

KumoRFM enforces a 30 MB context size limit per prediction. If exceeded, you will see an error message suggesting:

• Reducing the number of tables in the graph
• Reducing the number of columns (e.g., large text columns)
• Adjusting the neighborhood configuration
• Using a lower run mode

The optimize parameter in KumoRFM can help with database backends by creating indices for faster sampling:

1
model = rfm.KumoRFM(graph, optimize=True)