Kumo SDK

https://kumo-ai.github.io/kumo-sdk/docs/
Admin
The Kumo Python SDK provides a composable, modular interface to train best-in-class Graph Neural...
Tokens:249,529
Snippets:1,479
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### FileUploadConnector: Upload Examples (Parquet and CSV)

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.FileUploadConnector

Provides various examples of using the upload() method for different scenarios: local small/large files, disabling auto-partitioning, CSV files, remote single files, and remote directories.

```python
import kumoai
conn = kumoai.FileUploadConnector(file_type="parquet")

# Local: small file
conn.upload(name="users", path="/data/users.parquet")

# Local: large file (auto-partitions)
conn.upload(
    name="txns",
    path="/data/large_txns.parquet",
)

# Local: disable auto-partitioning (raises if > 1 GiB)
conn.upload(
    name="users",
    path="/data/users.parquet",
    auto_partition=False,
)

# CSV connector
csv_conn = kumoai.FileUploadConnector(file_type="csv")
csv_conn.upload(name="sales", path="/data/sales.csv")

# Remote: single file (<= 1 GiB)
conn.upload(name="logs", path="s3://bkt/path/logs.parquet")

# Remote: directory of shards (uniform format)
csv_conn.upload(name="events", path="gs://mybkt/events_csv/")
```

--------------------------------

### Prediction-Ready Graph Structure Example (Python)

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/rfm/data_requirements/kumorfm_best_practices

Provides an example of how to structure data for prediction queries (PQL) within KumoRFM. It emphasizes the need for clear relationships (e.g., users to transactions) and the presence of timestamp information for time-based predictions.

```python
# Consider what PQL queries you want to run
# Example: "PREDICT COUNT(transactions.*, 0, 30, days) FOR users.user_id=1"
# Requires: users -> transactions relationship via user_id
# Requires: Timestamp at the transaction table
```

--------------------------------

### Example Usage of TrainingJobResult in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.trainer.TrainingJobResult

A concise example illustrating the creation of a TrainingJob object and retrieval of its result using the result() method.

```python
import kumoai
job_future = kumoai.TrainingJob(id=...)
job = job_future.result()

```

--------------------------------

### Initialize Kumo SDK (SaaS/Databricks)

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Initializes the Kumo SDK for SaaS or Databricks editions using a provided URL and API key. This is the first step to authenticate and connect to the Kumo platform.

```python
import kumoai as kumo
kumo.init(url="<url>/api", api_key="<api_key>")
```

--------------------------------

### Python Example: Basic Training Job Interaction

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/trainer/job

A simple Python example demonstrating the import of the kumoai library and the creation of a TrainingJob object, followed by retrieving its result.

```python
import kumoai  # doctest: +SKIP
job_future = kumoai.TrainingJob(id=...)  # doctest: +SKIP
job = job_future.result()  # doctest: +SKIP
```

--------------------------------

### Transform Data with PySpark

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Shows an example of transforming a source table (transactions) using PySpark. It calculates 'TotalPrice' and saves the altered data to a specified output directory in parquet format.

```python
from pyspark.sql.functions import col

root_dir = "s3://kumo-public-datasets/customerltv_mini/"

# An output directory (e.g. on S3) that you can write to, and Kumo can
# read from:
output_dir = ...

# Perform transformation with Spark
spark.read.parquet(f"{root_dir}/transaction") \
    .withColumn("TotalPrice", col("Quantity") * col("UnitPrice")) \
    .write.format("parquet").option("header","true").mode("Overwrite") \
    .save(f"{output_dir}/transaction_altered/")
```

--------------------------------

### Initialize Kumo SDK and Create Connector

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Initializes the Kumo SDK with API credentials and creates a data connector, such as an S3 connector. This is a prerequisite for interacting with Kumo services and accessing data sources.

```python
import kumoai as kumo

# Initialize the SDK:
kumo.init(url="https://<customer_id>.kumoai.cloud/api", api_key=API_KEY)

# Create a Connector:
connector = kumo.S3Connector("s3://kumo-public-datasets/customerltv_mini_integ_test/")
```

--------------------------------

### Python TrainingTableJob Usage Example

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/pquery/training_table

Demonstrates how to use the TrainingTableJob class to generate, monitor, and manage training table generation jobs. It covers creating a job, checking its status, attaching to it for progress updates, canceling it, and retrieving the final result. This example assumes an existing PredictiveQuery object.

