API Reference

Venturalitica exposes five public symbols. This page documents their exact signatures and behavior as of v0.6.0.

---

Core Functions

quickstart(scenario, verbose=True)

Run a pre-configured bias audit demo on a standard dataset. This is the fastest way to see the SDK in action.

import venturalitica as vl

results = vl.quickstart("loan")

Parameter	Type	Default	Description
scenario	str	"loan"	Predefined scenario name. Only "loan" (UCI German Credit fairness audit) is bundled with the SDK; any other value raises ValueError. Additional scenarios live in the venturalitica-sdk-samples repository.
verbose	bool	True	Print the structured compliance table to the console.

Returns: List[ComplianceResult]

Note

quickstart() is a convenience wrapper. Internally it loads a dataset, resolves a built-in OSCAL policy, and calls enforce(). It is useful for demos and first-contact experiences.

---

enforce()

The main entry point for auditing datasets and models against OSCAL policies.

def enforce(
    data=None,
    metrics=None,
    policy="risks.oscal.yaml",
    target="target",
    prediction="prediction",
    strict=False,
    phase=None,
    **attributes,
) -> List[ComplianceResult]

Parameter	Type	Default	Description
data	DataFrame or None	None	Pandas DataFrame containing features, targets, and optionally predictions.
metrics	Dict[str, float] or None	None	Pre-computed metrics dict. Use this when you have already calculated your metrics externally.
policy	str, Path, or List	"risks.oscal.yaml"	Path to one or more OSCAL policy files. Pass a list to enforce multiple policies in a single call. The canonical v0.6.0 envelope is the unified assessment_plan.oscal.yaml emitted by vl pull.
target	str	"target"	Name of the column containing ground truth labels.
prediction	str	"prediction"	Name of the column containing model predictions.
strict	bool	False	If True, missing metrics, unbound variables, and calculation errors raise exceptions instead of being skipped. Auto-enabled when CI=true or VENTURALITICA_STRICT=true.
phase	str or None	None	Optional lifecycle_phase filter. Only controls tagged with this phase (or untagged) are evaluated. Typical values: "training" (raw data, Art. 10), "validation" (model predictions, Art. 15). Controls tagged monitoring or incident are always skipped by the SDK; they target the runtime proxy and incident handler respectively.
**attributes	keyword args		Mappings for protected variables and dimensions. For example: gender="Attribute9", age="Attribute13".

Returns: List[ComplianceResult]

Two Modes of Operation

Mode 1: DataFrame-based (most common). Pass a DataFrame and let the SDK compute metrics automatically:

results = vl.enforce(
    data=df,
    target="class",
    prediction="prediction",
    gender="Attribute9",     # maps abstract 'gender' -> column 'Attribute9'
    age="Attribute13",       # maps abstract 'age' -> column 'Attribute13'
    policy="assessment_plan.oscal.yaml",
    phase="training",        # only Art. 10 (data) controls run
)

Mode 2: Pre-computed metrics. Pass a dict of already-calculated values:

results = vl.enforce(
    metrics={"accuracy_score": 0.92, "demographic_parity_diff": 0.07},
    policy="assessment_plan.oscal.yaml",
    phase="validation",      # only Art. 15 (model) controls run
)

Column Binding

When using DataFrame mode, the SDK resolves column names through a synonym system (see Column Binding):

• target and prediction are resolved first via explicit parameters, then via synonym discovery.
• **attributes (e.g., gender="Attribute9") are passed directly to metric functions as the dimension parameter.
• If a column is not found, the SDK falls back to lowercase matching.

Results Caching

enforce() automatically caches results to .venturalitica/results.json and, if inside a monitor() session, to the session-specific evidence directory. Run venturalitica ui to visualize cached results.

Multiple Policies

Pass a list to enforce several policies in one call. v0.6.0 emits a single assessment_plan.oscal.yaml document that already covers every AssuranceMeasure end-to-end, so list mode is most useful when you want to merge an internal SaaS-emitted policy with a customer-authored OSCAL file:

results = vl.enforce(
    data=df,
    target="class",
    policy=["assessment_plan.oscal.yaml", "extra_controls.oscal.yaml"],
    gender="Attribute9",
)

---

monitor(name, label=None, inputs=None, outputs=None)

