sage-governance 1.0.0

package/sage/sage_agent.py

@@ -0,0 +1,710 @@
+"""
+sage_agent.py — SAGE Intent Classifier & Ethics Evaluator
+══════════════════════════════════════════════════════════
+Classifies developer intent, evaluates ethics/fairness/regulatory compliance,
+and generates structured tradeoff options.
+
+DESIGN DECISIONS
+────────────────
+1. DETERMINISTIC FIRST — domain detection, risk scoring, proxy detection,
+   and tradeoff selection are all rule-based. These never fail.
+
+2. LLM SECOND — the LLM is used ONLY to generate a human-readable reasoning
+   summary. If the LLM is unavailable or fails, a deterministic fallback
+   summary is returned. The Pydantic schema is ALWAYS satisfied.
+
+3. PYDANTIC CONTRACT — every output goes through SageEvaluateResponse.
+   The schema is the contract Roshan builds opencode.json against.
+   It cannot silently change shape.
+
+Author: SAGE Team / Team SAGE (Hackathon)
+License: MIT
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, field_validator
+
+# startup is always imported first — it pre-loads all globals
+from startup import (
+    EU_AI_ACT_ANNEX_III,
+    FAIRLEARN_AVAILABLE,
+    LLM_AVAILABLE,
+    LLM_CLIENT,
+    LLM_MODEL,
+    POLICY_INDEX,
+    PROTECTED_ATTRIBUTES,
+    PROXY_ATTRIBUTE_MAP,
+    UDHR_ARTICLE_MAP,
+)
+
+# ══════════════════════════════════════════════════════════════════════════════
+# PYDANTIC MODELS  — the immutable contract
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+class FairnessOption(BaseModel):
+    """One concrete fairness strategy with full tradeoff analysis."""
+
+    name: str
+    definition: str
+    stakeholder_view: str  # Northpointe / ProPublica / GDPR framing
+    pros: list[str]
+    cons: list[str]
+    fairlearn_api: str
+    diffprivlib_api: Optional[str] = None
+    who_benefits: str
+    tradeoff_cost: str
+    compatible_with: list[str]   # other options it can coexist with
+    incompatible_with: list[str] # Fairness Impossibility Theorem entries
+
+
+class SageEvaluateResponse(BaseModel):
+    """
+    The complete SAGE evaluation result.
+    Roshan: build opencode.json against THIS schema. It will not change shape.
+    """
+
+    risk_level: Literal["LOW", "MEDIUM", "HIGH", "CRITICAL"]
+    eu_ai_act_annex: Optional[str]
+    eu_ai_act_category: Optional[str]
+    udhr_articles: list[str]
+    protected_attributes: list[str]
+    proxy_attributes: list[str]
+    detected_domain: str
+    intent_summary: str
+    compliance_flags: list[str]
+    fairness_options: list[FairnessOption]
+    immediate_actions: list[str]
+    regulations: list[str]
+    requires_human_review: bool
+    sage_reasoning: str           # LLM-enriched or deterministic fallback
+    fairness_impossibility: bool  # True when base rates differ across groups
+
+    @field_validator("intent_summary")
+    @classmethod
+    def truncate_summary(cls, v: str) -> str:
+        return v[:300]
+
+    @field_validator("risk_level")
+    @classmethod
+    def validate_risk(cls, v: str) -> str:
+        assert v in ("LOW", "MEDIUM", "HIGH", "CRITICAL")
+        return v
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# FAIRNESS OPTION LIBRARY
+# Three frameworks from the COMPAS/SAMPLE_CASES evidence base.
+# ══════════════════════════════════════════════════════════════════════════════
+
+_FAIRNESS_LIBRARY: dict[str, FairnessOption] = {
+    "equalized_odds": FairnessOption(
+        name="Equalized Odds",
+        definition=(
+            "Equal true-positive AND false-positive rates across all groups. "
+            "The model makes equally frequent mistakes for every demographic."
+        ),
+        stakeholder_view=(
+            "ProPublica standard — 'An innocent Black defendant must not be "
+            "twice as likely to be wrongly flagged as high-risk.'"
+        ),
+        pros=[
+            "Directly addresses the ProPublica COMPAS critique",
+            "Protects individuals from being misclassified at higher rates by group",
+            "Supported natively by Fairlearn ExponentiatedGradient",
+            "Satisfies EU AI Act Article 10 non-discrimination requirements",
+        ],
+        cons=[
+            "Mathematically incompatible with Demographic Parity and Predictive Parity "
+            "when base rates differ (Fairness Impossibility Theorem)",
+            "Requires protected attributes at training time — GDPR tension",
+            "Reducing FPR for one group may increase FNR for another",
+        ],
+        fairlearn_api="fairlearn.reductions.ExponentiatedGradient(estimator, EqualizedOdds())",
+        who_benefits=(
+            "Individuals from groups incorrectly classified at higher rates "
+            "(e.g. Black defendants in COMPAS, women in credit scoring)"
+        ),
+        tradeoff_cost="Overall accuracy drop; requires demographic data collection",
+        compatible_with=[],
+        incompatible_with=["demographic_parity", "predictive_parity"],
+    ),
+
+    "demographic_parity": FairnessOption(
+        name="Demographic Parity",
+        definition=(
+            "Equal fraction of positive predictions across all groups, "
+            "regardless of ground-truth differences."
+        ),
+        stakeholder_view=(
+            "Equality-of-outcome view — 'Force proportional representation now, "
+            "because historical data cannot be trusted.'"
+        ),
+        pros=[
+            "Eliminates visible representation disparity in predictions",
+            "Simple to measure and communicate to non-technical stakeholders",
+            "No protected attributes needed at inference time",
+        ],
+        cons=[
+            "Ignores actual underlying differences in ground-truth rates",
+            "Mathematically incompatible with Equalized Odds and Predictive Parity",
+            "Can produce individually unfair outcomes (penalizes qualified individuals)",
+        ],
+        fairlearn_api="fairlearn.metrics.demographic_parity_difference(y_true, y_pred, sensitive_features=sf)",
+        who_benefits="Groups underrepresented in positive predictions at the population level",
+        tradeoff_cost="Individual fairness; overall predictive accuracy; requires base-rate trust",
+        compatible_with=[],
+        incompatible_with=["equalized_odds", "predictive_parity"],
+    ),
+
+    "predictive_parity": FairnessOption(
+        name="Predictive Parity (Calibration)",
+        definition=(
+            "Equal positive predictive value (precision) across groups — "
+            "a given score carries the same probability of the outcome for all groups."
+        ),
+        stakeholder_view=(
+            "Northpointe standard — 'If a score of 7 means 70% recidivism for "
+            "white defendants, it must mean the same for Black defendants.'"
+        ),
+        pros=[
+            "Ensures score interpretability is equal across groups",
+            "Does not require protected attributes at inference time",
+            "Defends calibration when base rates genuinely differ in the real world",
+        ],
+        cons=[
+            "Permits systematically higher false-positive rates for disadvantaged groups",
+            "Northpointe used this argument while ProPublica demonstrated concrete harm",
+            "When base rates differ, Fairness Impossibility Theorem guarantees "
+            "this metric co-exists with unequal error rates",
+        ],
+        fairlearn_api="fairlearn.metrics.MetricFrame(metrics=selection_rate, sensitive_features=sf).by_group",
+        who_benefits=(
+            "System operators who need calibrated scores; "
+            "groups with higher true base rates"
+        ),
+        tradeoff_cost="Equal error rates; protection from individual misclassification",
+        compatible_with=[],
+        incompatible_with=["equalized_odds", "demographic_parity"],
+    ),
+
+    "differential_privacy": FairnessOption(
+        name="Differential Privacy (ε-DP)",
+        definition=(
+            "Formal mathematical guarantee: adding or removing any single "
+            "training record changes model output by at most e^ε — "
+            "individual records cannot be reconstructed."
+        ),
+        stakeholder_view=(
+            "Privacy-first — 'Protect every individual in the training set "
+            "regardless of group membership.'"
+        ),
+        pros=[
+            "Provable protection against model inversion and membership inference attacks",
+            "Satisfies GDPR data minimization principle by design",
+            "Strong regulatory story under GDPR Article 25 (privacy by design)",
+        ],
+        cons=[
+            "Noise injection disproportionately harms underrepresented groups — "
+            "DP can WORSEN fairness for minorities",
+            "Significant accuracy cost; privacy budget ε directly trades off with utility",
+            "diffprivlib supports only Logistic Regression and select estimators",
+        ],
+        fairlearn_api="diffprivlib.models.LogisticRegression(epsilon=1.0)",
+        diffprivlib_api="diffprivlib.models.LogisticRegression(epsilon=1.0)",
+        who_benefits="All individuals in the training set; regulatory compliance teams",
+        tradeoff_cost=(
+            "Model accuracy; minority group fairness (noise amplification); "
+            "limited model family choices"
+        ),
+        compatible_with=["demographic_parity"],
+        incompatible_with=[],
+    ),
+
+    "threshold_optimizer": FairnessOption(
+        name="Post-Processing Threshold Optimizer",
+        definition=(
+            "Train a race-blind model, then adjust decision thresholds "
+            "per group at deployment time to satisfy Equalized Odds — "
+            "protected attributes used only for threshold calibration, "
+            "never as model features."
+        ),
+        stakeholder_view=(
+            "Pragmatic compromise — 'The model itself is blind; only the "
+            "deployment policy uses demographic information.'"
+        ),
+        pros=[
+            "Model weights do not encode protected attributes — lower model inversion risk",
+            "Strong accuracy (uses GradientBoosting as base model)",
+            "Achieves Equalized Odds without embedding sensitive features in the model",
+            "Threshold table is a small, auditable, human-readable artifact",
+        ],
+        cons=[
+            "Requires protected attributes at inference time for threshold lookup",
+            "Still technically processes demographic data — GDPR Art. 9 consideration",
+            "GradientBoosting base model is a black box (EU AI Act transparency tension)",
+        ],
+        fairlearn_api=(
+            "from fairlearn.postprocessing import ThresholdOptimizer\n"
+            "ThresholdOptimizer(estimator=clf, constraints='equalized_odds').fit(X, y, sensitive_features=sf)"
+        ),
+        who_benefits="Teams wanting Equalized Odds without encoding race into model weights",
+        tradeoff_cost="Slight accuracy drop; still requires demographic data collection",
+        compatible_with=["equalized_odds"],
+        incompatible_with=["demographic_parity"],
+    ),
+
+    "human_in_loop_escalation": FairnessOption(
+        name="Human-in-the-Loop Escalation",
+        definition=(
+            "Flagged activities are routed to a human moderator before action. "
+            "Auto-escalate is reserved only for high-confidence P0 cases."
+        ),
+        stakeholder_view=(
+            "Respect child autonomy and prevent arbitrary censorship by enforcing human review."
+        ),
+        pros=[
+            "Prevents false positive blocks",
+            "Ensures human oversight (EU AI Act Art 14)",
+            "Protects children from automated censorship",
+        ],
+        cons=[
+            "High latency in safety intervention",
+            "Moderator mental health exposure",
+            "High operational costs",
+        ],
+        fairlearn_api="# Safeguarding: human_in_the_loop_review",
+        who_benefits="Minors experiencing false-positive flags, privacy advocates",
+        tradeoff_cost="Intervention latency, moderator overhead",
+        compatible_with=["metadata_only_retention"],
+        incompatible_with=[],
+    ),
+
+    "metadata_only_retention": FairnessOption(
+        name="Metadata-Only Retention",
+        definition=(
+            "Log only anonymized metadata (user ID hash, timestamp, alert type) "
+            "for compliance. Discard message contents immediately."
+        ),
+        stakeholder_view=(
+            "GDPR Article 25 Privacy by Design — protect children's communication "
+            "from data breaches."
+        ),
+        pros=[
+            "Minimizes privacy violation risk",
+            "Limits data breach liability",
+            "Compliant with UN CRC Article 16 (privacy)",
+        ],
+        cons=[
+            "Impossible to perform manual post-audit",
+            "Cannot retrain model on false negatives/positives",
+            "Limits evidence gathering for active abuse",
+        ],
+        fairlearn_api="# Safeguarding: metadata_only_retention",
+        who_benefits="Minors in the dataset, data protection officers",
+        tradeoff_cost="Model auditability, future training data collection",
+        compatible_with=["human_in_loop_escalation"],
+        incompatible_with=[],
+    ),
+
+    "recall_first_detection": FairnessOption(
+        name="Recall-First Detection (FN vs FP)",
+        definition=(
+            "Optimize model threshold to minimize False Negatives (FN). "
+            "Flag all potential safety issues, accepting higher False Positives (FP)."
+        ),
+        stakeholder_view=(
+            "Safety first — a missed grooming or abuse attempt is far worse than a false flag."
+        ),
+        pros=[
+            "Maximizes protection of child safety",
+            "Captures subtle grooming patterns early",
+            "Allows swift intervention",
+        ],
+        cons=[
+            "High rate of false alerts",
+            "Moderator fatigue from noise",
+            "Disrupts user experience with false blocks",
+        ],
+        fairlearn_api="# Safeguarding: recall_first_optimization",
+        who_benefits="Vulnerable children, child protection teams",
+        tradeoff_cost="Moderator burden, user disruption",
+        compatible_with=["human_in_loop_escalation"],
+        incompatible_with=[],
+    ),
+
+    "cybersecurity_tradeoff": FairnessOption(
+        name="Transparency vs. Gaming & Inversion",
+        definition=(
+            "Balance public transparency of model details (weights, features) against "
+            "the risk of adversarial gaming (manipulation of features by users) "
+            "and model inversion (reconstructing training data)."
+        ),
+        stakeholder_view=(
+            "Security-first — limit public exposure of model parameters to prevent exploitation."
+        ),
+        pros=[
+            "Prevents users from gaming the scoring system",
+            "Protects proprietary model IP",
+            "Reduces risk of model inversion attacks",
+        ],
+        cons=[
+            "Violates EU AI Act Article 13 transparency requirements",
+            "Prevents independent public audits of bias",
+            "Restricts user right to explanation",
+        ],
+        fairlearn_api="# Cybersecurity: adversarial training and API rate limiting / model obfuscation",
+        who_benefits="System operators, database administrators, model providers",
+        tradeoff_cost="Transparency, public auditability, explaining individual predictions",
+        compatible_with=["equalized_odds", "differential_privacy", "demographic_parity"],
+        incompatible_with=[],
+    ),
+}
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# DETERMINISTIC DETECTION FUNCTIONS
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+def _detect_domain(text: str) -> tuple[str, str | None, list[str]]:
+    """
+    Returns (domain_key, eu_ai_act_annex | None, udhr_articles).
+    Pure keyword matching — deterministic and fast.
+    """
+    text_lower = text.lower()
+    for domain_key, info in EU_AI_ACT_ANNEX_III.items():
+        if any(kw in text_lower for kw in info["keywords"]):
+            return domain_key, info["annex"], UDHR_ARTICLE_MAP.get(domain_key, ["Article 2"])
+    return "general", None, UDHR_ARTICLE_MAP["general"]
+
+
+def _detect_protected_attributes(text: str) -> list[str]:
+    """Detects protected attributes mentioned directly."""
+    text_lower = text.lower()
+    found = []
+    for attr in PROTECTED_ATTRIBUTES:
+        pattern = r"\b" + re.escape(attr.replace("_", "[ _]?")) + r"\b"
+        if re.search(pattern, text_lower):
+            found.append(attr)
+    return list(set(found))
+
+
+def _detect_proxy_attributes(text: str, protected_attrs: list[str]) -> list[str]:
+    """
+    Detects proxy attributes using the semantic PROXY_ATTRIBUTE_MAP.
+    Always scans all proxy attributes to prevent missing proxy features
+    when a different protected attribute is explicitly specified.
+    """
+    text_lower = text.lower()
+    found: list[str] = []
+    for group, proxies in PROXY_ATTRIBUTE_MAP.items():
+        for proxy in proxies:
+            if proxy.lower() in text_lower:
+                found.append(proxy)
+    return list(set(found))
+
+
+def _score_risk(
+    domain: str,
+    protected_attrs: list[str],
+    proxy_attrs: list[str],
+    annex: str | None,
+) -> Literal["LOW", "MEDIUM", "HIGH", "CRITICAL"]:
+    """Deterministic risk scoring. No LLM involved."""
+    score = 0
+    if annex:
+        score += 3
+    score += min(len(protected_attrs) * 2, 4)
+    score += min(len(proxy_attrs), 2)
+    if domain in ("criminal_justice", "children_safety"):
+        score += 2
+    elif domain in ("credit_scoring", "employment"):
+        score += 1
+
+    if score >= 7:
+        return "CRITICAL"
+    if score >= 5:
+        return "HIGH"
+    if score >= 3:
+        return "MEDIUM"
+    return "LOW"
+
+
+def _build_compliance_flags(
+    domain: str,
+    protected_attrs: list[str],
+    proxy_attrs: list[str],
+    annex: str | None,
+) -> list[str]:
+    flags: list[str] = []
+    if protected_attrs:
+        flags.append(
+            f"PROTECTED ATTRIBUTES IN FEATURE SET: {', '.join(protected_attrs)} — "
+            "direct use may violate GDPR Article 9 and EU AI Act Article 10"
+        )
+    if proxy_attrs:
+        flags.append(
+            f"PROXY DISCRIMINATION RISK: {', '.join(proxy_attrs)} — "
+            "these features may encode protected characteristics indirectly"
+        )
+    if annex:
+        flags.append(
+            f"EU AI ACT HIGH-RISK CLASSIFICATION: {annex} — "
+            "mandatory conformity assessment, DPIA, and bias monitoring required pre-deployment"
+        )
+    if domain == "criminal_justice":
+        flags.append(
+            "FAIRNESS IMPOSSIBILITY THEOREM: Demographic Parity, Equalized Odds, and "
+            "Predictive Parity cannot all be satisfied simultaneously when base rates differ. "
+            "A values choice must be documented."
+        )
+    if domain == "children_safety":
+        flags.append(
+            "CHILDREN'S RIGHTS: UN CRC Articles 3, 12, 16, 19, 34 apply. "
+            "Explicit escalation policy, data retention limits, and false-negative tolerance "
+            "must be defined and documented before proceeding."
+        )
+    if domain == "employment":
+        flags.append(
+            "AD DELIVERY BIAS: Algorithm optimization for engagement may produce "
+            "gender/race disparities even with neutral targeting (Ali et al. 2019, Lambrecht & Tucker 2019). "
+            "Audit delivery outcomes, not just model inputs."
+        )
+    return flags
+
+
+def _select_fairness_options(domain: str) -> list[FairnessOption]:
+    """Returns the 3 most relevant options ordered by relevance, covering Fairness, Privacy, and Cybersecurity."""
+    domain_map: dict[str, list[str]] = {
+        "criminal_justice": [
+            "equalized_odds", "differential_privacy", "cybersecurity_tradeoff"
+        ],
+        "credit_scoring": [
+            "equalized_odds", "differential_privacy", "cybersecurity_tradeoff"
+        ],
+        "employment": [
+            "demographic_parity", "differential_privacy", "cybersecurity_tradeoff"
+        ],
+        "children_safety": [
+            "human_in_loop_escalation", "metadata_only_retention", "recall_first_detection"
+        ],
+    }
+    keys = domain_map.get(domain, ["equalized_odds", "differential_privacy", "cybersecurity_tradeoff"])
+    return [_FAIRNESS_LIBRARY[k] for k in keys]
+
+
+def _build_regulations(domain: str, annex: str | None) -> list[str]:
+    regs: list[str] = []
+    if annex:
+        domain_info = EU_AI_ACT_ANNEX_III.get(domain, {})
+        regs.append(f"EU AI Act {annex}: {domain_info.get('description', '')}")
+    regs.append("GDPR Article 9 — Processing of special category personal data")
+    regs.append("UNESCO Recommendation on AI Ethics (2021) — Principle 7: Fairness & Non-Discrimination")
+    regs.append("OECD AI Principles (2019) — Principle 1.3: Fairness & Inclusivity")
+    if domain == "criminal_justice":
+        regs += [
+            "UDHR Article 7 — Equal protection under the law",
+            "UDHR Article 10 — Right to fair and public hearing",
+            "ECHR Article 6 — Right to fair trial",
+            "State v. Loomis (2016) — Due process in algorithmic sentencing",
+        ]
+    elif domain == "employment":
+        regs += [
+            "UDHR Article 23 — Right to work without discrimination",
+            "EU Charter Article 21 — Non-discrimination",
+            "Equal Employment Opportunity Act (US)",
+        ]
+    elif domain == "credit_scoring":
+        regs += [
+            "UDHR Article 22 — Right to social security",
+            "Equal Credit Opportunity Act (US, 1974)",
+            "EU Charter Article 21 — Non-discrimination in financial services",
+        ]
+    elif domain == "children_safety":
+        regs += [
+            "UN Convention on the Rights of the Child Articles 3, 12, 16, 19, 34",
+            "UNICEF Guidance on AI and Children v3.0 (2025)",
+        ]
+    return regs
+
+
+def _build_immediate_actions(
+    risk_level: str,
+    protected_attrs: list[str],
+    proxy_attrs: list[str],
+    domain: str,
+    annex: str | None,
+) -> list[str]:
+    actions: list[str] = []
+    if risk_level in ("HIGH", "CRITICAL"):
+        actions.append(
+            "Conduct Data Protection Impact Assessment (DPIA) before deployment — "
+            "required by GDPR Article 35 for high-risk processing"
+        )
+    if protected_attrs:
+        actions.append(
+            f"Evaluate whether {', '.join(protected_attrs)} can be removed from "
+            "the feature set; audit remaining features for proxy discrimination"
+        )
+    if proxy_attrs:
+        actions.append(
+            f"Audit correlation between [{', '.join(proxy_attrs)}] and protected "
+            "characteristics using Fairlearn MetricFrame before training"
+        )
+    if annex:
+        actions.append(
+            f"Register this system under EU AI Act {annex} — conformity assessment "
+            "and bias monitoring are mandatory, not optional"
+        )
+    if domain == "children_safety":
+        actions.append(
+            "Define and document escalation policy (who reviews flagged messages), "
+            "data retention limit (how long conversations are stored), and "
+            "acceptable false-negative tolerance before writing any code"
+        )
+    if domain == "criminal_justice":
+        actions.append(
+            "Select ONE fairness metric (Equalized Odds recommended per ProPublica standard) "
+            "and document the values judgment. "
+            "The Fairness Impossibility Theorem means you cannot satisfy all three simultaneously."
+        )
+    return actions
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# LLM ENRICHMENT  (optional; fails gracefully)
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+def _enrich_with_llm(prompt: str, det: dict[str, Any]) -> str:
+    """
+    Calls the configured LLM to write a 2-3 sentence governance explanation.
+    Returns a deterministic fallback if LLM is unavailable or times out.
+    """
+    fallback = (
+        f"Deterministic analysis: Domain={det['domain']}, Risk={det['risk_level']}. "
+        f"Protected attributes: {det['protected_attributes'] or 'none detected directly'}. "
+        f"Proxy attributes: {det['proxy_attributes'] or 'none detected'}. "
+        f"Applicable regulation: {det.get('annex') or 'none (not classified as high-risk)'}."
+    )
+
+    if not LLM_AVAILABLE:
+        return fallback
+
+    system = (
+        "You are SAGE, a governance agent for AI systems. Given a developer's coding "
+        "prompt and a preliminary risk classification, write a concise 2-3 sentence "
+        "explanation of WHY this prompt raises ethical or regulatory concerns. "
+        "Reference specific laws, principles, or documented real-world cases. "
+        "Be factual and precise. Output ONLY the explanation — no JSON, no preamble, "
+        "no bullet points."
+    )
+    user = (
+        f"Developer prompt: \"{prompt}\"\n\n"
+        f"SAGE preliminary classification:\n"
+        f"- Domain: {det['domain']}\n"
+        f"- Risk level: {det['risk_level']}\n"
+        f"- Protected attributes detected: {det['protected_attributes']}\n"
+        f"- Proxy attributes detected: {det['proxy_attributes']}\n"
+        f"- Applicable regulation: {det.get('annex', 'None')}\n\n"
+        "Write 2-3 sentences explaining the governance concern."
+    )
+
+    try:
+        response = LLM_CLIENT.chat.completions.create(
+            model=LLM_MODEL,
+            max_tokens=350,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+        )
+        return response.choices[0].message.content.strip()
+    except Exception as exc:
+        print(f"[sage_agent] LLM enrichment failed: {exc}", file=sys.stderr)
+        return fallback
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# MAIN PUBLIC API
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+def evaluate(
+    prompt: str,
+    code: str = "",
+    context: str = "",
+) -> SageEvaluateResponse:
+    """
+    Full SAGE evaluation pipeline.
+
+    Step 1: Deterministic domain/attribute/risk detection (always runs)
+    Step 2: LLM reasoning enrichment (optional, graceful fallback)
+    Step 3: Pydantic validation (always enforced)
+
+    Returns: SageEvaluateResponse — Pydantic-validated, always parseable.
+    """
+    full_text = f"{prompt} {code} {context}"
+
+    # ── Step 1: Deterministic analysis ────────────────────────────────────────
+    domain, annex, udhr_articles = _detect_domain(full_text)
+    protected_attrs = _detect_protected_attributes(full_text)
+    proxy_attrs     = _detect_proxy_attributes(full_text, protected_attrs)
+    risk_level      = _score_risk(domain, protected_attrs, proxy_attrs, annex)
+    flags           = _build_compliance_flags(domain, protected_attrs, proxy_attrs, annex)
+    options         = _select_fairness_options(domain)
+    regulations     = _build_regulations(domain, annex)
+    actions         = _build_immediate_actions(
+        risk_level, protected_attrs, proxy_attrs, domain, annex
+    )
+    domain_info     = EU_AI_ACT_ANNEX_III.get(domain, {})
+
+    det = {
+        "domain": domain,
+        "risk_level": risk_level,
+        "protected_attributes": protected_attrs,
+        "proxy_attributes": proxy_attrs,
+        "annex": annex,
+    }
+
+    # ── Step 2: LLM enrichment ────────────────────────────────────────────────
+    reasoning = _enrich_with_llm(prompt, det)
+
+    # ── Step 3: Pydantic-validated return ────────────────────────────────────
+    return SageEvaluateResponse(
+        risk_level=risk_level,
+        eu_ai_act_annex=annex,
+        eu_ai_act_category=domain_info.get("description"),
+        udhr_articles=udhr_articles,
+        protected_attributes=protected_attrs,
+        proxy_attributes=proxy_attrs,
+        detected_domain=domain,
+        intent_summary=prompt[:300],
+        compliance_flags=flags,
+        fairness_options=options,
+        immediate_actions=actions,
+        regulations=regulations,
+        requires_human_review=risk_level in ("HIGH", "CRITICAL"),
+        sage_reasoning=reasoning,
+        fairness_impossibility=domain in ("criminal_justice", "credit_scoring", "employment"),
+    )
+
+
+def log_model_metrics(metrics: dict[str, Any], dataset_info: Optional[dict[str, Any]] = None) -> str:
+    """
+    Log model training/evaluation metrics and dataset info to the audit trail.
+    This is called automatically when the model trains or evaluates.
+    """
+    from startup import write_audit_entry
+    entry = {
+        "event_type": "model_trained",
+        "metrics": metrics,
+        "dataset_info": dataset_info or {},
+    }
+    return write_audit_entry(entry)