```python
import kumoai

# See `PredictiveQuery` documentation:
pquery = kumoai.PredictiveQuery(...)

# If a training table is generated in nonblocking mode, the response
# will be of type `TrainingTableJob`:
training_table_job = pquery.generate_training_table(non_blocking=True)

# You can also construct a `TrainingTableJob` from a job ID, e.g.
# one that is present in the Kumo Jobs page:
training_table_job = kumoai.TrainingTableJob("trainingjob-...")

# Get the status of the job:
print(training_table_job.status())

# Attach to the job, and poll progress updates:
training_table_job.attach()

# Cancel the job:
training_table_job.cancel()

# Wait for the job to complete, and return a `TrainingTable`:
training_table_job.result()
```

--------------------------------

### PQL Filtering Context Examples

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/rfm/querying_rfm

Shows how to use filters in KumoRFM's PQL to refine the context data used for predictions. This example demonstrates excluding users without recent activity by checking the count of orders in a specific time window, thereby improving prediction relevance.

```PQL
PREDICT COUNT(orders.*, 0, 30, days) > 0
FOR users.user_id=1 WHERE COUNT(orders.*, -30, 0, days) > 0
```

--------------------------------

### KumoRFM Evaluation Mode Example

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/rfm/querying_rfm

Provides a Python example of how to use KumoRFM's evaluation mode to perform automatic evaluation on a sample of predictions. It shows constructing a query string for evaluation and then calling the `rfm.evaluate()` method to retrieve metrics.

```Python
>>> query = "EVALUATE PREDICT COUNT(orders.*, 0, 30, days) FOR users.user_id=1"
>>> metrics = rfm.evaluate(query)
>>> print(metrics)
```

--------------------------------

### Accessing and Inspecting Tables with S3Connector

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Demonstrates how to check for the existence of a table in an S3 connector and then print the head of the 'transaction_altered' table, specifically showing the 'TotalPrice' column. This requires an initialized S3Connector object.

```python
assert S3Connector(output_dir).has_table("transaction_altered")
print("Transaction price: ", connector["transaction_altered"].head(num_rows=2)["TotalPrice"])
```

--------------------------------

### Install Kumo SDK on Snowflake with External Access

Source: https://kumo-ai.github.io/kumo-sdk/docs/install/spcs

Installs the Kumo SDK directly within a Snowflake notebook environment configured for Snowpark Container using pip, assuming external network access is enabled.

```bash
pip install kumoai=<kumo_app_version>

```

--------------------------------

### Initialization and Configuration

Source: https://kumo-ai.github.io/kumo-sdk/docs/modules/root

This section details how to initialize the Kumo SDK with a URL and API key, and how to set the logging level.

```APIDOC
## Initialization and Configuration

### Description
Initializes the Kumo SDK and authenticates the API key against the Kumo service. It also allows setting the logging level to control the amount of output from methods.

### Methods

- **init(url: str, api_key: str, **kwargs)**
  Initializes and authenticates the API key against the Kumo service.

- **set_log_level(level: str)**
  Sets the Kumo logging level, which defines the amount of output that methods produce.

### Parameters

#### init Parameters
- **url** (str) - Required - The URL of the Kumo service.
- **api_key** (str) - Required - The API key for authentication.

#### set_log_level Parameters
- **level** (str) - Required - The desired logging level (e.g., 'DEBUG', 'INFO', 'WARNING', 'ERROR').

### Request Example
```python
import kumo

kumo.init(url='YOUR_KUMO_URL', api_key='YOUR_API_KEY')
kumo.set_log_level('INFO')
```

### Response

#### Success Response (200)

- **init**: Returns a success status upon successful initialization.
- **set_log_level**: Returns a success status upon successful log level update.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Initialize SourceTable and Get Connector Data

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.SourceTable

Demonstrates how to initialize an S3Connector and access a table named 'articles' from it. This is a common pattern for starting data operations with Kumo.

```python
import kumoai
connector = kumoai.S3Connector(root_dir='s3://...')
articles_src = connector['articles']
articles_src = kumoai.SourceTable('articles', connector)
```

--------------------------------

### Install Kumo Python SDK using pip

Source: https://kumo-ai.github.io/kumo-sdk/docs/install/installation

This command installs the Kumo Python SDK using pip. Ensure pip is installed and available in your environment before running this command. This installation method is standard across different Kumo platform editions (SaaS, Databricks, Snowflake).

```shell
pip install kumoai
```

--------------------------------

### Creating Kumo Tables from Scratch

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Shows an alternative method for creating Kumo `Table` objects by specifying columns and primary keys directly using the `kumo.Table` constructor. Metadata for unspecified columns can be inferred using `infer_metadata()`. Includes validation of the created table.

```python
stock = kumo.Table(
    source_table=stock_src,
    columns=dict(name='StockCode', stype='ID'),  # will infer dtype='string'
    primary_key='StockCode',
).infer_metadata()