A context manager that records multimodal telemetry during training or evaluation. Captures hardware, carbon, security, and audit evidence automatically.

@contextmanager
def monitor(
    name="Training Task",
    label=None,
    inputs=None,
    outputs=None,
)

Parameter	Type	Default	Description
name	str	"Training Task"	Human-readable name for this monitoring session. Used in trace filenames.
label	str or None	None	Optional label for categorization (e.g., "pre-training", "validation").
inputs	List[str] or None	None	Paths to input artifacts (datasets, configs) for data lineage tracking.
outputs	List[str] or None	None	Paths to output artifacts (models, plots) for lineage tracking.

Usage

with vl.monitor("credit_model_v1"):
    model.fit(X_train, y_train)
    vl.enforce(data=df, policy="policy.oscal.yaml", target="class")

Probes Collected

monitor() initializes 7 probes automatically. See Probes Reference for details.

Probe	What It Captures	EU AI Act Article
IntegrityProbe	SHA-256 environment fingerprint, drift detection	Art. 15
HardwareProbe	Peak RAM, CPU count	Art. 15
CarbonProbe	CO2 emissions via CodeCarbon	Art. 15
BOMProbe	Software Bill of Materials (SBOM)	Art. 13
ArtifactProbe	Input/output data lineage	Art. 10
HandshakeProbe	Whether enforce() was called inside the session	Art. 9
TraceProbe	AST code analysis, timestamps, call context	Art. 11

Evidence is saved to .venturalitica/ or a session-specific directory.

---

wrap(model, policy) — Experimental

Caution

PREVIEW: This function is experimental and its API may change.

Transparently audit your model during Scikit-Learn standard workflows by hooking into .fit() and .predict().

Parameter	Type	Description
model	object	Any Scikit-learn compatible classifier or regressor.
policy	str	Path to the OSCAL policy for evaluation.

Returns: AssuranceWrapper (preserves the original model API: .fit(), .predict(), etc.)

wrapped = vl.wrap(LogisticRegression(), policy="assessment_plan.oscal.yaml")
wrapped.fit(X_train, y_train)
preds = wrapped.predict(X_test)  # Audit runs automatically

---

Utility Class

PolicyManager

Programmatic access to OSCAL policy loading and manipulation. Used by the Streamlit policy editor and any tool that needs to read or write a YAML-serialized policy under a workspace directory.

from venturalitica import PolicyManager

mgr = PolicyManager(target_dir=".venturalitica")
policy = mgr.load()
errors = mgr.validate(policy)
if not errors:
    mgr.save(policy)

Member	Signature	Description
__init__	PolicyManager(target_dir: str)	Resolves the policy file at <target_dir>/model_policy.oscal.yaml. (For new v0.6.0 workflows, prefer the unified assessment_plan.oscal.yaml written by vl pull; PolicyManager is intended for the simplified editor schema.)
load()	() -> Dict[str, Any]	Reads the policy YAML and returns it as a dict. Returns a stub {"title": "New Policy", "controls": []} if the file does not exist. Legacy list-only files are wrapped under a controls key.
save(data)	(Dict[str, Any]) -> bool	Validates the basic shape (title is required) and writes the dict back as YAML. Raises ValueError if title is missing.
validate(data)	(Dict[str, Any]) -> List[str]	Returns a list of human-readable error strings (empty if valid). Checks for title, a controls list, and required fields (id, metric_key, operator, threshold) on each control.
get_schema()	staticmethod -> Dict[str, Any]	Returns the JSON Schema (Draft-07) describing the simplified policy shape.

---

Data Types

ComplianceResult

Every call to enforce() returns a list of ComplianceResult dataclass instances:

Field	Type	Description
control_id	str	The control identifier from the policy (e.g., "credit-data-bias").
description	str	Human-readable description of the control.
metric_key	str	The metric function used (e.g., "disparate_impact").
actual	float	The computed metric value.
threshold	float	The policy-defined threshold.
operator	str	Comparison operator (">", "<", ">=", "<=", "==", "gt", "lt").
passed	bool	Whether the control passed.

for r in results:
    print(f"{r.control_id}: {r.actual:.3f} {'PASS' if r.passed else 'FAIL'}")