Lesson 12: Compliance Modes And Regulated Workflows

Lesson Goal

By the end of this lesson, you should be able to:

• Explain why regulated industries require stricter AI controls than general use.
• Select the correct PolicyMode for a given industry context.
• Configure PHI scrubbing, immutable audit, and compliance profiles.
• Build a compliant workflow for healthcare (HIPAA) and finance (SOX).
• Understand what each compliance flag does and what it does not do.

Estimated time: 40 to 55 minutes.

1. Why Compliance Is A First-Class Concern

Most software engineering concerns are about correctness and performance. In regulated industries, a third dimension is mandatory: governance. A healthcare AI that leaks patient identifiers, or a financial AI that lacks an audit trail, can result in regulatory fines, legal liability, and public harm — even if the output was factually correct.

MeshFlow treats compliance as a runtime concern, not an afterthought. You configure it once at the policy level, and the runtime enforces it for every run.

2. The PolicyMode Enum

PolicyMode sets the baseline behavior of the governance stack:

from meshflow.core.schemas import Policy, PolicyMode

policy = Policy(mode=PolicyMode.HIPAA, budget_usd=5.0)

Setting a mode is a shortcut. Under the hood it sets several individual flags. You can always override individual flags after setting the mode.

3. The compliance= Keyword

The compliance= keyword activates a full regulatory profile from a string:

policy = Policy(compliance="hipaa", budget_usd=5.0)
policy = Policy(compliance="sox",   budget_usd=5.0)
policy = Policy(compliance="gdpr",  budget_usd=5.0)
policy = Policy(compliance="pci",   budget_usd=5.0)

This is useful when the compliance mode is determined at runtime from configuration or environment variables rather than hardcoded.

4. PHI Scrubbing

Protected Health Information (PHI) includes names, dates of birth, social security numbers, medical record numbers, phone numbers, and email addresses. HIPAA requires that PHI not be stored or transmitted unnecessarily.

policy = Policy(scrub_phi=True)

With scrub_phi=True, the MeshFlow runtime scans every output for known PHI patterns and replaces them with redaction markers before the artifact is stored in the ledger:

Patient John Doe (SSN: 123-45-6789) → Patient John Doe (SSN: [SSN_REDACTED])

Important caveats:

• Scrubbing is pattern-based and will miss novel PHI formats.
• It applies to stored artifacts, not to what the LLM processes internally.
• For strong HIPAA compliance, the LLM itself should not receive raw PHI.

Use de-identification at ingestion, not only at output.

5. Immutable Audit

policy = Policy(immutable_audit=True)

When immutable_audit=True, the ledger refuses delete_run and similar mutation operations. Attempts to delete or modify a completed run raise a PolicyViolationError. This is a defense against accidental or malicious deletion of compliance records.

Combine with verify_chain on a schedule to detect any tampering that bypasses the application layer (for example, direct database edits).

6. Require Human Review

policy = Policy(require_human_review=True)

Every run must include at least one human approval record in the ledger. If the workflow completes without a HITL gate having been reached, the ledger records a compliance warning. Use this for regulated workflows where a human must be in the loop on every decision.

7. Collusion And Drift Detection

In multi-agent workflows, one agent may influence another inappropriately — for example, a researcher embedding instructions in its output that change the writer's behavior. This is called collusion.

policy = Policy(enable_collusion_audit=True)

When enabled, MeshFlow monitors agent outputs for instruction-injection patterns. The run result contains a collusion_alerts list. In standard mode this list is empty. If a pattern is detected, it contains a description of the suspicious output and which agents were involved.

8. SOX Financial Workflow Example

A SOX-regulated financial analysis workflow requires:

• Full audit trail for every calculation
• Human approval before any disclosure is sent
• Immutable records that cannot be altered after the run
• Collusion detection to prevent one agent from manipulating another

policy = Policy(
    mode=PolicyMode.SOX,
    immutable_audit=True,
    require_human_review=True,
    enable_collusion_audit=True,
    budget_usd=10.0,
)

The ledger will record every step, the human approval event, and the chain hash. The compliance team can verify the chain at any time.

9. HIPAA Healthcare Workflow Example

A HIPAA-compliant patient-data workflow requires:

• PHI scrubbed from all stored outputs
• Full audit trail
• Human approval before any patient-facing communication
• Immutable records

policy = Policy(
    compliance="hipaa",
    scrub_phi=True,
    immutable_audit=True,
    require_human_review=True,
)

Additionally: do not send raw PHI to a third-party LLM provider without a Business Associate Agreement (BAA) in place.

10. What Compliance Modes Do Not Cover

• They do not make your LLM provider HIPAA-compliant. That requires a BAA.
• They do not replace legal review of your workflow design.
• They do not prevent incorrect outputs — only govern how they are produced and

stored.

• PHI scrubbing is pattern-based and imperfect. It supplements, does not replace,

upstream de-identification.

11. Hands-On Lab

MESHFLOW_MOCK=1 python3 hands_on/12_compliance_modes.py

Observe the output table showing which controls are active per mode, the PHI scrubbing demo, the SOX workflow trace, and the LEGAL_CRITICAL contract review output. Compare the ledger entry counts across modes.

12. Summary

PolicyMode and the compliance= keyword activate graduated levels of governance. As you move from DEV → STANDARD → REGULATED → HIPAA, more controls become mandatory. Individual flags like scrub_phi, immutable_audit, and require_human_review let you customize beyond the preset levels. Compliance configuration belongs at the policy layer, not scattered through application code.