# Validate the table's correctness:
stock.validate(verbose=True)
```

--------------------------------

### Check String Starts With Prefix (Python)

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.encoder.NAStrategy

Returns True if the string starts with the specified prefix, False otherwise. Optional start and end arguments can specify a slice of the string to check. The prefix can also be a tuple of strings.

```python
def startswith(_prefix_[, _start_[, _end_]]) -> bool:
    """
    Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.
    """
    pass
```

--------------------------------

### Verify Kumo Python SDK Installation

Source: https://kumo-ai.github.io/kumo-sdk/docs/install/installation

This Python code snippet imports the kumoai library and prints its version. Successful execution of this code confirms that the Kumo Python SDK has been installed correctly and is accessible in your Python environment.

```python
>>> import kumoai as kumo
>>> kumo.__version__
'2.9.0'
```

--------------------------------

### Quick Example: KumoRFM Workflow with E-commerce Data

Source: https://kumo-ai.github.io/kumo-sdk/docs/modules/experimental_rfm

Demonstrates the typical KumoRFM workflow, from loading data into pandas DataFrames, creating LocalTable objects, constructing a Graph, initializing KumoRFM, and executing a predictive query using PQL. The result is a pandas DataFrame containing prediction probabilities.

```python
import pandas as pd
from kumoai.experimental.rfm import Graph, KumoRFM

# Load your tables into memory:
users_df = pd.DataFrame({
    'user_id': [1, 2, 3, 4, 5],
    'name': ['Alice', 'Bob', 'Charlie', 'David', 'Eve'],
    'created_at': pd.date_range('2023-01-01', periods=5),
    'age': [25, 30, 35, 40, 45]
})

orders_df = pd.DataFrame({
    'order_id': [101, 102, 103, 104, 105],
    'user_id': [1, 2, 1, 3, 4],
    'amount': [100.0, 250.0, 75.0, 300.0, 150.0],
    'order_date': pd.date_range('2023-02-01', periods=5)
})

# Create a graph from tables:
graph = Graph.from_data({
    'users': users_df,
    'orders': orders_df
})

# Initialize KumoRFM:
rfm = KumoRFM(graph)

# Query the model
query = "PREDICT COUNT(orders.*, 0, 30, days)>0 FOR users.user_id=0"
result = rfm.predict(query)

# Result is a pandas DataFrame with prediction probabilities
print(result)  # user_id  COUNT(orders.*, 0, 30, days) > 0
               # 1        0.85

```

--------------------------------

### Creating a Kumo Graph

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Demonstrates the construction of a Kumo `Graph` object, which connects multiple `Table` objects based on their primary and foreign key relationships. The `Graph` constructor takes a dictionary of tables and a list of edges defining the relationships.

```python
graph = kumo.Graph(
    # These are the tables that participate in the graph: the keys of this
    # dictionary are the names of the tables, and the values are the Table
    # objects that correspond to these names:
    tables={
        'customer': customer,
        'stock': stock,
        'transaction': transaction,
    },

    # These are the edges that define the primary key / foreign key
    # relationships between the tables defined above. Here, `src_table`
    # is the table that has the foreign key `fkey`, which maps to the
    # table `dst_table`'s primary key:`
    edges=[
        dict(src_table='transaction', fkey='StockCode', dst_table='stock'),
        dict(src_table='transaction', fkey='CustomerID', dst_table='customer'),
    ],
)

# Validate the graph's correctness:
graph.validate(verbose=True)
```

--------------------------------

### Initialize and Predict with KumoRFM in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.experimental.rfm.KumoRFM

Demonstrates how to initialize the KumoRFM model with a Graph object and make predictions using a query. This example requires pandas for DataFrame creation and the kumoai.experimental.rfm module for Graph and KumoRFM classes. It shows constructing a graph from dataframes and then querying the RFM for predictions.

```python
from kumoai.experimental.rfm import Graph, KumoRFM
import pandas as pd

df_users = pd.DataFrame(...)
df_items = pd.DataFrame(...)
df_orders = pd.DataFrame(...)

graph = Graph.from_data({
    'users': df_users,
    'items': df_items,
    'orders': df_orders,
})

rfm = KumoRFM(graph)

query = ("PREDICT COUNT(orders.*, 0, 30, days)>0 "
         "FOR users.user_id=1")
result = rfm.predict(query)

