🧪 Risk Scorers

Note

Risk scorers are currently in Preview. Breaking changes may occur in future releases.

Risk scorers let you continuously monitor risk by computing a numeric risk score for your evaluation metrics. A risk scorer applies a configurable risk scoring methodology function to a set of in-scope metrics, aggregates the result across the latest evaluations, and maps it to a risk level: low, medium, high, or critical.

A risk scorer depends on a risk scoring methodology: a reusable, configurable function that you register once and reference from any number of risk scorers.

Prerequisites

To use risk scorers, you need:

• An AI app with at least one evaluation you can run.
• Tasks that produce the metrics you want to set risk scorers on (for example: accuracy, hallucination, faithfulness).
• The CLI installed and configured (see Command Line Interface).

Quickstart

This quickstart sets up a risk scoring methodology and a single risk scorer that monitors a safety score from a harmful content evaluation.

1. Create a risk scoring methodology.
2. Register the risk scoring methodology.
3. Define a risk scorer.
4. Add the risk scorer.
5. Run (or re-run) your evaluations.
6. View risk scores.

1. Create a Risk Scoring Methodology

A risk scoring methodology defines a numeric scoring function with two kinds of variables: a single metric variable that receives an evaluation metric (identified by metric_key), and configurable parameters declared in config_spec that are configured per risk scorer.

Create a file called safety_risk_scoring_methodology.yaml:

key: "safety_risk_scoring_methodology"
display_name: "Safety Risk Scoring Methodology"
description: "Maps the safety score metric to a 0–10 risk score."
function: "impact * (1 - safety_score)"
metric_key: "safety_score"
config_spec:
  - type: float
    key: "impact"
    display_name: "Impact"
    default_value: 5.0
    min: 0.0
    max: 10.0

The function field is a Python-like math expression. The variable named by metric_key (safety_score here) receives the metric value from the evaluation run, while the other variables in the function (here impact) are configurable parameters of the risk scoring methodology.

2. Register the Risk Scoring Methodology

$ lf add risk-scoring-methodology -f safety_risk_scoring_methodology.yaml

Note

lf add risk-scoring-methodology creates the methodology if it does not exist yet, or updates it if the key already exists. You can also pass a directory or glob pattern to register multiple methodologies at once.

3. Define a Risk Scorer

Create a file called risk_scorers.yaml:

risk_scorers:
  - key: "harmful_content"
    display_name: "Harmful Content Risk Scorer"
    description: >
      Tracks the risk of harmful or unsafe content generation across categories including
      violent crimes, hate speech, privacy violations, and cybercrime, using AILuminate
      safety scores.
    domain: "safety_and_reputational_harm"
    risk_scoring_methodology_key: "safety_risk_scoring_methodology"
    scope:
      evaluation_keys: ["atlas-harmful_content"]
    config:
      impact: 7.0
    metric: "safety_score"
    aggregation: "mean"

4. Add the Risk Scorers

$ lf add risk-scorer -f risk_scorers.yaml

This creates or updates the risk scorers defined in the file. Risk scorers that already exist but are not in the file are left untouched — use lf delete risk-scorer <key> to remove one.

5. Run Evaluations

$ lf init eval --key atlas-harmful_content
# Add datasets
lf add -f atlas-harmful_content/run.yaml
# Run evaluation
lf run eval -k atlas-harmful_content -c atlas-harmful_content/config.yaml

6. View Risk Scores

$ lf overview risk-scorers

Example output:

                              Risk Scorer Status (4 rows)
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ Key                     ┃ Name                                   ┃ Score  ┃ Level   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
│ harmful_content         │ Harmful Content Risk Scorer            │ 7.50   │ high    │
└─────────────────────────┴────────────────────────────────────────┴────────┴─────────┘

Note

For JSON output, use lf overview risk-scorers --json. To view a specific risk scorer, use lf overview risk-scorers --key <risk-scorer-key>.

Defining Risk Scoring Methodologies

Methodology Function

The function field is a math expression using named variables:

