isaf-logger 0.2.0

Instruction Stack Audit Framework - Automatic compliance logging for AI systems

ISAF Logger

Instruction Stack Audit Framework - Automatic compliance logging for AI systems

Add 3 lines of code, get EU AI Act-ready documentation with cryptographic verification.

Quick Start

import isaf

# Initialize (one line)
isaf.init()

# Add decorators to your training functions
@isaf.log_data(source="customer_data", version="3.2.1")
def load_training_data():
    return pd.read_csv("data.csv")

@isaf.log_objective(name="binary_crossentropy", constraints=["fairness < 0.05"])
def train_model(data):
    model = create_model()
    model.fit(data)
    return model

# Log inference with human oversight (EU AI Act Article 14)
@isaf.log_inference(threshold=0.5, human_oversight=True, model_version="1.0.0")
def predict(input_data):
    return model.predict(input_data)

# Run training and inference as normal
data = load_training_data()
model = train_model(data)
predictions = predict(test_data)

# Export compliance report (one line)
isaf.export("compliance_report.json")

Installation

pip install isaf-logger

Features

• 3 Lines of Code: Minimal integration with existing ML pipelines
• Full Stack Coverage: Logs Layers 6-9 (Framework, Data, Objectives, Deployment)
• Cryptographic Verification: SHA-256 hash chains prove lineage integrity
• Compliance Ready: Maps to EU AI Act, NIST AI RMF, ISO 42001, Colorado AI Act
• Framework Agnostic: Works with PyTorch, TensorFlow, JAX, scikit-learn
• Flexible Storage: SQLite for local, MLflow for production

What Gets Logged

Layer 6: ML Framework

• Framework versions (PyTorch, TensorFlow, etc.)
• CUDA availability and configuration
• Default parameters and numerical precision
• System environment (Python version, OS, processor)

Layer 7: Training Data

• Data source and version
• Dataset shape, dtypes, missing values
• Data hash for provenance tracking
• Preprocessing operations

Layer 8: Objective Function

• Loss function name and mathematical form
• Constraints and regularization terms
• Hyperparameters (learning rate, batch size, etc.)
• Business justification

Layer 9: Deployment/Inference (NEW)

• Decision thresholds and confidence cutoffs
• Human oversight configuration
• Model version and deployment environment
• Inference mode (single, batch, streaming)
• Fallback actions and escalation rules

Compliance Mappings

ISAF automatically maps your logged data to regulatory requirements:

• EU AI Act: Article 10 (Data Governance), Article 11 (Technical Documentation)
• NIST AI RMF: MEASURE-2.2, GOVERN-1.1
• ISO 42001: Section 8.4 (Control of externally provided AI)
• Colorado AI Act: SB24-205 (Impact Assessment Documentation)

CLI Tools

# Inspect lineage file
isaf inspect compliance_report.json

# Verify cryptographic integrity
isaf verify compliance_report.json

# Export from database
isaf export-from-db lineage.db --output report.json

# List sessions
isaf list-sessions lineage.db

Advanced Usage

Custom Storage Backend

# SQLite (default)
isaf.init(backend='sqlite', db_path='my_lineage.db')

# MLflow
isaf.init(backend='mlflow', tracking_uri='http://localhost:5000')

# Memory only (testing)
isaf.init(backend='memory')

Compliance Export

# Export with compliance mappings
isaf.export(
    'compliance_report.json',
    include_hash_chain=True,
    compliance_mappings=['eu_ai_act', 'nist_ai_rmf', 'iso_42001']
)

Verification

# Verify lineage integrity
verified = isaf.verify_lineage('compliance_report.json')
print(f"Verification: {'PASSED' if verified else 'FAILED'}")

Examples

PyTorch Example

import torch
import isaf

isaf.init()

@isaf.log_data(source='internal', version='1.0')
def load_data():
    return torch.utils.data.TensorDataset(X, y)

@isaf.log_objective(name='cross_entropy')
def train(model, data):
    optimizer = torch.optim.Adam(model.parameters())
    for epoch in range(10):
        # training loop
        pass
    return model

data = load_data()
model = train(model, data)
isaf.export('pytorch_lineage.json')

scikit-learn Example

from sklearn.ensemble import RandomForestClassifier
import isaf

isaf.init()

@isaf.log_data(source='synthetic', version='1.0')
def load_data():
    from sklearn.datasets import make_classification
    return make_classification(n_samples=1000, n_features=20)

@isaf.log_objective(name='gini_impurity', constraints=['max_depth=10'])
def train_model(X, y):
    model = RandomForestClassifier(max_depth=10)
    model.fit(X, y)
    return model

X, y = load_data()
model = train_model(X, y)
isaf.export('sklearn_lineage.json')

Inference with Human Oversight

import isaf

isaf.init()

# Log inference with EU AI Act Article 14 compliance
@isaf.log_inference(
    threshold=0.5,
    human_oversight=True,
    review_threshold=0.7,  # Flag for human review below this confidence
    model_version="2.0.0",
    model_name="loan_classifier",
    fallback_action="flag"  # What to do when confidence is low
)
def classify_loan_application(application_data):
    prediction = model.predict(application_data)
    confidence = model.predict_proba(application_data).max()
    return {'prediction': prediction, 'confidence': confidence}

# Multi-class thresholds
@isaf.log_inference(
    thresholds={'approve': 0.8, 'deny': 0.9, 'review': 0.5},
    human_oversight=True,
    inference_mode='batch'
)
def batch_classify(applications):
    return model.predict(applications)

result = classify_loan_application(new_application)
isaf.export('inference_lineage.json', compliance_mappings=['eu_ai_act'])

Documentation

• Homepage: https://haiec.com/isaf
• Full Documentation: https://haiec.com/isaf/docs
• GitHub: https://github.com/haiec/isaf-logger
• Issues: https://github.com/haiec/isaf-logger/issues

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT License - see LICENSE file for details.

Citation

If you use ISAF Logger in your research, please cite:

@software{isaf_logger,
  title = {ISAF Logger: Instruction Stack Audit Framework},
  author = {HAIEC Lab},
  year = {2025},
  url = {https://github.com/haiec/isaf-logger}
}

Support

• Email: [e-mail]
• Enterprise Support: https://haiec.com/contact
• Community: GitHub Discussions

---

Built by HAIEC - Human AI Ethics & Compliance