print(result)  # Expected output format: user_id  COUNT(transactions.*, 0, 30, days) > 0
               #                          1        0.85

```

--------------------------------

### Inspect Source Table Data and Columns

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Demonstrates how to inspect the raw data and schema of a connected source table. Uses .head() to view a sample of the data as a DataFrame and checks the number of columns.

```python
print(customer_src.head())
# >>
#     CustomerID
# 428    16909.0
# 312    14002.0
# 306    17101.0
# 141    13385.0
# 273    14390.0

print(len(transaction_src.columns))
# >> 8
```

--------------------------------

### Creating Kumo Tables from Source Tables

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Illustrates how to create Kumo `Table` objects from source tables using `Table.from_source_table()`. This method allows specifying primary keys and time columns, and `infer_metadata()` can be used to automatically determine data types and semantic types.

```python
# NOTE if `columns` is not specified, all source columns are included:
customer = kumo.Table.from_source_table(
    source_table=customer_src,
    primary_key='CustomerID',
).infer_metadata()

transaction = kumo.Table.from_source_table(
    source_table=transaction_src,
    time_column='InvoiceDate',
).infer_metadata()
```

--------------------------------

### Train a Model using Kumo SDK

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Trains a Kumo model based on a predictive query. It involves suggesting a model plan, creating a trainer, and fitting the model using a graph and a generated training table. The `fit()` method can run in a blocking or non-blocking mode.

```python
model_plan = pquery.suggest_model_plan()
trainer = kumo.Trainer(model_plan)
training_job = trainer.fit(
    graph=graph,
    train_table=pquery.generate_training_table(non_blocking=True),
    non_blocking=False,
)
print(f"Training metrics: {training_job.metrics()}")
```

--------------------------------

### Initialize Kumo SDK with Free Trial API Key

Source: https://kumo-ai.github.io/kumo-sdk/docs/install/key_management

Initializes the Kumo SDK by establishing a connection to the Kumo platform using the provided URL and API key for Free Trial environments. This method is essential for verifying the API key's validity and enabling SDK communication.

```python
import kumoai as kumo
kumo.init(url="https://<environment_id>.trial.kumoai.cloud/api", api_key="<api_key>")
```

--------------------------------

### Create S3 Connector and Access Tables

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Creates a connector to an S3 data source and demonstrates accessing tables within it. Supports accessing tables by dictionary-style indexing or using the .table() method. Only S3Connector is supported for Snowpark Container Services edition.

```python
connector = kumo.S3Connector(root_dir="s3://kumo-public-datasets/customerltv_mini/")

# Access the 'customer' table by indexing into the connector:
customer_src = connector['customer']

# Access the 'transaction' table by explicitly calling the .table
# method on the connector:
transaction_src = connector.table('transaction')

# Create a connector without a root directory, and obtain a table by
# passing the full table path:
stock_src = kumo.S3Connector().table('s3://kumo-public-datasets/customerltv_mini/stock')
```

--------------------------------

### NAStrategy.startswith()

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.encoder.NAStrategy

The startswith() method checks if the string starts with a specified prefix.

```APIDOC
## NAStrategy.startswith()

### Description
The `startswith()` method checks if the string starts with a specified prefix.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### NAStrategy.rsplit()

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.encoder.NAStrategy

The rsplit() method splits the string into a list of substrings, starting from the right.

```APIDOC
## NAStrategy.rsplit()

### Description
The `rsplit()` method splits the string into substrings, starting from the right.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Initialize and Use S3Connector

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.S3Connector

Demonstrates how to initialize an S3Connector with a root directory, list available tables, check for table existence, and retrieve a specific source table. This requires the 'kumoai' library and a valid S3 path.

```python
import kumoai
connector = kumoai.S3Connector(root_dir="s3://...")  # an S3 path.

# List all tables:
print(connector.table_names())  # Returns: ['articles', 'customers', 'users']

# Check whether a table is present:
assert "articles" in connector

# Fetch a source table (both approaches are equivalent):
source_table = connector["articles"]
source_table = connector.table("articles")
```

--------------------------------

### Initialize DatabricksConnector and List Tables

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.DatabricksConnector

Demonstrates how to initialize a DatabricksConnector with connection details and credentials. It also shows how to list all available table names using the `table_names()` method.

```python
import kumoai

