[FEATURE] Add configurable Trust Score policy profiles

[Khanz9664]

Overview

TrustLens currently applies a single, uniform scoring configuration across all deployment contexts — the same calibration penalties, failure penalties, fairness thresholds, and deployment blocking logic regardless of whether the model is powering an ad recommendation engine or a clinical diagnostic system.

This is a fundamental mismatch with real-world ML deployment. Risk tolerance is not one-size-fits-all.

---

Problem

Today, analyze() produces a deterministic Trust Score with no concept of deployment context:

# Both of these use identical scoring logic — that's wrong
analyze(model=ad_ranker, ...)       # low-stakes
analyze(model=cancer_classifier, ...)  # high-stakes

This affects:

• Calibration penalties — same weight regardless of consequence
• Failure penalties — no concept of severity tolerance
• Fairness thresholds — identical cutoffs for all domains
• Deployment blocking — single gate for all risk levels

---

Proposed Solution: Policy Profiles

Introduce a policy parameter to analyze() that selects a named scoring profile from a centralized registry.

report = analyze(
    model=model,
    X=X_test,
    y_true=y_test,
    y_prob=y_prob,
    policy="strict"  # 👈 new
)

Supported Profiles

Profile	Use Case	Behavior
"balanced" (default)	General purpose	Current TrustLens behavior — no breaking changes
"strict"	Healthcare, finance, safety-critical	Stronger failure penalties · lower fairness tolerance · calibration penalized harder · deployment block triggers easier
"pragmatic"	Low-risk systems, prototyping	Softer penalties · higher tolerance margins · relaxed deployment gate

---

Architecture

Avoid scattered conditionals. Use a centralized policy registry:

POLICY_PROFILES = {
    "balanced": {
        "calibration_penalty_weight": 1.0,
        "failure_penalty_weight": 1.0,
        "fairness_threshold": 0.15,
        "deployment_block_threshold": 0.5,
    },
    "strict": {
        "calibration_penalty_weight": 1.5,
        "failure_penalty_weight": 2.0,
        "fairness_threshold": 0.08,
        "deployment_block_threshold": 0.65,
    },
    "lenient": {
        "calibration_penalty_weight": 0.7,
        "failure_penalty_weight": 0.6,
        "fairness_threshold": 0.25,
        "deployment_block_threshold": 0.35,
    },
}

The scoring engine reads from the active profile config — no hardcoded logic per profile.

---

API & Report Changes

TrustReport should expose the active policy:

report.policy
# "strict"

Report metadata output:

{
  "trust_score": 0.61,
  "policy": "strict",
  "deployment_recommended": false
}

Scoring explanations should reference the active profile:

Calibration penalty applied at 1.5× weight under strict policy.

---

Requirements

• policy parameter added to analyze() — default "balanced"
• POLICY_PROFILES registry implemented as centralized config
• Scoring engine reads weights/thresholds from active profile
• TrustReport exposes .policy attribute
• Report JSON/dict includes "policy" field
• Scoring explanations reference active profile by name
• 100% backward compatible — existing calls unchanged
• Tests for all three profiles
• Docs updated with profile descriptions and usage examples

---

Future: Custom Policies

Out of scope for this issue, but the architecture should leave room for:

analyze(
    model=model,
    ...,
    policy_config={
        "calibration_penalty_weight": 1.8,
        "fairness_threshold": 0.05,
    }
)

This would allow fully user-defined profiles without hardcoding into the registry.

---

Why This Matters

A model that clears TrustLens in one domain may be completely unacceptable in another — not because the model changed, but because the stakes changed. TrustLens should reflect that reality.

Policy profiles let teams codify their reliability standards in one place, making trust evaluation a first-class part of deployment configuration — not an afterthought.