• The variable referenced by metric_key receives the metric value from the evaluation.
• Any other variable in the expression must be declared in config_spec (see Methodology Parameters below).

Design the function so the result falls in the 0–10 range. This ensures the output maps meaningfully to the four risk levels (see Risk Score Levels below).

Examples:

# Scale a 0–1 metric to 0–10
function: "10 * failure_rate"
metric_key: "failure_rate"

# Weighted: multiply by a configurable severity factor
function: "severity * failure_rate"
metric_key: "failure_rate"

Methodology Parameters

Use config_spec to declare parameters that the function references (other than metric_key). Supported types: float, int, categorical. Note that all variables must be numeric, so if you define a categorial parameter, make sure to include the values_mapping field to map the categorical values to numeric values.

key: "weighted_failure_rate"
display_name: "Weighted Failure Rate"
function: "severity * exposure * failure_rate"
metric_key: "failure_rate"
config_spec:
  - type: "float"
    key: "severity"
    display_name: "Severity"
    description: "Weight applied to the failure rate score."
    default_value: 5.0
  - type: "categorical"
    key: "exposure"
    display_name: "Deployment Exposure"
    description: "Whether the system is user-facing or internal. External deployments amplify the score."
    allowed_values:
      - "internal"
      - "external"
    default_value: "external"
    values_mapping:
      internal: 0.5
      external: 1.0

The risk scorer then configures those parameters via its config field:

risk_scorers:
  - key: "critical_service_risk"
    display_name: "Critical Service Risk"
    risk_scoring_methodology_key: "weighted_failure_rate"
    metric: "failure_rate"
    aggregation: "mean"
    domain: "performance_and_reliability"
    config:
      severity: 9.0
      exposure: "external"
    scope: "all_latest"

Defining Risk Scorers

Risk Scorer Scope

Each risk scorer must define a scope, which controls which metric values the risk scorer considers. Two types are supported.

Metrics from all latest evaluations

scope: "all_latest"

Applies the risk scorer to metrics from the latest run of each evaluation. If you ran multiple evaluations with the same key, only the latest one is considered.

Custom scope

Use a fine-grained scope when you want a risk scorer to apply only to specific evaluations, tasks, scorers, or metrics:

scope:
  evaluation_keys: ["rag_eval_v1", "safety_eval_v2"]
  task_specification_keys: ["rag_performance"]
  scorer_keys: ["rag_checker"]
  metric_keys: ["failure_rate"]

All specified filters are ANDed together; omit any filter to leave it unconstrained. If you ran multiple evaluations with the same key, only the latest is considered.

Aggregation

When a risk scorer matches multiple data points, aggregation controls how the individual risk scores are combined into the final risk score:

Value	Behaviour
mean	Average across all matched metric values
max	Worst-case: the highest individual score
min	Best-case: the lowest individual score

Risk Score Levels

The final aggregated risk score is mapped to a level based on fixed thresholds:

Level	Score range
low	0 – 2.0
medium	2.0 – 4.0
high	4.0 – 9.0
critical	above 9.0

Manage Risk Scorers

To list all registered risk scorers:

$ lf list risk-scorer

To delete a risk scorer:

$ lf delete risk-scorer <key>

Manage Risk Scoring Methodologies

To list all registered risk scoring methodologies:

$ lf list risk-scoring-methodology

To delete a risk scoring methodology:

$ lf delete risk-scoring-methodology <key>

Practical Tips

• Design methodology functions so results fall in the 0–10 range. Multiplying a 0–1 metric by 10 maps cleanly to the risk level thresholds.
• Use aggregation: "max" when a single failing evaluation run should raise the overall risk level.
• Use a fine-grained scope to exclude experimental evaluations from production risk tracking.
• Reuse a single risk scoring methodology across multiple risk scorers by referencing the same risk_scoring_methodology_key with different metric or config values.
• Use lf overview risk-scorers --json to integrate risk scores into CI pipelines or dashboards.
• Iterate: define risk scorers after you have seen the metrics your evaluations produce.