# Either pass `credentials=dict(client_id=..., client_secret=...,
token=...)` or set the 'DATABRICKS_CLIENT_ID' and
'DATABRICKS_CLIENT_SECRET' (or 'DATABRICKS_TOKEN') environment
variables:
connector = kumoai.connector.DatabricksConnector(
    name="<connector_name>",
    host="<databricks_host_name>",
    cluster_id="<databricks_cluster_id>",
    warehouse_id="<databricks_warehouse_id>",
    catalog="<databricks_catalog_name>",
    credentials=credentials,
)

# List all tables:
print(connector.table_names())
```

--------------------------------

### KumoRFM Get Train Table

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.experimental.rfm.KumoRFM

Retrieves the training data table used by the KumoRFM model.

```APIDOC
## KumoRFM.get_train_table()

### Description
Retrieves the training data table used by the KumoRFM model. This can be useful for understanding the data the model was trained on.

### Method
GET

### Endpoint
/kumoai/experimental/rfm/KumoRFM/get_train_table

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **train_table** (list of objects) - The training data table, where each object represents a row.

#### Response Example
```json
{
  "train_table": [
    {
      "entity_id": "user1",
      "recency": 30,
      "frequency": 10,
      "monetary": 1000.00
    }
  ]
}
```
```

--------------------------------

### Initialize BigQueryConnector in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.BigQueryConnector

Demonstrates how to initialize the BigQueryConnector by providing project and dataset IDs, along with credentials or by setting environment variables. It also shows basic usage like listing table names and accessing a specific table.

