How to Set Up Compliance Templates (HIPAA, SOC 2, EU AI Act) with Soup

Use soup init --template <hipaa|soc2|eu-ai-act> to generate a pre-configured compliance workflow, then execute the regulatory CLI commands prescribed in the generated soup.yaml file.

Soup transforms regulatory requirements into ready-to-use training configurations through a template-based compliance system. The open-source repository MakazhanAlpamys/Soup separates static configuration from dynamic compliance actions, letting you audit the same model under different regimes without editing YAML files. This article explains how to set up HIPAA, SOC 2, and EU AI Act templates using the three-layer architecture: the Template Registry, the Init Command, and the Compliance Runtime.

Understanding the Compliance Architecture

Template Registry: Centralized Manifest

All compliance starters live in src/soup_cli/templates/manifest.json. This JSON file maps human-readable names to YAML config files:

// src/soup_cli/templates/manifest.json - registry structure
{
  "templates": {
    "hipaa": "templates/hipaa.yaml",
    "soc2": "templates/soc2.yaml",
    "eu-ai-act": "templates/eu-ai-act.yaml"
  }
}

The list_templates() function queries this manifest to present available options via the CLI.

Init Command: Materialize Your Template

The soup init command in src/soup_cli/commands/init.py performs the actual setup:

# Conceptual flow in src/soup_cli/commands/init.py

def load_template(template_name):
    manifest = read_manifest("src/soup_cli/templates/manifest.json")
    template_path = manifest.resolve(template_name)  # e.g., hipaa.yaml

    return inject_compliance_guidance(template_path)

Key implementation detail: load_template(template) reads the YAML and writes it to your target file (default soup.yaml). The template contains standard training config plus header comments that list required CLI steps—not configuration keys.

Compliance Runtime: Execute Regulatory Controls

After initialization, you run compliance-specific commands that are orthogonal to the training config:

Command Category	Purpose	Example Commands
Data handling	PII removal, decontamination	soup data pii, soup data decontaminate
Audit logging	Immutable command history	soup audit-log tail
Provenance	Artifact tracking	soup bom emit, soup attest emit
Signing	Cryptographic verification	soup adapters sign
Air-gap bundling	Secure transfer	soup airgap-bundle

This separation ensures the same soup.yaml works for both compliant and non-compliant runs.

Setting Up HIPAA Compliance

The HIPAA template (src/soup_cli/templates/hipaa.yaml) targets Protected Health Information (PHI) protection with full audit trails.

Step-by-Step Initialization

# 1. Generate the HIPAA starter config

soup init --template hipaa

# 2. Review the compliance steps embedded in the file

cat soup.yaml

Complete HIPAA Workflow

# Data sanitization: flag and remove PHI

soup data pii ./data/train.jsonl
soup data decontaminate ./data/train.jsonl

# Verify audit logging is active (enabled by default in HIPAA template)

soup audit-log tail

# Train with reproducibility receipt capturing who/what/when

soup train --config soup.yaml --repro-receipt receipt.json

# Generate provenance artifacts

soup bom emit \
    --name phi-model \
    --base-sha <sha> \
    --config-sha <sha> \
    --format both

# Cryptographically sign the model

soup adapters sign ./output --backend ed25519 --generate-key key.pem
soup attest emit \
    --stage train \
    --subject phi-model \
    --sha <sha> \
    --sign ed25519 \
    --key key.pem

# Air-gap bundle for secure zone transfer (no PHI leaves boundary)

soup airgap-bundle \
    --model ./output \
    --output phi-model.tar \
    --repro-receipt receipt.json

# Generate model card for downstream documentation

soup card phi-model -o MODELCARD.md

Critical HIPAA controls implemented:

• PII detection and removal before training
• Automatic audit logging of all commands
• Reproducibility receipts for regulatory inspection
• Signed attestations of training provenance
• Air-gap capability for isolated environments

Setting Up SOC 2 Compliance

The SOC 2 template (src/soup_cli/templates/soc2.yaml) emphasizes change management and trust services criteria.

Initialization and Workflow

# Initialize SOC 2 template

soup init --template soc2

# Execute change-management focused workflow

soup audit-log tail

# Lock environment state for reproducibility

soup lock write \
    --base-sha <base> \
    --dataset-sha <data> \
    --env-lock soup-env.lock

# Train with full provenance capture

