venturalitica 0.5.1

Frictionless Governance for AI. Enforce policies in your ML training with one line of code.

Venturalítica SDK

Frictionless Governance for AI Systems.

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.

✨ 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 git+https://github.com/Venturalitica/venturalitica-sdk.git

⚙️ Configuration

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

Variable	Description	Default	Required?
MISTRAL_API_KEY	Get a Free Key. Used for Cloud Fallback if local Ollama fails.	None	Recommended
VENTURALITICA_LLM_PRO	Set to true to use Mistral even if Ollama is available (Higher Quality).	false	No
VENTURALITICA_STRICT	Set to true to enforce strict compliance checks (fail on missing metrics).	false	No
MLFLOW_TRACKING_URI	If set, monitor() will auto-log audits to MLflow.	None	No

📋 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

• Tutorial: Zero-Setup Audit: "Hello World" - Scan & Visualize in 2 minutes
• Tutorial: Training Integration: Add compliance checks to your Python code
• Concept: Strict Mode: Enforcing compliance in CI/CD chains
• Concept: The Regulatory Map: Understanding the Dashboard (Art 9-15)
• Concept: Evidence Collection: How to record your 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"

🛠️ 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

🔒 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