```python
import kumoai

# Either pass `credentials=dict(private_key_id=..., private_key=...,
# client_id=..., client_email=..., token_uri=..., auth_url=...)` or set
# the aforementioned environment variables:
connector = kumoai.BigQueryConnector(
    name="<connector_name>",
    project_id="<bigquery_project_id>",
    dataset_id="<bigquery_dataset_id>",
    credentials=credentials,
)

# List all tables:
print(connector.table_names())

# Check whether a table is present:
assert "articles" in connector

# Fetch a source table (both approaches are equivalent):
source_table = connector["articles"]
source_table = connector.table("articles")

```

--------------------------------

### Get Number of Rows

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/experimental/rfm/backend/local/table

Returns the number of rows in the underlying pandas DataFrame.

```python
def _get_num_rows(self) -> Optional[int]:
    return len(self._data)
```

--------------------------------

### Initialize and Use TrainingTable in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.pquery.TrainingTable

Demonstrates initializing a TrainingTable from a job ID, retrieving its data as a Pandas DataFrame or URLs, and exporting it. It also shows how to update the table with modifications, such as adding a weight column.

```python
import kumoai

# Create a Training Table from a training table generation job. Note
# that the job ID passed here must be in a completed state:
training_table = kumoai.TrainingTable("gen-traintable-job-...")

# Read the training table as a Pandas DataFrame:
training_df = training_table.data_df()

# Get URLs to download the training table:
training_download_urls = training_table.data_urls()

# Add weight column to the training table:
# see `kumo-sdk.examples.datasets.weighted_train_table.py`
# for a more detailed example
# 1. Export train table
connector = kumo.S3Connector("s3_path")
training_table.export(TrainingTableExportConfig(
    output_types={'training_table'},
    output_connector=connector,
    output_table_name="<any_name>"))
# 2. Assume the weight column was added to the train table
# and it was saved to the same S3 path as "<mod_name>"
training_table.update(SourceTable("<mod_table>", connector),
                      TrainingTableSpec(weight_col="weight"))

```

--------------------------------

### Get Sample DataFrame

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/experimental/rfm/backend/local/table

Returns the underlying pandas DataFrame associated with the LocalTable instance.

```python
def _get_sample_df(self) -> pd.DataFrame:
    return self._data
```

--------------------------------

### Initialize SnowflakeConnector and Interact with Tables (Python)

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.connector.SnowflakeConnector

Demonstrates how to initialize a SnowflakeConnector with various parameters, including authentication. It also shows how to list table names, check for table existence, and fetch a specific source table.

```python
import kumoai

# Either pass `credentials=dict(user=..., password=...)` or set the
# 'SNOWFLAKE_USER' and 'SNOWFLAKE_PASSWORD' environment variables:
connector = kumoai.SnowflakeConnector(
    name="<connector_name>",
    account="<snowflake_account_name>",
    database="<snowflake_database_name>"
    schema_name="<snowflake_schema_name>",
    credentials=credentials,
)

# List all tables:
print(connector.table_names())

# Check whether a table is present:
assert "articles" in connector

# Fetch a source table (both approaches are equivalent):
source_table = connector["articles"]
source_table = connector.table("articles")

```

--------------------------------

### Get Job Status

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/trainer/job

Retrieves the status of a running batch prediction job.

```APIDOC
## GET /jobs/{job_id}/status

### Description
Returns the status of a running batch prediction job.

### Method
GET

### Endpoint
/jobs/{job_id}/status

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the batch prediction job.

### Response
#### Success Response (200)
- **JobStatusReport** (object) - An object containing the job status report.
  - **status** (string) - The current status of the job (e.g., PENDING, RUNNING, DONE, FAILED).
  - **validation_response** (object) - Details about validation if the job failed.
    - **message** (string) - A message describing the validation error.

#### Response Example
```json
{
  "status": "RUNNING",
  "validation_response": null
}
```
```

--------------------------------

### Get Batch Prediction Job

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/trainer/job

Retrieves a batch prediction job resource by its ID.

```APIDOC
## GET /batch_prediction_jobs/{job_id}

### Description
Retrieves a batch prediction job resource by its ID.

### Method
GET

### Endpoint
/batch_prediction_jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the batch prediction job.

### Response
#### Success Response (200)
- **BatchPredictionJobResource** (object) - The batch prediction job resource.
  - **job_id** (string) - The unique identifier of the job.
  - **job_status_report** (object) - The status report of the job.
    - **status** (string) - The current status of the job.
    - **validation_response** (object) - Validation details if applicable.

#### Response Example
```json
{
  "job_id": "job-abc",
  "job_status_report": {
    "status": "DONE",
    "validation_response": null
  }
}
```
```

--------------------------------

### Create and Configure kumoai.graph.Table

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.graph.Table

Demonstrates how to create a kumoai.graph.Table either by directly constructing it with specified columns and primary keys, or by using the convenience method `from_source_table()`. It also shows how to infer missing metadata from the source table and validate the table configuration for downstream use in Kumo models.

```python
import kumoai

# Define connector to source data:
connector = kumoai.S3Connector('s3://...')

# Create table using `from_source_table`:
customer = kumoai.Table.from_source_table(
    source_table=connector['customer'],
    primary_key='CustomerID',
)

# Create a table by constructing it directly:
customer = kumoai.Table(
    source_table=connector['customer'],
    columns=[kumoai.Column(name='CustomerID', dtype='string', stype='ID')],
    primary_key='CustomerID',
)

# Infer any missing metadata in the table, from source table
# properties:
print("Current metadata: ", customer.metadata)
customer.infer_metadata()

# Validate the table configuration, for use in Kumo downstream models:
customer.validate(verbose=True)

# Fetch statistics from a snapshot of this table (this method will

```

--------------------------------

### Get Prediction Progress

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/trainer/job

Retrieves the progress of an ongoing or completed batch prediction job.

```APIDOC
## GET /jobs/{job_id}/progress

### Description
Returns the progress of an ongoing or completed batch prediction job.

### Method
GET

### Endpoint
/jobs/{job_id}/progress

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the batch prediction job.

### Response
#### Success Response (200)
- **PredictionProgress** (object) - An object containing details about the prediction progress.
  - **total_iterations** (integer) - The total number of iterations for the prediction.
  - **completed_iterations** (integer) - The number of completed iterations.

#### Response Example
```json
{
  "total_iterations": 1000,
  "completed_iterations": 500
}
```
```

--------------------------------

### Table Class Initialization and Usage in Kumo

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/graph/table

Demonstrates how to initialize and use the kumoai.graph.Table class. This includes creating tables from source tables, directly defining columns, inferring metadata, validating table configurations, and fetching statistics from table snapshots. It highlights the relationship between kumoai.Table, kumoai.connector.SourceTable, and kumoai.graph.Column.

```python
import kumoai

# Define connector to source data:
connector = kumoai.S3Connector('s3://...')

# Create table using `from_source_table`:
customer = kumoai.Table.from_source_table(
    source_table=connector['customer'],
    primary_key='CustomerID',
)

# Create a table by constructing it directly:
customer = kumoai.Table(
    source_table=connector['customer'],
    columns=[kumoai.Column(name='CustomerID', dtype='string', stype='ID')],
    primary_key='CustomerID',
)

# Infer any missing metadata in the table, from source table
# properties:
print("Current metadata: ", customer.metadata)
customer.infer_metadata()

# Validate the table configuration, for use in Kumo downstream models:
customer.validate(verbose=True)

# Fetch statistics from a snapshot of this table (this method will
# take a table snapshot, and as a result may have high latency):
customer.get_stats(wait_for="minimal")
```

--------------------------------

### Data Collection and Logging in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/experimental/rfm/rfm

This Python code snippet collects and logs test and in-context examples, handling different task types like binary classification, multiclass classification, regression, and temporal link prediction. It calculates statistics such as the number of positive cases or the range of target values, providing insights into the collected data. The code logs messages to provide context on collected examples.

```python
if logger is not None:
    if task_type == TaskType.BINARY_CLASSIFICATION:
        pos = 100 * int((y_train > 0).sum()) / len(y_train)
        msg = (f"Collected {len(y_train):,} in-context examples with "
               f"{pos:.2f}% positive cases")
    elif task_type == TaskType.MULTICLASS_CLASSIFICATION:
        msg = (f"Collected {len(y_train):,} in-context examples "
               f"holding {y_train.nunique()} classes")
    elif task_type == TaskType.REGRESSION:
        _min, _max = float(y_train.min()), float(y_train.max())
        msg = (f"Collected {len(y_train):,} in-context examples with "
               f"targets between {format_value(_min)} and "
               f"{format_value(_max)}")
    elif task_type == TaskType.TEMPORAL_LINK_PREDICTION:
        num_rhs = y_train.explode().nunique()
        msg = (f"Collected {len(y_train):,} in-context examples with "
               f"{num_rhs:,} unique items")
    else:
        raise NotImplementedError
    logger.log(msg)

msg = (f"Collected {len(y_test):,} test examples with "
       f"{num_rhs:,} unique items")
logger.log(msg)
```

--------------------------------

### Initialize and Use TrainingJobResult in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.trainer.TrainingJobResult

Demonstrates how to create a TrainingJobResult object, either by awaiting the completion of a TrainingJob or by directly instantiating it. It also shows how to access associated objects like predictive_query and training_table, and retrieve holdout data.

```python
import kumoai

training_job = kumoai.TrainingJob("trainingjob-...")

# Wait for a training job's completion, and get its result:
training_job_result = training_job.result()

# Alternatively, create the result directly, but be sure that the job
# is completed:
training_job_result = kumoai.TrainingJobResult("trainingjob-...")

# Get associated objects:
pquery = training_job_result.predictive_query
training_table = training_job_result.training_table

# Get holdout data:
holdout_df = training_job_result.holdout_df()

```

--------------------------------

### Batch Prediction with KumoRFM using Context Manager in Python

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.experimental.rfm.KumoRFM

Illustrates how to perform predictions in batches using the `batch_mode` context manager provided by the KumoRFM class. This is useful for optimizing performance when making multiple predictions. The example shows setting a batch size and the number of retries within the `with` statement.

```python
with model.batch_mode(batch_size='max', num_retries=1):
    df = model.predict(query, indices=...)

```

--------------------------------

### Get All Columns from Table (Python)

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/graph/table

Returns a list of all Column objects present in the table. This provides a comprehensive view of the table's structure.

```python
@property
def columns(self) -> List[Column]:
    r"""Returns a list of :class:`~kumoai.Column` objects that represent
    the columns in this table.
    """
    return list(self._columns.values())
```

--------------------------------

### GET /predictive_query/suggest_model_plan

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.pquery.PredictiveQuery

Suggests a modeling plan given the predictive query and graph. This plan can alter how Kumo trains your machine learning model.

```APIDOC
## GET /predictive_query/suggest_model_plan

### Description
Suggests a modeling plan given the predictive query and graph. This plan can alter how Kumo trains your machine learning model.

### Method
GET

### Endpoint
/predictive_query/suggest_model_plan

### Parameters
#### Query Parameters
- **run_mode** (RunMode) - Optional - A representation of how quickly you would like your predictive query to complete. Faster run modes correspond to lower training times, at the cost of potentially lower performance.
- **train_table_spec** (Optional[TrainingTableSpec]) - Optional - Needed if the original train table has been modified by adding a weight column.

### Response
#### Success Response (200)
- **ModelPlan** - The suggested plan for model training.

#### Response Example
```json
{
  "model_plan": { ... } 
}
```
```

--------------------------------

### Initialize Snowflake Connector

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/connector/snowflake_connector

Demonstrates how to initialize a SnowflakeConnector object. It shows how to specify connection details such as name, account, database, schema, and credentials. The example highlights using either direct credential dictionary or environment variables for authentication.

```python
import kumoai

# Example using credentials dictionary
credentials = {
    "user": "<your_snowflake_user>",
    "password": "<your_snowflake_password>"
}
connector = kumoai.SnowflakeConnector(
    name="<connector_name>",
    account="<snowflake_account_name>",
    database="<snowflake_database_name>",
    schema_name="<snowflake_schema_name>",
    credentials=credentials,
)

# Example using environment variables (SNOWFLAKE_USER, SNOWFLAKE_PASSWORD)
# Ensure these environment variables are set before running.
# connector = kumoai.SnowflakeConnector(
#     name="<connector_name>",
#     account="<snowflake_account_name>",
#     database="<snowflake_database_name>",
#     schema_name="<snowflake_schema_name>"
# )

```

--------------------------------

### BatchPredictionJobResult - Get Embeddings

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.trainer.BatchPredictionJobResult

Retrieves URLs for downloading or reading embedding results. The format of the URLs depends on the Kumo deployment environment (SaaS, Snowpark, Databricks).

```APIDOC
## GET /websites/kumo-ai_github_io_kumo-sdk/embeddings/urls

### Description
Retrieves a list of URLs for downloading or reading the embeddings. The URL format varies based on the Kumo deployment environment (SaaS, Snowpark, Databricks).

### Method
GET

### Endpoint
/websites/kumo-ai_github_io_kumo-sdk/embeddings/urls

### Parameters
None

### Response
#### Success Response (200)
- **List[str]** - A list of URLs or stage paths for accessing embedding data.

#### Response Example
```json
[
  "s3://kumo-embeddings/job123/part1.vec",
  "s3://kumo-embeddings/job123/part2.vec"
]
```
```

--------------------------------

### BatchPredictionJobResult - Get Predictions

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.trainer.BatchPredictionJobResult

Retrieves URLs for downloading or reading prediction results. The format of the URLs depends on the Kumo deployment environment (SaaS, Snowpark, Databricks).

```APIDOC
## GET /websites/kumo-ai_github_io_kumo-sdk/predictions/urls

### Description
Retrieves a list of URLs for downloading or reading the predictions. The URL format varies based on the Kumo deployment environment (SaaS, Snowpark, Databricks).

### Method
GET

### Endpoint
/websites/kumo-ai_github_io_kumo-sdk/predictions/urls

### Parameters
None

### Response
#### Success Response (200)
- **List[str]** - A list of URLs or stage paths for accessing prediction data.

#### Response Example
```json
[
  "s3://kumo-predictions/job123/part1.csv",
  "s3://kumo-predictions/job123/part2.csv"
]
```
```

--------------------------------

### KumoRFM Initialization

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.experimental.rfm.KumoRFM

Initializes the KumoRFM class.

```APIDOC
## KumoRFM.__init__()

### Description
Initializes the KumoRFM class.

### Method
GET

### Endpoint
/kumoai/experimental/rfm/KumoRFM

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **instance** (KumoRFM) - An initialized instance of the KumoRFM class.

#### Response Example
```json
{
  "instance": "<KumoRFM object>"
}
```
```

--------------------------------

### Create Kumo Tables from Source Tables

Source: https://kumo-ai.github.io/kumo-sdk/docs/get_started/introduction

Creates Kumo `Table` objects from source tables, specifying primary keys and time columns. The `infer_metadata()` method helps in automatically detecting data types and other schema details, which is crucial for model training.

```python
# Create Tables from SourceTables:
customer = kumo.Table.from_source_table(
    source_table=connector.table('customer'),
    primary_key='CustomerID,
).infer_metadata()

stock = kumo.Table.from_source_table(
    source_table=connector.table('stock'),
    primary_key='StockCode,
).infer_metadata()

transaction = kumo.Table.from_source_table(
    source_table=connector.table('transaction'),
    time_column='InvoiceDate',
).infer_metadata()
```

--------------------------------

### Get Graph Edge Statistics

Source: https://kumo-ai.github.io/kumo-sdk/docs/generated/kumoai.graph.Graph

Retrieves statistics for edges within a graph. The `non_blocking` parameter controls whether the operation waits for completion. It takes a boolean value.

```python
graph.get_edge_stats(non_blocking=False)
```

--------------------------------

### Create and Initialize SourceTable

Source: https://kumo-ai.github.io/kumo-sdk/docs/_modules/kumoai/connector/source_table

This code demonstrates the initialization of a SourceTable object, which involves retrieving connector configurations and setting up the table name. It handles different connector types, specifically mentioning Glue connectors, and raises an error for unsupported types.

```python
            connector = GlueConnector(
                name=connector_cfg.name,
                account=connector_cfg.account,
                region=connector_cfg.region,
                database=connector_cfg.database,
                _bypass_creation=True,
            )
            table_name = table_definition.source_table.table
        else:
            raise NotImplementedError()

        return SourceTable(table_name, connector)
```
Tokens:
Raw