Skip to content

quickstart.md

Latest commit

 

History

History
169 lines (117 loc) · 7.18 KB

quickstart.md

File metadata and controls

169 lines (117 loc) · 7.18 KB

60-Second Quickstart

Goal: Your first bias audit in under 60 seconds.

The Fundamentals: From Risk to Code

Building High-Risk AI requires a fundamental shift in how we approach testing. It is no longer enough to check for technical accuracy (e.g., F1 Score); we must now mathematically prove that the system respects fundamental rights, such as non-discrimination or data quality, as mandated by the EU AI Act.

Venturalítica automates this by treating "Assurance" as a dependency. Instead of vague legal requirements, you define strict policies (OSCAL) that your model must pass before it can be deployed. This turns compliance into a deterministic engineering problem. !!! question "Is my System High-Risk?" According to Article 6 of EU AI Act, a system is High-Risk if it is covered by Annex I (Safety Components like machinery/medical devices) or listed in Annex III (Biometrics, Critical Infrastructure, Education, Employment, Essential Services, Law Enforcement, Migration, Justice/Democracy).

The Translation Layer:

  1. Fundamental Risk: "The model must not discriminate against protected groups" (Art 9).

  2. Policy Control: "Disparate Impact Ratio must be > 0.8".

  3. Code Assertion: assert calculated_metric > 0.8.

When you run quickstart(), you are technically running a Unit Test for Ethics.

Step 1: Install

pip install venturalitica

Step 2: Run Your First Audit

import venturalitica as vl

vl.quickstart('loan')

Output:

[Venturalítica {{ version }}] 🎓 Scenario: Credit Scoring Fairness
[Venturalítica {{ version }}] 📊 Loaded: UCI Dataset #144 (1000 samples)

  CONTROL                DESCRIPTION                            ACTUAL     LIMIT      RESULT
  ────────────────────────────────────────────────────────────────────────────────────────────────
  credit-data-imbalanc   Data Quality: Minority class repres... 0.429      > 0.2      ✅ PASS
  credit-data-bias       Disparate impact ratio follows the ... 0.818      > 0.8      ✅ PASS
  credit-age-disparate   Age disparate impact ratio > 0.5       0.286      > 0.5      ❌ FAIL
  ────────────────────────────────────────────────────────────────────────────────────────────────
  Audit Summary: ❌ VIOLATION | 2/3 controls passed

!!! info The audit detected age-based bias in the UCI German Credit dataset — the age disparate impact ratio (0.286) is well below the 0.5 threshold set by the policy.

Step 3: What's Happening Under the Hood

The quickstart() function is a wrapper that performs the full compliance lifecycle in one go:

  1. Downloads Data: Fetches the UCI German Credit dataset.
  2. Loads Policy: Reads data_policy.oscal.yaml which defines the fairness rules.
  3. Enforces: Runs the audit (vl.enforce).
  4. Records: Captures the evidence (trace.json) for the dashboard.

Here's the equivalent "manual" code:

from ucimlrepo import fetch_ucirepo
import venturalitica as vl

# 1. Load Data (The "Risk Source")
dataset = fetch_ucirepo(id=144)
df = dataset.data.features
df['class'] = dataset.data.targets

# 2. Define the Policy (The "Law")
# Create data_policy.oscal.yaml (see Academy Level 1 for full policy file)

# 3. Run the Audit (The "Test")
# This automatically generates the Evidence Bill of Materials (BOM)
with vl.monitor("manual_audit"):
    vl.enforce(
        data=df,
        target="class",          # The outcome (True/False)
        gender="Attribute9",     # Protected Group A
        age="Attribute13",       # Protected Group B
        policy="data_policy.oscal.yaml"
    )

The Policy Logic

The policy (data_policy.oscal.yaml) is the bridge. It tells the SDK what to check so you don't have to hardcode it.

# ... inside the OSCAL YAML ...
- control-id: credit-data-bias
  description: "Disparate impact ratio must be > 0.8 (80% rule)"
  props:
    - name: metric_key
      value: disparate_impact   # <--- The Python Function to call
    - name: threshold
      value: "0.8"              # <--- The Limit to enforce
    - name: operator
      value: ">"                # <--- The Logic (> 0.8)
    - name: "input:dimension"
      value: gender             # <--- Maps to "Attribute9"

This design decouples Assurance (the policy file) from Engineering (the python code).

Why This Matters

Without this mechanism, your AI model is a legal "Black Box":

  • Liability: You cannot prove you checked for bias before deployment (Art 9).
  • Fragility: Compliance is a manual checklist, easily forgotten or skipped.
  • Opacity: Auditors cannot see the link between your code and the law.

By running quickstart(), you have just generated an immutable Compliance Artifact. Even if the laws change, your evidence remains.

Step 4: The "Glass Box" Dashboard 📊

Now that we have the evidence (the "Black Box" recording), let's inspect it in the Regulatory Map.

pip install venturalitica[dashboard]   # Required for the UI
venturalitica ui

Navigate through the Compliance Map tabs:

  • Article 9 (Risk): See the failed credit-age-disparate control. This is your technical evidence of "Risk Monitoring".
  • Article 10 (Data): See the data distribution and quality checks.
  • Article 13 (Transparency): Review the "Transparency Feed" to see your Python dependencies (BOM).

Step 5: Generate Documentation (Annex IV) 📝

The final step is to turn this evidence into a legal document.

  1. In the Dashboard, go to the "Generation" tab.
  2. Select "English" (or Spanish/Catalan/Euskera).
  3. Click "Generate Annex IV".

Venturalítica will draft a technical document that references your specific run:

"As evidenced in trace_quickstart_loan.json, the system was audited against [OSCAL Policy: Credit Scoring Fairness]. A deviation was detected in Age Disparity (0.36), identifying a potential risk of bias..."

References

What's Next?