soup-cli 0.71.2__tar.gz → 0.71.3__tar.gz

{soup_cli-0.71.2 → soup_cli-0.71.3}/CHANGELOG.md

@@ -12,6 +12,41 @@ reproducing 70+ versions of notes.
 
 ## [Unreleased]
 
+## [0.71.3] - 2026-06-01
+
+### Added
+- **Energy & CO2 measurement for training** — `soup train --track-energy` wraps
+  the training window in a codecarbon **offline** tracker (no IP-geolocation
+  network call) and reports kWh / CO2 / grid intensity, feeding those numbers
+  into `--annex-xi`. New `EnergyTracker` context manager; graceful no-op when
+  codecarbon is absent (`pip install soup-cli[carbon]`). `--energy-country`
+  picks the ISO-3166 alpha-3 grid for the CO2 estimate (default `USA`).
+- **PDF Annex XI/XII documents** — `soup train --annex-xi report.pdf` now renders
+  a reportlab PDF (a `.md` path still renders markdown). `pip install
+  soup-cli[pdf]`.
+- **Auto-populated training-corpus domains in Annex XI/XII** — the top crawled
+  domains (with shares) are now extracted from the training JSONL and listed in
+  the EU AI Act docs, replacing the previous empty placeholder.
+- **Soup Can manifest v3 with embedded attestations** — `soup can pack --attest
+  <statement.json>` (repeatable) embeds in-toto Statements into a v3 can
+  manifest; v1/v2 cans still load. Each statement is shape- and size-validated.
+- **Local audit log auto-instrumentation** — every `soup` command now appends one
+  HIPAA/SOC2-shaped record to `~/.soup/audit.jsonl` (secrets redacted, args
+  capped). Opt out per-invocation with `--no-audit-log` or globally with
+  `SOUP_NO_AUDIT_LOG=1`. Tail/rotate with `soup audit-log`.
+- **Reproducibility receipt in airgap bundles** — `soup airgap-bundle
+  --repro-receipt <receipt.json>` embeds an SR 11-7 receipt as
+  `repro-receipt.json`; auto-detected from `<model>/repro-receipt.json` when not
+  supplied.
+
+### Security
+- `soup can pack --attest` now rejects oversize attestation files by their raw
+  size *before* parsing them into memory (defence against memory-exhaustion).
+- The new file-loading paths (attestation JSON, airgap receipt, training-corpus
+  scan, PDF write) are all cwd-contained + TOCTOU symlink-rejected and
+  size-capped; the audit auto-log redacts `hf_`/`sk-`/`Bearer` tokens and never
+  crashes the CLI on a broken log.
+
 ## [0.71.2] - 2026-06-01
 
 ### Added

{soup_cli-0.71.2 → soup_cli-0.71.3}/CONTRIBUTING.md

