Venturalítica SDK

📄 Companion to the arXiv preprint Making AI Compliance Evidence Machine-Readable (Cilla Ugarte et al., 2026). See CITATION.cff and the normative OSCAL contract.

Compliance by Design — AI Assurance through Compliance-as-Code.

The Venturalítica SDK enables Data Scientists and ML Engineers to integrate compliance and risk management directly into their training workflows. Built on the OSCAL (Open Security Controls Assessment Language) standard, it provides semantic policy enforcement with educational audit trails.

Join our Discord community — Get help, share your use case, and discuss EU AI Act compliance with other engineers.

✨ Key Features

• Glass Box Governance: Sequential regulatory mapping (Art 9-15) for total transparency.
• Strict Mode: Auto-enforcement of compliance checks in CI/CD environments.
• Deep Provenance: Trace data lineage across Files, SQL, and S3 using ArtifactProbe.
• Local Sovereignty: Zero-cloud dependency. All enforcement runs locally.
• TraceCollector Architecture: Unified evidence gathering for BOM, metrics, anlogs.
• Educational Audits: Control descriptions that explain why metrics matter.
• Deep Integrations: Seamless "Glass Box" syncing with MLflow & WandB.
• OSCAL-Native: Policy-as-Code using standard NIST formats.
• Annex IV Ready: Auto-draft technical documentation from local traces.

📦 Installation

pip install venturalitica

⚙️ Configuration

The SDK supports the following Environment Variables. We recommend using a .env file (but never commit it!).

📋 Prerequisites

• Python: 3.11+
• Local LLM (Optional):
  • Ollama: (Recommended for standard local use).
  • ALIA (Experimental): Native Spanish Sovereign model (Requires High-End GPU).
  • Note: If you cannot run local models, please set MISTRAL_API_KEY for cloud generation.

🚀 Quick Start

60-Second Demo

import venturalitica as vl

# Auto-downloads UCI German Credit and runs bias audit
results = vl.quickstart('loan')

Output:

[📊] Loaded: UCI Dataset #144 (1000 samples)
[✅] PASSED: 3/3 fairness controls

🎉 Dataset passes bias checks!

Analyze Your Own Data

First, create a policy file (fairness.yaml) that defines what to check:

assessment-plan:
  uuid: my-policy
  metadata:
    title: "Fairness Policy"
  reviewed-controls:
    control-selections:
      - include-controls:
        - control-id: gender-check
          description: "Approval rates must be similar across genders"
          props:
            - name: metric_key
              value: demographic_parity_diff
            - name: threshold
              value: "0.10"
            - name: operator
              value: "<"

Then run the audit:

import pandas as pd
import venturalitica as vl

df = pd.read_csv("my_data.csv")

vl.enforce(
    data=df,
    target="approved",
    gender="gender",
    policy="fairness.yaml"
)

📚 Documentation

Read Full Documentation — Hosted on Starlight.

Quick guides:

• Quickstart Guide: Get started in 60 seconds
• Full Lifecycle Walkthrough: Zero to Annex IV in one page
• Policy Authoring: Write OSCAL policies for your AI systems
• Compliance Dashboard: Understanding the Glass Box Dashboard (Art 9-15)
• Evidence Probes: Automated evidence collection for audits
• Samples Repository: Real-world examples

🎯 Core Concepts

Role-Based Binding

The SDK uses a three-tier mapping system:

1. Functional Roles (defined by metrics): target, prediction, dimension
2. Semantic Variables (defined in policies): gender, age_group, income
3. Physical Columns (in your DataFrame): sex_col, age_cat, salary

This decoupling allows policies to evolve independently of your training code.

Educational Audits

Control descriptions include regulatory context:

- control-id: data-quality-check
  description: "Data Quality: Minority class should represent at least 20% to avoid Class Imbalance"

Evaluated vs. Retained

enforce() caches everything it evaluates, so the Local Dashboard can show every control it ever ran. That's the right behavior for a single call per run, but some pipelines call enforce() more than once against different partitions of the same dataset -- e.g. one pass per case and another per anatomical sub-unit -- and only keep the controls the compiled OSCAL policy actually assigns to each partition. If you do that, call vl.retain() with the filtered subset before the monitor() block ends:

with vl.monitor("training-run"):
    by_case = vl.enforce(data=case_df, policy="per-case.oscal.yaml")
    by_unit = vl.enforce(data=unit_df, policy="per-unit.oscal.yaml")

    # Filter down to what actually applies (e.g. by reading each control's
    # partition tag from the compiled OSCAL), then declare it authoritative:
    vl.retain(by_case + [r for r in by_unit if r.control_id in unit_controls])

vl push ships whichever exists: the retained subset if retain() was called, otherwise everything evaluated (the default, single-call behavior). This keeps the pushed assessment-results.oscal.json from ever disagreeing with the pipeline's own authoritative metrics. Every result also carries metadata["partition_digest"], a content digest of the data it was computed against, so two results sharing a control_id stay distinguishable even after filtering discards which partition produced which.

🛠️ CLI Tools

BOM & Supply Chain

The SDK automatically generates a CycloneDX ML-BOM during execution via vl.monitor().

Detects:

• Python dependencies (requirements.txt, pyproject.toml)
• ML models (scikit-learn, PyTorch, TensorFlow, XGBoost, etc.)
• MLOps frameworks (MLflow, WandB, ClearML)

Output: bom key within your audit trace JSON.

Compliance Dashboard

Launch the Local Regulatory Map to interpret your evidence:

venturalitica ui

Read the Guide: Understanding the Dashboard

Features:

• Article 9-15 Walk: A sequential check of Risk, Data, Transparency, and Oversight.
• Sequential Verification: See exactly which technical artifact satisfies which legal article.
• Annex IV Draft: Generate the PDF-ready markdown file with venturalitica doc.

Integrates with:

• trace_*.json (from vl.monitor())
• emissions.csv (from CodeCarbon)
• OSCAL policies

📡 Telemetry & Privacy

Venturalítica collects anonymous usage data to help us improve the SDK.

• What we track: Command usage (login, pull, push), SDK execution times, and errors.
• What we DO NOT track: Your datasets, PII, IP addresses, or any code content.
• Privacy First: We host our analytics in the EU and strictly disable IP tracking (disable_geoip=True).

Opt-Out: To disable telemetry completely, set the environment variable:

export VENTURALITICA_NO_ANALYTICS=1

Or follow the standard DO_NOT_TRACK specification.

🔒 Data Sovereignty & Privacy

Venturalítica follows a strict Local-First architecture.

• No Cloud Uploads: vl.enforce() and vl.quickstart() run entirely on your local machine. Your datasets never leave your environment.
• Telemetry: Usage metrics (if enabled) are strictly metadata (e.g., performance, error rates) and contain NO PII.
• Compliance Data: All evidence (trace_*.json) is stored locally in .venturalitica/. You own your compliance data.

☁️ Venturalítica Cloud (Coming Soon)

Enterprise-grade EU AI Act & ISO 42001 compliance management

While the SDK provides frictionless local enforcement, Venturalítica Cloud will offer a complete compliance lifecycle management platform for EU AI Act and ISO 42001:

What's Coming

• Visual Policy Builder: Create OSCAL policies mapped to EU AI Act Articles 9-15 & ISO 42001 controls
• Team Collaboration: Centralized policy management across organizations
• Compliance Dashboard: Real-time status for EU AI Act & ISO 42001 requirements
• Annex IV Generator: Auto-generate complete EU AI Act technical documentation
• Risk Assessment: Guided workflows for high-risk AI system classification
• Audit Trail: Immutable compliance history for regulatory inspections
• Integration Hub: Connect with your existing MLOps and governance tools

Early Access

Interested in early access to Venturalítica Cloud?

• Join the waitlist: www.venturalitica.ai (coming soon)
• Enterprise inquiries: Contact us for pilot programs

The SDK will always remain free and open-source under Apache 2.0. The cloud platform will offer additional enterprise features for teams managing EU AI Act and ISO 42001 compliance at scale.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

Apache 2.0 - See LICENSE for details.

🔗 Links

• Samples Repository
• Documentation
• OSCAL Standard