Exercises

Exercise 1: Run All Compliance Modes and Observe Differences

Goal: See how different PolicyMode values change the behavior and output of an identical workflow.

Instructions:

1. Run the hands-on script:

   python hands_on/12_compliance_modes.py

1. The script runs the same sample workflow under each of the six compliance modes in sequence and prints labeled output blocks.
2. For each mode, record:

- Was an audit ledger entry created? (yes/no) - Was PHI scrubbing applied? (yes/no) - Was a human review gate inserted? (yes/no) - Did the workflow complete in "fast path" (no gates) or "gated path"?

1. Build a simple 6-row comparison table in your notes with these four columns.

Expected output: Six labeled output blocks, each showing mode name, step results, and any policy-triggered events (scrubbing, gates, citation blocks). DEV mode should be the fastest; LEGAL_CRITICAL and HIPAA should show the most intervention.

---

Exercise 2: Trigger PHI Scrubbing Manually

Goal: Understand exactly which patterns scrub_phi detects and replaces.

Instructions:

1. Open a Python REPL and import the PHI scrubber:

   from meshflow.compliance import scrub_phi

1. Call scrub_phi on strings containing each of the following PHI categories:

- A person's full name: "Patient: Jane Doe" - A date of birth: "DOB: 04/12/1983" - An email address: "Contact: jane.doe@hospital.org" - A US Social Security Number: "SSN: 123-45-6789" - A phone number: "Phone: (555) 867-5309" - A diagnosis code combined with a name: "Jane Doe diagnosed with ICD-10 E11.9"

1. Print each result and record the replacement token used (e.g., [PHI:NAME], [PHI:DATE], etc.).
2. Try a sentence that has no PHI and confirm it passes through unchanged.

Expected output: Each PHI-containing string returns with the sensitive portion replaced by a tagged placeholder. The no-PHI string is returned verbatim.

---

Exercise 3: Observe immutable_audit in REGULATED Mode

Goal: Confirm that immutable_audit prevents run deletion.

Instructions:

1. Run 12_compliance_modes.py and note the run_id of the REGULATED mode run (printed in the output).
2. In a Python REPL, attempt to delete that run:

   from meshflow.ledger import ReplayLedger
   ledger = ReplayLedger()
   run_id = "<the_regulated_run_id>"
   try:
       ledger.delete_run(run_id)
       print("Deleted (unexpected!)")
   except Exception as e:
       print(f"Blocked: {e}")

1. Confirm that an exception is raised. Record the exception type and message.
2. Now find the DEV mode run ID and attempt the same deletion. Confirm it succeeds (DEV mode does not enforce immutability).
3. Write a one-sentence explanation of why this asymmetry exists between DEV and REGULATED modes.

Expected output: delete_run on the REGULATED run raises an ImmutableAuditError (or similar). The DEV run deletion succeeds silently.

---

Exercise 4: Add require_human_review to a Custom Workflow

Goal: Implement a human-in-the-loop gate and observe the workflow pause.

Instructions:

1. Create a short Python script (my_hipaa_test.py) that defines a two-step workflow with HIPAA compliance:

   from meshflow import MeshFlow, PolicyMode

   app = MeshFlow(compliance=PolicyMode.HIPAA)

   @app.agent("data_ingestion")
   def ingest(input):
       return {"patient_count": 42, "raw_data": "..."}

   @app.agent("report_generator", require_human_review=True)
   def generate_report(input):
       return {"report": "Summary of 42 patients..."}

   result = app.run({"query": "monthly summary"})
   print(result)

1. Run the script. Observe what happens when the workflow reaches report_generator — it should pause and either prompt you (interactive) or log a human review request (non-interactive/test mode).
2. If it prompts you, type approve or reject and observe the outcome.
3. Try running the same script with compliance=PolicyMode.DEV and require_human_review=True still set. Does the gate still activate? Record your finding.

Expected output: In HIPAA mode, the workflow pauses at the human review gate. In DEV mode, the gate is typically bypassed or logged-only, not blocking.

---

Exercise 5: Inspect Collusion Detection Logs

Goal: Understand what collusion detection flags and how to read its output.

Instructions:

1. Run 12_compliance_modes.py and look for any lines in the output labeled [COLLUSION_ALERT] or similar.
2. If the script includes a collusion demo section, read the description of the scenario: two agents are both accessing the same sensitive data source and producing outputs that are suspiciously correlated.
3. In a Python REPL, enable LEGAL_CRITICAL mode and inspect the collusion log:

   from meshflow import MeshFlow, PolicyMode
   from meshflow.compliance import get_collusion_log

   app = MeshFlow(compliance=PolicyMode.LEGAL_CRITICAL)
   # (run your workflow here or use the one from the hands-on script)
   log = get_collusion_log(app.last_run_id)
   for entry in log:
       print(entry)

1. Review the fields in each collusion log entry. Identify:

- Which agents were flagged. - What behavioral pattern triggered the flag (e.g., shared data access, correlated outputs, circular referencing). - The severity level assigned.

1. Write two to three sentences explaining why collusion detection matters in a multi-agent legal or financial workflow.

Expected output: A list of collusion log entries (may be empty if no collusion patterns were triggered). If the script's demo does trigger an alert, you will see at least one entry with agent_a, agent_b, pattern, and severity fields.