@@ -33,6 +33,8 @@ This installs:
   pulled in too (since v0.71.0 these are an opt-in extra, not core deps)
 - `cryptography` — `[dev]` also pulls it in (it's the `[sign]` extra) so the
   ed25519 signing tests (`soup adapters sign` / `soup attest`) run in CI
+- `reportlab` — `[dev]` also pulls it in (it's the `[pdf]` extra) so the
+  Annex XI/XII PDF tests (`soup train --annex-xi *.pdf`) run in CI
 
 ### 3. Verify Setup
 
@@ -118,7 +120,7 @@ src/soup_cli/
   templates/          - 17 built-in soup.yaml templates (YAML + manifest.json) with load_template loader (v0.39.0, +bco v0.40.0)
   ui/                 - Web UI (FastAPI + HTML/JS SPA)
 
-tests/                - Test suite (272 files, 12259 tests)
+tests/                - Test suite (273 files, 12342 tests)
 examples/             - Real-world config examples and datasets
 ```
 

{soup_cli-0.71.2 → soup_cli-0.71.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soup-cli
-Version: 0.71.2
+Version: 0.71.3
 Summary: Fine-tune LLMs in one command. No SSH, no config hell.
 Project-URL: Homepage, https://github.com/MakazhanAlpamys/Soup
 Project-URL: Repository, https://github.com/MakazhanAlpamys/Soup
@@ -39,6 +39,8 @@ Requires-Dist: librosa>=0.10.0; extra == 'audio'
 Requires-Dist: soundfile>=0.12.0; extra == 'audio'
 Provides-Extra: awq
 Requires-Dist: autoawq>=0.2.0; extra == 'awq'
+Provides-Extra: carbon
+Requires-Dist: codecarbon>=2.0.0; extra == 'carbon'
 Provides-Extra: cce
 Requires-Dist: cut-cross-entropy>=24.10.0; extra == 'cce'
 Provides-Extra: data
@@ -59,6 +61,7 @@ Requires-Dist: peft>=0.7.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: reportlab>=4.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: torch>=2.0.0; extra == 'dev'
 Requires-Dist: transformers<5.0.0,>=4.36.0; extra == 'dev'
@@ -80,6 +83,8 @@ Requires-Dist: mlx-lm>=0.20.0; extra == 'mlx'
 Requires-Dist: mlx>=0.20.0; extra == 'mlx'
 Provides-Extra: onnx
 Requires-Dist: optimum[onnxruntime]>=1.16.0; extra == 'onnx'
+Provides-Extra: pdf
+Requires-Dist: reportlab>=4.0.0; extra == 'pdf'
 Provides-Extra: qat
 Requires-Dist: torchao>=0.4.0; extra == 'qat'
 Provides-Extra: remote
@@ -178,19 +183,19 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.2 — Governance & supply-chain live.** Real signatures and supply-chain gates:
-
-- **ed25519 signing** — `soup adapters sign --backend ed25519 --key priv.pem` (or `--generate-key`)
-  produces a real detached signature over the adapter's Merkle root; `soup adapters verify
-  --public-key trusted.pem` does cryptographic authentication. Same for `soup attest emit
-  --sign ed25519` + the new `soup attest verify`. Install with `pip install soup-cli[sign]`.
-- **Anti-AI-Jacking namespace pin** — Hub model downloads now refuse a repo whose author silently
-  changed (or whose creation date jumped backward), the classic namespace-re-creation attack.
-- **License-conflict gate at merge** — `soup adapters merge` auto-detects each adapter's license
-  (from `adapter_config.json` / model card) and refuses incompatible combinations unless you pass
-  `--license-override <reason>` (logged to the audit trail).
-- **Backdoor-scan gate at merge** — refuses to merge any adapter that `soup adapters scan` flags
-  FAIL unless you pass `--allow-unscanned`.
+**v0.71.3 — Compliance / annex / audit / energy.** The EU AI Act + carbon + audit surfaces go live:
+
+- **Energy & CO2 measurement** — `soup train --track-energy` measures the training window with an
+  offline carbon tracker (no network) and reports kWh / CO2, feeding them into the Annex doc.
+  Install with `pip install soup-cli[carbon]`.
+- **PDF compliance docs** — `soup train --annex-xi report.pdf` now renders a real PDF of the
+  EU AI Act Annex XI/XII (a `.md` path still gives markdown). The top crawled domains of your
+  training corpus are auto-listed. `pip install soup-cli[pdf]`.
+- **Per-command audit log** — every `soup` command appends one HIPAA/SOC2 record to
+  `~/.soup/audit.jsonl` (secrets redacted). Opt out with `--no-audit-log` or `SOUP_NO_AUDIT_LOG=1`.
+- **Signed Soup Cans + airgap receipts** — `soup can pack --attest statement.json` embeds in-toto
+  attestations into a can; `soup airgap-bundle --repro-receipt receipt.json` ships a reproducibility
+  receipt inside the offline bundle.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.2 → soup_cli-0.71.3}/README.md

@@ -49,19 +49,19 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.2 — Governance & supply-chain live.** Real signatures and supply-chain gates:
-
-- **ed25519 signing** — `soup adapters sign --backend ed25519 --key priv.pem` (or `--generate-key`)
-  produces a real detached signature over the adapter's Merkle root; `soup adapters verify
-  --public-key trusted.pem` does cryptographic authentication. Same for `soup attest emit
-  --sign ed25519` + the new `soup attest verify`. Install with `pip install soup-cli[sign]`.
-- **Anti-AI-Jacking namespace pin** — Hub model downloads now refuse a repo whose author silently
-  changed (or whose creation date jumped backward), the classic namespace-re-creation attack.
-- **License-conflict gate at merge** — `soup adapters merge` auto-detects each adapter's license
-  (from `adapter_config.json` / model card) and refuses incompatible combinations unless you pass
-  `--license-override <reason>` (logged to the audit trail).
-- **Backdoor-scan gate at merge** — refuses to merge any adapter that `soup adapters scan` flags
-  FAIL unless you pass `--allow-unscanned`.
+**v0.71.3 — Compliance / annex / audit / energy.** The EU AI Act + carbon + audit surfaces go live:
+
+- **Energy & CO2 measurement** — `soup train --track-energy` measures the training window with an
+  offline carbon tracker (no network) and reports kWh / CO2, feeding them into the Annex doc.
+  Install with `pip install soup-cli[carbon]`.
+- **PDF compliance docs** — `soup train --annex-xi report.pdf` now renders a real PDF of the
+  EU AI Act Annex XI/XII (a `.md` path still gives markdown). The top crawled domains of your
+  training corpus are auto-listed. `pip install soup-cli[pdf]`.
+- **Per-command audit log** — every `soup` command appends one HIPAA/SOC2 record to
+  `~/.soup/audit.jsonl` (secrets redacted). Opt out with `--no-audit-log` or `SOUP_NO_AUDIT_LOG=1`.
+- **Signed Soup Cans + airgap receipts** — `soup can pack --attest statement.json` embeds in-toto
+  attestations into a can; `soup airgap-bundle --repro-receipt receipt.json` ships a reproducibility
+  receipt inside the offline bundle.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.2 → soup_cli-0.71.3}/docs/adapters-and-governance.md

@@ -275,6 +275,9 @@ Share a reproducible recipe as a single `.can` file — a tarball of the manifes
 # Pack a registry entry into a .can
 soup can pack --entry-id llama31-chat-v1 --out ./llama31-chat.can
 
+# Embed in-toto attestations into the manifest (v3 cans; repeatable)
+soup can pack --entry-id llama31-chat-v1 --out ./signed.can --attest att.json
+
 # Preview the manifest without extracting
 soup can inspect ./llama31-chat.can
 
@@ -358,29 +361,45 @@ Render an EU AI Act Annex XI (technical documentation, Sections 1+2) or Annex XI
 (Article 53(1)(d) public training summary) directly from a training run:
 
 ```bash
-soup train --config soup.yaml --annex-xi annex.md
+soup train --config soup.yaml --annex-xi annex.md           # markdown
+soup train --config soup.yaml --annex-xi annex.pdf           # PDF (pip install soup-cli[pdf])
+soup train --config soup.yaml --track-energy --annex-xi annex.md  # + measured kWh/CO2
 ```
 
 Top-10 domains by share, modality breakdown, training compute / kWh / CO₂, model
-description, base model, run id. Markdown body now; PDF in v0.59.1. Operator-controlled
-fields are escape-neutralised (`|[](){}!<>` + newline / CR / tab) so a malicious model
-name can't inject a forged heading into downstream PDF/HTML renderers.
+description, base model, run id. A `.pdf` output path renders a reportlab PDF (a `.md`
+path renders markdown). The **top crawled domains** are auto-extracted from the training
+JSONL (`cfg.data.train`). With `--track-energy`, the measured energy is recorded in the
+doc. Operator-controlled fields are escape-neutralised (`|[](){}!<>` + newline / CR / tab)
+so a malicious model name can't inject a forged heading into downstream renderers.
+
+### Energy & CO₂ measurement (`--track-energy`)
+
+`soup train --track-energy` wraps the training window in a codecarbon **offline** tracker
+(no IP-geolocation network call). It reports kWh / CO₂ / grid intensity and feeds them into
+`--annex-xi`. `--energy-country <ISO3>` picks the grid for the CO₂ estimate (default `USA`;
+the kWh figure itself is country-independent). Requires `pip install soup-cli[carbon]`;
+without it, `--track-energy` is a graceful no-op.
 
 
 ## Audit Log (`soup audit-log`)
 
-Tail or rotate the HIPAA/SOC2-shaped JSONL audit log at `~/.soup/audit.jsonl` (override
-via `SOUP_AUDIT_LOG_PATH`, containment-checked to `$HOME / $CWD / $TMPDIR`):
+**Every `soup` command** now appends one HIPAA/SOC2-shaped record to the JSONL audit log at
+`~/.soup/audit.jsonl` (override via `SOUP_AUDIT_LOG_PATH`, containment-checked to
+`$HOME / $CWD / $TMPDIR`). Opt out per-invocation with `soup --no-audit-log <cmd>` or
+globally with `SOUP_NO_AUDIT_LOG=1`. Tail or rotate:
 
 ```bash
 soup audit-log tail --limit 50          # Rich table view
 soup audit-log tail --json              # raw JSONL for SIEM ingestion
 soup audit-log rotate --cap-mb 100      # force a rotation pass
+soup --no-audit-log version             # skip the audit line for this command
 ```
 
 PII redaction across **every** string field (`hf_*` / `sk-*` / `Bearer …` → `<redacted>`)
 via the v0.40.3 `_SECRET_RE` policy. POSIX `O_NOFOLLOW` + `0o600` perms, atomic-append,
-rotation at 100 MiB with symlink rejection at the backup path.
+rotation at 100 MiB with symlink rejection at the backup path. The auto-instrumentation is
+best-effort — a broken audit log never crashes the CLI.
 
 
 ## Reproducibility Receipt (`soup train --repro-receipt`)
@@ -490,7 +509,16 @@ merge with exit 3 unless you pass `--allow-unscanned`.
 
 Single signed tarball with model + datasets + wheels + CUDA kernels +
 embedded `manifest.json` listing SHA-256 per file. Sized for one-way
-physical-media transfer through a data diode. Default 100 GiB cap;
+physical-media transfer through a data diode. A reproducibility receipt is
+embedded as a top-level `repro-receipt.json` when you pass
+`--repro-receipt <receipt.json>` (or auto-detected from
+`<model>/repro-receipt.json`):
+
+```bash
+soup airgap-bundle --model ./out --output bundle.tar --repro-receipt repro.json
+```
+
+Default 100 GiB cap;
 refuses oversize. Deterministic dataset labeling by sorted basename
 (NOT argv order) so the same inputs in different argv order produce
 identical manifests. TOCTOU defence: `os.lstat + S_ISLNK` re-check on

{soup_cli-0.71.2 → soup_cli-0.71.3}/docs/commands.md

@@ -157,7 +157,13 @@ soup adapters check-safetensors <adapter> [--strict]  Refuse pickle / PyTorch-cl
 soup adapters merge ... [--license <id>] [--license-override <reason>] [--allow-unscanned]  License + backdoor-scan gates (auto-detect license; scan FAIL refused)
 soup attest emit ... [--sign ed25519 --key <pem>] [-o att.json]  in-toto/SLSA-3 attestation (+ .sig sidecar)
 soup attest verify <statement> --signature <sig> [--public-key <pem>]  Verify ed25519 attestation signature
-soup airgap-bundle --model <m> --output <out.tar>  Signed tarball for data-diode transfer
+soup airgap-bundle --model <m> --output <out.tar> [--repro-receipt <r.json>]  Signed tarball for data-diode transfer (embeds repro-receipt)
+soup train --config soup.yaml --annex-xi <out.md|out.pdf>  EU AI Act Annex XI/XII doc (markdown or PDF; top_domains auto-filled)
+soup train --config soup.yaml --track-energy [--energy-country USA]  codecarbon offline kWh/CO2 → annex-xi (pip install soup-cli[carbon])
+soup train --config soup.yaml --repro-receipt <out.json>  SR 11-7 reproducibility receipt
+soup can pack --entry-id <id> --out r.can --attest <statement.json>  Embed in-toto Statements into a v3 can manifest
+soup audit-log tail / rotate  Tail / rotate the per-command HIPAA/SOC2 audit log (~/.soup/audit.jsonl)
+soup --no-audit-log <cmd> / SOUP_NO_AUDIT_LOG=1  Opt out of the per-command audit line
 soup eval unlearning <run-id> --benchmark tofu|muse|wmdp  Forget Quality + Model Utility + PrivLeak verdict
 soup edit set --base <m> --method rome|memit|alphaedit --subject "..." --target "..."  Surgical knowledge edit (--plan-only available)
 soup edit diff <before-run> <after-run> --probes p.jsonl  Knowledge-injection diff visualizer

{soup_cli-0.71.2 → soup_cli-0.71.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "soup-cli"
-version = "0.71.2"
+version = "0.71.3"
 description = "Fine-tune LLMs in one command. No SSH, no config hell."
 readme = "README.md"
 license = "Apache-2.0"
@@ -54,7 +54,7 @@ wandb = ["wandb>=0.15.0,<0.18.0"]
 # Self-references `[train]` so CI / contributors get the full training stack
 # (CI runs `pip install -e ".[dev]"`; without this every test would fail at
 # `import torch`).
-dev = ["soup-cli[train]", "cryptography>=41.0.0", "pytest>=7.0", "ruff>=0.1.0", "pytest-cov>=4.0", "httpx>=0.24.0", "mypy>=1.8.0", "pre-commit>=3.5.0"]
+dev = ["soup-cli[train]", "cryptography>=41.0.0", "reportlab>=4.0.0", "pytest>=7.0", "ruff>=0.1.0", "pytest-cov>=4.0", "httpx>=0.24.0", "mypy>=1.8.0", "pre-commit>=3.5.0"]
 ui = ["fastapi>=0.104.0", "uvicorn>=0.24.0"]
 serve = ["fastapi>=0.104.0", "uvicorn>=0.24.0"]
 serve-fast = ["vllm>=0.4.0", "fastapi>=0.104.0", "uvicorn>=0.24.0"]
@@ -89,6 +89,11 @@ data-pro = ["langdetect>=1.0.9", "presidio-analyzer>=2.2.0"]
 # adapters sign`. Pure-offline; Sigstore keyless (OIDC + Fulcio/Rekor network)
 # stays infra-blocked and is NOT bundled here.
 sign = ["cryptography>=41.0.0"]
+# v0.71.3 #181 — reportlab PDF rendering for `soup train --annex-xi *.pdf`.
+pdf = ["reportlab>=4.0.0"]
+# v0.71.3 #180 — codecarbon offline energy/CO2 measurement for
+# `soup train --track-energy` (offline; no IP-geolocation network call).
+carbon = ["codecarbon>=2.0.0"]
 
 [project.scripts]
 soup = "soup_cli.cli:run"

{soup_cli-0.71.2 → soup_cli-0.71.3}/src/soup_cli/__init__.py

@@ -1,3 +1,3 @@
 """Soup CLI — Fine-tune LLMs in one command."""
 
-__version__ = "0.71.2"
+__version__ = "0.71.3"

{soup_cli-0.71.2 → soup_cli-0.71.3}/src/soup_cli/cans/pack.py

@@ -29,6 +29,7 @@ def _add_text(tar: tarfile.TarFile, name: str, content: str) -> None:
 def pack_entry(
     *, entry_id: str, out_path: str, author: str = "unknown",
     description: Optional[str] = None,
+    attestations: Optional[list[dict]] = None,
 ) -> Path:
     """Pack a registry entry as a ``.can`` tarball.
 
@@ -38,6 +39,8 @@ def pack_entry(
             at call time.
         author: author handle baked into the manifest.
         description: optional free-form description.
+        attestations: optional list of embedded in-toto Statements (v0.71.3
+            #182). Each is shape-validated by the manifest schema.
 
     Returns:
         The absolute path to the written file.
@@ -66,6 +69,7 @@ def pack_entry(
         base_hash=entry.get("entry_hash", ""),
         description=description or entry.get("notes"),
         tags=list(entry.get("tags", [])),
+        attestations=list(attestations or []),
     )
 
     out.parent.mkdir(parents=True, exist_ok=True)

{soup_cli-0.71.2 → soup_cli-0.71.3}/src/soup_cli/cans/schema.py

@@ -2,18 +2,48 @@
 
 from __future__ import annotations
 
+import json
 import re
 from typing import Literal, Optional
 
 from pydantic import BaseModel, Field, field_validator
 
-CAN_FORMAT_VERSION = 2  # v0.33.0: deploy_targets + env capture (additive over v1)
-SUPPORTED_CAN_FORMAT_VERSIONS = (1, 2)
+CAN_FORMAT_VERSION = 3  # v0.71.3 #182: attestations field (additive over v2)
+SUPPORTED_CAN_FORMAT_VERSIONS = (1, 2, 3)
 
 _NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-.]{0,127}$")
 _HF_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-./]{0,127}$")
 _HF_REPO_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-.]{0,95}/[A-Za-z0-9][A-Za-z0-9_\-.]{0,95}$")
 
+# v0.71.3 #182 — caps on embedded in-toto attestations.
+_MAX_ATTESTATIONS = 64
+_MAX_ATTESTATION_BYTES = 1024 * 1024  # 1 MiB per statement
+
+
+def validate_attestation_statement(stmt: object) -> dict:
+    """Validate one embedded in-toto Statement dict (v0.71.3 #182).
+
+    Shape-only: must be a dict carrying ``_type`` (str) and ``predicateType``
+    (str), and serialise to <= 1 MiB. Returns the statement unchanged.
+    """
+    if not isinstance(stmt, dict):
+        raise ValueError("attestation must be a dict (in-toto Statement)")
+    type_field = stmt.get("_type")
+    predicate_type = stmt.get("predicateType")
+    if not isinstance(type_field, str) or not type_field:
+        raise ValueError("attestation missing a non-empty '_type' string")
+    if not isinstance(predicate_type, str) or not predicate_type:
+        raise ValueError("attestation missing a non-empty 'predicateType' string")
+    try:
+        size = len(json.dumps(stmt).encode("utf-8"))
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"attestation is not JSON-serialisable: {exc}") from exc
+    if size > _MAX_ATTESTATION_BYTES:
+        raise ValueError(
+            f"attestation too large ({size} > {_MAX_ATTESTATION_BYTES} bytes)"
+        )
+    return stmt
+
 
 class DeployTarget(BaseModel):
     """One declarative deploy target embedded in a can manifest (v2+).
@@ -116,6 +146,23 @@ class Manifest(BaseModel):
         default_factory=list,
         description="Optional declarative deploy targets (v2+)",
     )
+    attestations: list[dict] = Field(
+        default_factory=list,
+        description="Optional embedded in-toto Statements (v3+)",
+    )
+
+    @field_validator("attestations", mode="before")
+    @classmethod
+    def _valid_attestations(cls, value: object) -> list[dict]:
+        if value is None:
+            return []
+        if not isinstance(value, list):
+            raise ValueError("attestations must be a list of in-toto Statements")
+        if len(value) > _MAX_ATTESTATIONS:
+            raise ValueError(
+                f"too many attestations ({len(value)} > {_MAX_ATTESTATIONS})"
+            )
+        return [validate_attestation_statement(s) for s in value]
 
     @field_validator("can_format_version")
     @classmethod

{soup_cli-0.71.2 → soup_cli-0.71.3}/src/soup_cli/cli.py

@@ -1,5 +1,6 @@
 """Main CLI entry point — all commands registered here."""
 
+import os
 import sys
 
 # UTF-8 stdio bootstrap (v0.40.1 Part A) — must run before any Rich console
@@ -71,6 +72,12 @@ console = Console()
 _verbose = False
 # Global log level (resolved string), set by main() callback
 _log_level = "normal"
+# v0.71.3 #183 — audit-log opt-out, set by the --no-audit-log callback flag.
+_audit_disabled = False
+
+# Global options that consume a following value (so the audit command-splitter
+# does not mistake the value for the subcommand name).
+_GLOBAL_VALUE_OPTS = frozenset({"--log-level"})
 
 app = typer.Typer(
     name="soup",
@@ -598,10 +605,20 @@ def main(
         "--log-level",
         help="Logging tier: quiet | normal | verbose | debug",
     ),
+    no_audit_log: bool = typer.Option(
+        False,
+        "--no-audit-log",
+        help=(
+            "Disable the local HIPAA/SOC2 audit log for this invocation "
+            "(also via SOUP_NO_AUDIT_LOG=1). Default: a one-line record per "
+            "command under ~/.soup/audit.jsonl. v0.71.3."
+        ),
+    ),
 ):
     """Soup — fine-tune LLMs in one command."""
-    global _verbose, _log_level
+    global _verbose, _log_level, _audit_disabled
     _verbose = verbose
+    _audit_disabled = no_audit_log
     from soup_cli.utils.log_level import (
         apply_logging_level,
         parse_log_level,
@@ -621,24 +638,114 @@ def main(
     apply_logging_level(tier)
 
 
+def _split_command_args(argv: list[str]) -> tuple[str, list[str]]:
+    """Split ``argv`` into (command, remaining_args) for the audit record.
+
+    Skips the program name (argv[0]) and global options. Global options that
+    take a value (``--log-level``) consume their following token so the value
+    is not mistaken for the subcommand. Returns ``("(root)", [...])`` when no
+    subcommand is present.
+    """
+    tokens = list(argv[1:])
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok in _GLOBAL_VALUE_OPTS:
+            i += 2  # skip the option AND its value (even if the value is "-"-like)
+            continue
+        if isinstance(tok, str) and tok.startswith("-"):
+            i += 1
+            continue
+        return tok, tokens[i + 1:]
+    return "(root)", tokens
+
+
+def _audit_env_opt_out() -> bool:
+    val = (os.environ.get("SOUP_NO_AUDIT_LOG") or "").strip().lower()
+    return val in {"1", "true", "yes", "on"}
+
+
+def _emit_audit_event(argv: list[str], exit_code: int) -> None:
+    """Append one HIPAA/SOC2 audit record for this command. Best-effort.
+
+    v0.71.3 #183 — auto-instrumentation. Disabled by ``--no-audit-log`` /
+    ``SOUP_NO_AUDIT_LOG``. Never raises: a broken audit log must never crash
+    the CLI (mirrors v0.59.0 audit-log fail-soft policy).
+    """
+    if _audit_disabled or _audit_env_opt_out():
+        return
+    try:
+        import getpass
+        import platform
+        from datetime import datetime, timezone
+
+        from soup_cli.utils.audit_log import AuditEvent, append_audit_event
+
+        command, args = _split_command_args(argv)
+        command = (command or "(root)")[:64] or "(root)"
+        try:
+            operator = getpass.getuser() or "unknown"
+        except (OSError, KeyError, ImportError):
+            # getpass.getuser() can raise when no pwd / env user is resolvable.
+            operator = "unknown"
+        host = (platform.node() or "unknown")[:128] or "unknown"
+        operator = (operator or "unknown")[:128] or "unknown"
+        # Defensive re-cap, mirroring audit_log._MAX_ARGS (256) /
+        # _MAX_ARG_LEN (1024) so AuditEvent.__post_init__ never rejects.
+        capped_args = tuple(str(a)[:1024] for a in args[:256])
+        code = exit_code if isinstance(exit_code, int) and not isinstance(
+            exit_code, bool
+        ) else 1
+        ev = AuditEvent(
+            timestamp=datetime.now(tz=timezone.utc).isoformat(),
+            command=command,
+            args=capped_args,
+            exit_code=code,
+            host_id=host,
+            operator_id=operator,
+        )
+        append_audit_event(ev)
+    except Exception:  # noqa: BLE001 — audit must never crash the CLI
+        pass
+
+
 def run():
     """Entry point with friendly error handling."""
     # v0.54.0 — rewrite `soup advise <data>` → `soup advise run <data>`.
     sys.argv = _rewrite_advise_argv(sys.argv)
+    argv_snapshot = list(sys.argv)
     try:
         app()
-    except SystemExit:
+    except SystemExit as exc:
+        code = exc.code
+        if code is None:
+            resolved = 0
+        elif isinstance(code, int) and not isinstance(code, bool):
+            resolved = code
+        else:
+            resolved = 1
+        _emit_audit_event(argv_snapshot, resolved)
         raise
-    except typer.Exit:
+    except typer.Exit as exc:
+        # Defensive/unreachable under click standalone mode (typer.Exit is
+        # converted to SystemExit inside app()); kept so a future click
+        # behaviour change still audits exactly once.
+        _emit_audit_event(argv_snapshot, getattr(exc, "exit_code", 1) or 0)
         raise
     except KeyboardInterrupt:
+        _emit_audit_event(argv_snapshot, 130)
         console.print("\n[yellow]Interrupted.[/]")
         sys.exit(130)
     except Exception as exc:
+        _emit_audit_event(argv_snapshot, 1)
         from soup_cli.utils.errors import format_friendly_error
 
         format_friendly_error(exc, verbose=_verbose)
         sys.exit(1)
+    else:
+        # Defensive/unreachable: app() raises SystemExit(0) on success under
+        # click standalone mode, so this normal-return path rarely fires.
+        _emit_audit_event(argv_snapshot, 0)
 
 
 # When invoked via `soup` entry point, use run() for error handling.