Get documentation on how to use KumoRFM.

KumoRFM is a pre-trained Relational Foundation Model (RFM) that generates training-free predictions on any relational multi-table data by interpreting the data as a (temporal) heterogeneous graph. It can be queried via the Predictive Query Language (PQL).

Internal note: It is NOT related to "Recency, Frequency, Monetary" analysis.

Internally, KumoRFM utilizes in-context learning to transfer patterns from historical examples to new unseen examples. Specifically, it constructs training/in-context subgraphs with known ground-truth labels and relates them to unseen subgraphs.

See the 'kumo://docs/overview' resource for more information.

KumoRFM can discover table-like files (e.g., CSV, Parquet), inspect them, and structure them into a graph via foreign key-primary key relationships. A time column in a table dictates the create time of a row, which is used downstream to receive and order historical interactions and prevent temporal leakage. Each column within a table is assigned a semantic type (numerical, categorical, multi-categorical, ID, text, timestamp, sequence, etc) that denotes the semantic meaning of the column and how it should be processed within the model.

Important: Before creating and updating graphs, read the documentation first at 'kumo://docs/graph-setup'.

After a graph is set up and materialized, KumoRFM can generate predictions (e.g., missing value imputation, temporal forecasts) and evaluations by querying the graph via the Predictive Query Language (PQL), a declarative language to formulate machine learning tasks. Understanding PQL and how it maps to a machine learning task is critical to achieve good model predictions. Besides PQL, various other options exist to tune model output, e.g., optimizing the run_mode of the model, specifying how subgraphs are formed via num_neighbors, or adjusting the anchor_time to denote the point in time for when a prediction should be made.

Important: Before executing or suggesting any predictive queries, read the documentation first at 'kumo://docs/predictive-query'.

KumoRFM can additionally generate explanations for predictions, providing both a global column-level analysis and a local, cell-level attribution view. Together, these views enable comprehensive interpretation.

Important: Before analyzing the explanation output, read the documentation first at 'kumo://docs/explainability'.

Authenticate the current KumoRFM session.

Authentication is needed once before predicting or evaluating with the KumoRFM model. If an API key is provided directly, it is used immediately. Otherwise, if the 'KUMO_API_KEY' environment variable is not set, this initiates an OAuth2 authentication flow by opening a browser window for user login. Sets the 'KUMO_API_KEY' environment variable upon successful authentication.

Finds all table-like files (e.g., CSV, Parquet) in a directory.

This tool is for local directories only. It cannot search, e.g., in S3 buckets.

Inspect the first rows of table-like files.

Each row in a file is represented as a dictionary mapping column names to their corresponding values.

Inspect the current graph metadata.

Confirming that the metadata is set up correctly is crucial for the RFM model to work properly. In particular,

• primary keys and time columns need to be correctly specified for each table in case they exist;

• columns need to point to a valid semantic type that describe their semantic meaning, or None if they have been discarded;

• links need to point to valid foreign key-primary key relationships.

Partially update the current graph metadata.

Setting up the metadata is crucial for the RFM model to work properly. In particular,

• primary keys and time columns need to be correctly specified for each table in case they exist;

• columns need to point to a valid semantic type that describe their semantic meaning, or None if they should be discarded;

• links need to point to valid foreign key-primary key relationships.

Omitted fields will be untouched.

For newly added tables, it is advised to double-check semantic types and modify in a follow-up step if necessary.

Make sure that tables are correctly linked before proceeding.

Note that all operations can be performed in a batch at once, e.g., one can add new tables and directly link them to together.

Important: Before creating and updating graphs, read the documentation first at 'kumo://docs/graph-setup'.

Return the graph as a Mermaid entity relationship diagram.

Important: The returned Mermaid markup can be used to input into an artifact to render it visually on the client side.

Materialize the graph based on the current state of the graph metadata to make it available for inference operations (e.g., predict and evaluate).

Any updates to the graph metadata require re-materializing the graph before the KumoRFM model can start making predictions again.

Lookup rows in the raw data frame of a table for a list of primary keys.

In contrast to the 'inspect_table_files' tool, this tool can be used to query specific rows in a registered table in the graph. It should not be used to understand and analyze table schema.

Use this tool to look up detailed information about recommended items to provide richer, more meaningful recommendations to users.

The table to read from needs to have a primary key, and the graph has to be materialized.

Execute a predictive query and return model predictions.

The graph needs to be materialized and the session needs to be authenticated before the KumoRFM model can start generating predictions.

The output prediction format depends on the given task type.

Binary classification: | ENTITY | ANCHOR_TIMESTAMP | TARGET_PRED | False_PROB | True_PROB | where 'ENTITY' holds the entity ID, 'ANCHOR_TIMESTAMP' holds the anchor time of the prediction in unix format, 'TARGET_PRED' holds the final prediction based on a threshold of 0.5, and 'False_PROB' and 'True_PROB' hold the probabilities.

Multi-class classification: | ENTITY | ANCHOR_TIMESTAMP | CLASS | SCORE | PREDICTED | where 'ENTITY' holds the entity ID, 'ANCHOR_TIMESTAMP' holds the anchor time of the prediction in unix format. Each row corresponds to an (ENTITY, CLASS) pair (up to 10 classes are reported), where 'CLASS' holds the predicted value, 'SCORE' holds its probability, and 'PREDICTED' denotes whether the (ENTITY, CLASS) pair has the highest likelihood.

Regression: | ENTITY | ANCHOR_TIMESTAMP | TARGET_PRED | where 'ENTITY' holds the entity ID, 'ANCHOR_TIMESTAMP' holds the anchor time of the prediction in unix format, and 'TARGET_PRED' holds the predicted numerical value.

Temporal link prediction: | ENTITY | ANCHOR_TIMESTAMP | CLASS | SCORE | where 'ENTITY' holds the entity ID, 'ANCHOR_TIMESTAMP' holds the anchor time of the prediction in unix format. Each row corresponds to an (ENTITY, CLASS) pair, where 'CLASS' holds the recommended item and 'SCORE' holds its likelihood.

Important: Before executing or suggesting any predictive queries, read the documentation first at 'kumo://docs/predictive-query'.

Evaluate a predictive query and return performance metrics which compares predictions against known ground-truth labels from historical examples.

The graph needs to be materialized and the session needs to be authenticated before the KumoRFM model can start evaluating.

Take the label distribution of the predictive query in the output logs into account when analyzing the returned metrics.

Important: Before executing or suggesting any predictive queries, read the documentation first at 'kumo://docs/predictive-query'.

Execute a predictive query and explain the model prediction.

The graph needs to be materialized and the session needs to be authenticated before the KumoRFM model can start generating an explanation for a prediction.

Only a single entity prediction can be explained at a time. The run_mode will be fixed to 'fast' mode for explainability. Note that the model prediction returned by the explanation might differ slightly from the result of the predict tool due to floating-point precision. Ignore such small differences.

Important: Before executing or suggesting any predictive queries, read the documentation first at 'kumo://docs/predictive-query'.

Important: Before analyzing the explanation output, read the documentation first at 'kumo://docs/explainability'.