> This page is for Kumo Engine.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.

# Lead Scoring Optimization

Lead scoring ranks leads by their probability of conversion so sales teams can prioritize outreach.
A marketing team can generate thousands of leads a day, while a sales team can contact only a fraction of them.

This example uses Kumo Engine to predict whether a recently-engaged lead will convert in the coming weeks, estimate conversion conditional on recorded sales outreach in the next seven days, and estimate expected revenue to prioritize by value as well as probability.
Kumo Engine learns from each lead's profile and the campaign responses and interactions connected to that lead in the graph.

## Data and relationships

The example assumes a prepared Kumo Engine `graph`, a matching `snapshot`, and these tables:

![Lead scoring schema with triggers and events linked to leads through lead\_id, timestamp time columns on triggers and events, and optional industry and title profile columns on leads.](/sdgm/_fern-files/nvidia-sdgm.docs.buildwithfern.com/2585a4bd5bf8b578cf0ed196cc88175424e60019fe55534661446b5de0119fe7/_dot_dot_/images/diagrams/workflow-lead-scoring-optimization-schema.svg)

| Table      | Required columns                                                                           | Purpose                                                                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `leads`    | `lead_id` as the primary key, plus optional profile columns such as `industry` and `title` | The leads, and the entity every query scores.                                                                                                                                                                                                            |
| `triggers` | `trigger_id` as the primary key, plus `lead_id` and `timestamp`                            | The campaign-response log. Each row is one time a lead responded to a marketing campaign, used to keep the prediction on leads that recently engaged.                                                                                                    |
| `events`   | `event_id` as the primary key, plus `lead_id`, `timestamp`, `event_type`, and `value`      | The interaction log. Each row is one action tied to a lead, and `event_type` names the action, for example `email_open`, `click`, `meeting`, `sales_touch`, or `conversion`. `value` carries the deal amount on a `conversion` row and is `0` otherwise. |

The time columns ensure that training and scoring use only history recorded before the prediction's reference time.
The `leads` table is a static entity: each forward-looking window starts at the scoring time, when you run the prediction, rather than at a time on the lead row.

Every query predicts a future window for a restricted set of leads.
The target counts or sums a lead's conversions over the days following the scoring time.

The trailing `WHERE COUNT(triggers.*, -7, 0, days) > 0` selects leads that responded to a campaign in the previous week, excluding cold leads with no recent engagement from the call list.
The forward window is half-open: it excludes actions at the exact scoring time and includes actions through the end of the window.

## Predict which recently-engaged leads will convert

This query predicts whether a recently-engaged lead will convert.
`COUNT(events.* WHERE events.event_type = 'conversion', 0, 30, days)` counts a lead's conversion events over the 30 days following the scoring time.
`> 0` makes at least one conversion a positive label.

The trailing `WHERE COUNT(triggers.*, -7, 0, days) > 0` selects leads that responded to a campaign in the previous 7 days, focusing the ranking on recently-engaged leads rather than dormant records.

```python
from kumo.engine import PredictiveQuery

query_text = (
    "PREDICT COUNT(events.* WHERE events.event_type = 'conversion', 0, 30, days) > 0 "
    "FOR EACH leads.lead_id "
    "WHERE COUNT(triggers.*, -7, 0, days) > 0"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # binary_classification
```

## Score conversion conditional on sales outreach

This query uses the same 30-day conversion target, conditional on a recorded sales touch in the next seven days.
`ASSUMING COUNT(events.* WHERE events.event_type = 'sales_touch', 0, 7, days) > 0` restricts training to historical lead and scoring-time pairs with that outreach in the following week.
The recent campaign-response requirement still applies.

Use this scenario to learn from conversion outcomes in that observed outreach subset.
Conditioning on recorded outreach does not remove selection bias or establish how much contacting a lead changes its chance of conversion.

```python
query_text = (
    "PREDICT COUNT(events.* WHERE events.event_type = 'conversion', 0, 30, days) > 0 "
    "FOR EACH leads.lead_id "
    "WHERE COUNT(triggers.*, -7, 0, days) > 0 "
    "ASSUMING COUNT(events.* WHERE events.event_type = 'sales_touch', 0, 7, days) > 0"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # binary_classification
```

## Rank leads by the revenue they are likely to bring

A likely small conversion may be less valuable than a less likely large deal.
This query predicts revenue instead of a binary conversion label.

`SUM(events.value WHERE events.event_type = 'conversion', 0, 30, days)` sums a lead's conversion deal amounts over the next 30 days to estimate expected revenue.
A lead with no conversion in the window contributes `0`, and the same trailing `WHERE` restricts predictions to recently-engaged leads.

```python
query_text = (
    "PREDICT SUM(events.value WHERE events.event_type = 'conversion', 0, 30, days) "
    "FOR EACH leads.lead_id "
    "WHERE COUNT(triggers.*, -7, 0, days) > 0"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # regression
```

## Reading the predictions

The first query returns a conversion probability for each recently-engaged lead in the coming weeks, which a sales team can use to rank its daily call list.

The second estimates conversion conditional on recorded sales outreach, using only historical windows that satisfy the outreach condition for training.
Its scores reflect that selected history; they do not measure the additional conversions caused by a call.

The third query returns expected revenue for each lead, allowing teams to compare likely small deals with less certain large ones and prioritize by value.

All three predictions are estimates from past behavior, not guarantees.
Each is anchored at the time you run it and uses only history recorded before that moment, excluding the outcome it predicts.

The 30-day forward window, the 7-day recent-response window, and the 7-day outreach window are starting points; widen or narrow the number of days to match your sales cycle and how quickly reps follow up.
Refresh the scores as new campaign responses and interactions arrive so each call list reflects the latest engagement.