> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Try Something New

## Solution Background and Business Value

Personalized **try-something-new** recommendations introduce customers to products they haven't purchased before but are likely to enjoy based on their buying habits and preferences. This strategy enhances customer experience by encouraging product discovery while also expanding sales into new product categories.

By integrating these recommendations into **push notifications, in-product placements, and email campaigns**, businesses can:

* **Drive cross-selling opportunities** by exposing customers to new product lines.

* **Enhance customer satisfaction** by keeping the shopping experience fresh.

* **Increase engagement and retention** by offering relevant and timely suggestions.

This proactive approach helps businesses **maintain a competitive edge** by increasing customer interaction and maximizing revenue.

## Data Requirements and Graph Schema

To develop an effective **Try-Something-New** recommendation model, we need a structured dataset. While a small set of core tables is sufficient to start, **Kumo AI** enables us to improve the model by incorporating additional sources of data.

**Core Tables**

The **three essential tables** required for this solution are:

1. **Users Table**

   * Stores details about users for whom we want to generate recommendations.

   * **Key attributes:**

     * `user_id`: Unique identifier (Primary Key).

     * `join_timestamp`: When the user joined.

     * Other optional features: age, location, and shopping behavior.

2. **Items Table**

   * Stores information about the items available for recommendation.

   * **Key attributes:**

     * `item_id`: Unique identifier (Primary Key).

     * `start_timestamp` / `end_timestamp`: Availability period of the item.

     * Other optional features: price, category, color, and brand.

3. **Transactions Table**

   * Stores user purchase history, which the model learns from.

   * **Key attributes:**

     * `transaction_id`: Unique identifier (Primary Key).

     * `user_id`: Foreign Key linking to Users.

     * `item_id`: Foreign Key linking to Items.

     * `timestamp`: When the purchase was made.

     * Other optional features: total amount, payment method, and discount applied.

**Entity Relationship Diagram (ERD)**

```mermaid theme={null}
erDiagram
    USERS {
        INT user_id PK
        TIMESTAMP join_timestamp
        INT age
        STRING location
        STRING other_features
    }
    
    ITEMS {
        INT item_id PK
        STRING item_name
        STRING category
        TIMESTAMP start_timestamp
        TIMESTAMP end_timestamp
        FLOAT price
        STRING color
        STRING other_features
    }
    
    TRANSACTIONS {
        INT transaction_id PK
        INT user_id FK
        INT item_id FK
        TIMESTAMP timestamp
        FLOAT total_amount
        STRING payment_method
        STRING other_features
    }

    USERS ||--o{ TRANSACTIONS : "makes"
    ITEMS ||--o{ TRANSACTIONS : "includes"
```

## Predictive Query

The challenge in **try-something-new** recommendations is balancing **item similarity** and **user behavior modeling** while ensuring recommendations remain **novel** to the user. Training a model solely on new purchases would discard valuable purchasing patterns.

Instead of training on only first-time purchases, we train a **general item-to-user recommendation model** and apply **filters at prediction time** to remove items the user has already purchased. This ensures:

* The model learns **broad user-item affinity**.

* Users receive **only new product recommendations**.

```pql theme={null}
PREDICT LIST_DISTINCT(transactions.item_id, 0, X, days) RANK TOP 50
FOR EACH users.user_id
```

This query:

* Predicts **the top 50 distinct items** a user is likely to buy.

* Looks at a future **X-day window** to determine potential purchases.

**Filtering for New Recommendations**

Try-something-new recommendations are particularly effective for users who are **not highly active**, as they encourage engagement. We can filter out highly active users and only target those with **fewer than N purchases in the last D days**.

```pql theme={null}
WHERE COUNT(transactions.*, -D, 0, days) < N
```

## Building models in Kumo SDK

This solution can be efficiently implemented using **Kumo AI**, which simplifies ML modeling on relational data.

**1. Initialize the Kumo SDK**

```python theme={null}
import kumoai as kumo

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

**2. Connect data**

```python theme={null}
connector = kumo.S3Connector("s3://your-dataset-location/")
```

**3. Select tables**

```python theme={null}
users = kumo.Table.from_source_table(
    source_table=connector.table('users'),
    primary_key='user_id',
).infer_metadata()

items = kumo.Table.from_source_table(
    source_table=connector.table('items'),
    primary_key='item_id',
).infer_metadata()

transactions = kumo.Table.from_source_table(
    source_table=connector.table('transactions'),
    time_column='timestamp',
).infer_metadata()
```

**4. Create graph schema**

```python theme={null}
graph = kumo.Graph(
    tables={
        'users': users,
        'items': items,
        'transactions': transactions,
    },
    edges=[
        dict(src_table='transactions', fkey='user_id', dst_table='users'),
        dict(src_table='transactions', fkey='item_id', dst_table='items'),
    ],
)

graph.validate(verbose=True)
```

**5. Train the model**

```python theme={null}
pquery = kumo.PredictiveQuery(
    graph=graph,
    query=(
        "PREDICT LIST_DISTINCT(transactions.item_id, 0, X, days) RANK TOP 50\n"
        "FOR EACH users.user_id"
    ),
)
pquery.validate(verbose=True)

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()}")
```

**6. Run the model**

```python theme={null}
prediction_job = trainer.predict(
    graph=graph,
    prediction_table=pquery.generate_prediction_table(non_blocking=True),
    output_types={'predictions', 'embeddings'},
    output_connector=connector,
    output_table_name='try_something_new_predictions',
    training_job_id=training_job.job_id,
    non_blocking=False,
)
print(f'Batch prediction job summary: {prediction_job.summary()}')
```