soup train --config soup.yaml --repro-receipt receipt.json

# Standard provenance and signing

soup bom emit --name model --base-sha <sha> --config-sha <sha> --format both
soup adapters sign ./output --backend ed25519 --generate-key key.pem
soup attest emit --stage train --subject model --sha <sha> --sign ed25519 --key key.pem

# CI gate: automated ship/no-ship decision

soup ship --evidence ev.json   # Exit 0 = SHIP, Exit 2 = DON'T SHIP

The soup ship command provides the automated control assessment required by SOC 2 CC6.1 and CC7.2 trust criteria.

Setting Up EU AI Act Compliance

The EU AI Act template (src/soup_cli/templates/eu-ai-act.yaml) targets Annex XI/XII documentation and energy transparency requirements for high-risk AI systems.

Initialization and Workflow

# Initialize EU AI Act template

soup init --template eu-ai-act

# Execute compliance workflow with energy tracking

soup data decontaminate ./data/train.jsonl
soup data pii ./data/train.jsonl

# Train with mandatory Annex XI documentation and energy metrics

soup train --config soup.yaml \
    --annex-xi annex_xi.md \
    --track-energy \
    --energy-country DEU \
    --energy-out energy.json

# Emit BOM with energy documentation included

soup bom emit \
    --name model \
    --base-sha <sha> \
    --config-sha <sha> \
    --energy energy.json \
    --format both

# Final audit verification

soup audit-log tail

Key EU AI Act requirements addressed:

• Annex XI technical documentation (--annex-xi flag)
• Energy consumption tracking by country (--track-energy, --energy-country)
• Conformity assessment artifacts via soup bom emit

CI/CD Integration for Automated Compliance

Use soup ci init to generate a GitHub Actions workflow that blocks pull requests until compliance checks pass:

soup ci init  # Creates .github/workflows/soup-compliance.yml

The generated workflow runs:

• soup data validate — verify data meets template requirements
• soup expect — assert compliance predicates
• soup ship --evidence ev.json — final gate check

Key Source Files Reference

File Path	Purpose
docs/compliance.md	Complete quick-start guide for all regulatory templates
src/soup_cli/commands/init.py	Implements soup init --template <name>
src/soup_cli/templates/manifest.json	Central registry of available templates
src/soup_cli/templates/hipaa.yaml	PHI-focused template with audit requirements
src/soup_cli/templates/soc2.yaml	Change-management and trust services template
src/soup_cli/templates/eu-ai-act.yaml	Annex XI/XII and energy tracking template

Summary

• One command initializes any compliance regime: soup init --template <hipaa|soc2|eu-ai-act>
• Templates contain guidance, not locks — compliance is enforced through CLI flags, not config keys
• Same config, multiple audits — run soup train with different compliance flags for different regulatory contexts
• Immutable provenance — soup bom emit, soup attest emit, and soup adapters sign create regulator-ready evidence
• CI automation — soup ci init gates releases on compliance verification

The separation of configuration from compliance actions in MakazhanAlpamys/Soup keeps training pipelines clean while satisfying HIPAA, SOC 2, and EU AI Act requirements through executable, auditable commands.

Frequently Asked Questions

What is the difference between soup init and running compliance commands directly?

soup init only materializes a starter YAML file with embedded guidance. The actual compliance enforcement happens through separate CLI commands you execute around soup train. This design lets you reuse the same soup.yaml for both compliant and non-compliant runs, switching regimes by changing flags rather than editing configuration files.

Can I use multiple compliance templates for the same model?

Yes. Because compliance is command-driven rather than config-driven, you can train once and then run different compliance command sequences against the same artifacts. For example, generate both HIPAA and SOC 2 attestations from the same training run by executing both command workflows with appropriate flags.

Where does Soup store the audit logs required for HIPAA and SOC 2?

Audit logs are captured automatically when using compliance templates—soup audit-log tail displays the immutable command history. The src/soup_cli/commands/init.py implementation ensures the HIPAA template enables logging by default, and soup.lock files preserve environment state for reproducibility verification.

How does EU AI Act energy tracking work in practice?

The --track-energy flag instruments the training process to record consumption metrics, with --energy-country specifying the grid carbon intensity lookup (e.g., DEU for Germany). The resulting energy.json is bundled into the BOM via --energy energy.json, creating the documentation required by Annex XI for high-risk AI system registration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}