Configuration

Configuration#

This page covers the runtime configuration options for KumoRFM, including run modes, explainability, 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.

Run Mode

Context Size

Neighbor Sampling

Use Case

DEBUG

100

[16, 16, 4, 4, 1, 1]

Quick iteration, testing queries

FAST

1,000

[32, 32, 8, 8, 4, 4]

Default. Good balance of speed and quality

NORMAL

5,000

[64, 64, 8, 8, 4, 4]

Higher quality predictions

BEST

10,000

[64, 64, 8, 8, 4, 4]

Maximum quality

 
# Use the fastest mode for quick testing
result = model.predict(query, run_mode="DEBUG")

# Use the highest quality mode for production
result = model.predict(query, run_mode="BEST")

You can also fine-tune the neighbor sampling directly:

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

Explainability#

KumoRFM can generate explanations alongside predictions using the explain parameter.

Basic explanation:

explanation = model.predict(query, explain=True)

# Access the prediction DataFrame
print(explanation.prediction)

# Access the human-readable summary
print(explanation.summary)

# Pretty-print both
explanation.print()

Skip the summary (faster, returns only prediction details):

explanation = model.predict(
    query,
    explain=ExplainConfig(skip_summary=True),
)

The Explanation object supports indexing for convenience:

prediction_df = explanation[0]   # Same as explanation.prediction
summary_text = explanation[1]    # Same as explanation.summary

Note

Explainability is currently only supported for single entity predictions with run_mode="FAST".

Batch Mode#

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

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

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:

Task Type

Max Prediction Size

Max Test Size

Classification / Regression / Forecasting

1,000

2,000

Retry#

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

with model.retry(num_retries=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:

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