Metadata-Version: 2.4
Name: venturalitica
Version: 0.6.10
Summary: AI assurance that compiles. Turn EU AI Act + ISO 42001 + DORA controls into executable OSCAL policy and enforce it at training time with one decorator.
Project-URL: Homepage, https://venturalitica.ai
Project-URL: Documentation, https://venturalitica.github.io/venturalitica-sdk
Project-URL: Repository, https://github.com/Venturalitica/venturalitica-sdk
Project-URL: Changelog, https://github.com/Venturalitica/venturalitica-sdk/releases
Author-email: Venturalítica <info@venturalitica.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,compliance,eu-ai-act,fairness,governance,mlops,oscal
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: compliance-trestle>=3.11.0
Requires-Dist: cyclonedx-python-lib>=11.6.0
Requires-Dist: huggingface-hub
Requires-Dist: numpy>=2.4.0
Requires-Dist: pandas>=2.3.0
Requires-Dist: posthog>=3.5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.2.0
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: typer>=0.21.0
Requires-Dist: ucimlrepo>=0.0.7
Provides-Extra: agentic
Requires-Dist: langchain-community; extra == 'agentic'
Requires-Dist: langchain-huggingface>=0.1.0; extra == 'agentic'
Requires-Dist: langchain-mistralai>=1.1.0; extra == 'agentic'
Requires-Dist: langchain-ollama>=1.0.1; extra == 'agentic'
Requires-Dist: langgraph>=1.0.7; extra == 'agentic'
Requires-Dist: llama-cpp-python; extra == 'agentic'
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.57.0; extra == 'dashboard'
Provides-Extra: full
Requires-Dist: codecarbon>=2.3.0; extra == 'full'
Requires-Dist: fairlearn>=0.10.0; extra == 'full'
Requires-Dist: langchain-community; extra == 'full'
Requires-Dist: langchain-huggingface>=0.1.0; extra == 'full'
Requires-Dist: langchain-mistralai>=1.1.0; extra == 'full'
Requires-Dist: langchain-ollama>=1.0.1; extra == 'full'
Requires-Dist: langgraph>=1.0.7; extra == 'full'
Requires-Dist: llama-cpp-python; extra == 'full'
Requires-Dist: streamlit>=1.57.0; extra == 'full'
Requires-Dist: torch>=2.0.0; extra == 'full'
Provides-Extra: green
Requires-Dist: codecarbon>=2.3.0; extra == 'green'
Provides-Extra: metrics
Requires-Dist: fairlearn>=0.10.0; extra == 'metrics'
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == 'torch'
Description-Content-Type: text/markdown

# Venturalítica SDK

![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)
[![PyPI](https://img.shields.io/pypi/v/venturalitica)](https://pypi.org/project/venturalitica/)
[![Python](https://img.shields.io/pypi/pyversions/venturalitica)](https://pypi.org/project/venturalitica/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Discord](https://img.shields.io/discord/P4RURqRm?label=Discord&logo=discord)](https://discord.gg/P4RURqRm)

> 📄 **Companion to the arXiv preprint** *[Making AI Compliance Evidence Machine-Readable](https://arxiv.org/abs/2604.13767)* (Cilla Ugarte et al., 2026). See [`CITATION.cff`](./CITATION.cff) and the [normative OSCAL contract](./docs/contracts/oscal-assessment-plan-v1.md).

**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](https://discord.gg/P4RURqRm)** — 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

```bash
pip install venturalitica
```

## ⚙️ 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](https://console.mistral.ai/). 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

```python
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:

```yaml
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:

```python
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](https://venturalitica.github.io/venturalitica-sdk/)** — 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](https://github.com/venturalitica/venturalitica-sdk-samples)**: 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:

```yaml
- 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:

```bash
venturalitica ui
```

**[Read the Guide: Understanding the Dashboard](https://venturalitica.github.io/venturalitica-sdk/)**

**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:
```bash
export VENTURALITICA_NO_ANALYTICS=1
```
Or follow the standard [DO_NOT_TRACK](https://consoledonottrack.com/) 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](http://www.venturalitica.ai) *(coming soon)*
- **Enterprise inquiries**: [Contact us](http://www.venturalitica.ai) 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](CONTRIBUTING.md).

## 📄 License

Apache 2.0 - See [LICENSE](LICENSE) for details.

## 🔗 Links

- [Samples Repository](https://github.com/venturalitica/venturalitica-sdk-samples)
- [Documentation](docs/)
- [OSCAL Standard](https://pages.nist.gov/OSCAL/)
