Agentic Compliance

Build an automated compliance auditor where AI agents inspect data, record every reasoning step in a tamper-evident chain-of-thought (CoT) ledger, and produce audit-ready reports. Every decision is hash-chained with SHA-256, creating an immutable record that can be verified for integrity at any time.

Architecture

+---------------+     MCP / SQL      +----------------+     Audit Log      +-----------+
|  Compliance   | ------------------> |  HatiData      | -----------------> |  Object   |
|  Agent        |                     |  Proxy         |                    |  Storage  |
+---------------+                     +--------+-------+                    +-----------+
                                               |
                                         DuckDB Engine
                                       + CoT Ledger (SHA-256)

The compliance agent connects to HatiData, inspects financial or regulatory data via SQL queries, and records every reasoning step in the CoT ledger. Each entry is hash-chained to the previous entry, creating a tamper-evident trail that auditors can verify.

What's Included

• HatiData Proxy -- Query engine with built-in CoT ledger and audit sink
• Demo App -- Python compliance audit agent that inspects financial data

Quick Start

# Clone and start
git clone https://github.com/marviy/hatidata.git
cd hatidata/playbooks/agentic-compliance
docker compose up -d

# Wait for services to be healthy
docker compose ps

# Run the compliance audit
docker compose exec demo-app python app.py

What the Demo Does

1. Loads financial data -- Inserts sample transaction and account data into HatiData
2. Runs compliance checks -- The agent inspects data for policy violations (transaction limits, velocity checks, pattern analysis)
3. Records reasoning -- Every check is hash-chained in the CoT ledger with evidence and conclusions
4. Generates audit report -- Produces a tamper-evident compliance report
5. Verifies chain integrity -- Demonstrates that the hash chain can be verified end-to-end

Key Concepts

Recording Compliance Reasoning

Each compliance check is recorded as a reasoning step with structured evidence. The CoT ledger automatically hash-chains each entry to the previous one using SHA-256.

# Each compliance check is recorded with evidence
client.call_tool("log_reasoning_step", {
    "step": "Checked transaction limits for Account A-1234",
    "evidence": [
        "Max single transaction: $45,000 (limit: $50,000)",
        "Daily aggregate: $120,000 (limit: $200,000)"
    ],
    "conclusion": "PASS -- All transactions within defined limits",
    "confidence": 0.95
})

Verifying the Audit Chain

The hash chain can be verified at any time to confirm that no entries were tampered with, inserted, or deleted after the fact.

# Verify no entries were tampered with
result = client.call_tool("replay_decision", {
    "session_id": "compliance-audit-2024-q4"
})
# result: { valid: true, chain_length: 47, ... }

If any entry in the chain has been modified, the verification will fail because the SHA-256 hash of the modified entry will not match the hash stored in the subsequent entry.

Policy Violation Detection

When the agent detects a potential violation, it records the finding with full evidence in the CoT ledger:

# Agent flags violations with full evidence trail
client.call_tool("log_reasoning_step", {
    "step": "Detected potential structuring in Account B-5678",
    "evidence": [
        "12 transactions of $9,900 in 3-day window",
        "Aggregate: $118,800 (exceeds $100,000 reporting threshold)"
    ],
    "conclusion": "FLAG -- Possible structuring to avoid CTR filing",
    "confidence": 0.88
})

Session History

Retrieve the complete reasoning history for a compliance session:

# Get full session history
history = client.call_tool("get_session_history", {
    "session_id": "compliance-audit-2024-q4"
})
# Returns all reasoning steps with their hash chain

Compliance Use Cases

Use Case	What the Agent Checks
Anti-Money Laundering (AML)	Transaction patterns, structuring detection, velocity anomalies, geographic risk
SOX Compliance	Access controls, segregation of duties, audit trail completeness, approval workflows
GDPR / Privacy	Data retention compliance, consent tracking, access request logs, right-to-erasure verification
Internal Policy	Spending limits, approval thresholds, vendor compliance checks, procurement rules

CoT Ledger Details

Hash Chain Structure

Each reasoning step contains:

Field	Description
session_id	Groups related steps into a compliance session
step_number	Sequential number within the session
step_type	Type of reasoning (observation, analysis, conclusion, etc.)
content	The reasoning step text
evidence	Supporting data points
conclusion	The agent's determination
confidence	Float 0.0-1.0 confidence score
prev_hash	SHA-256 hash of the previous entry
hash	SHA-256 hash of this entry (computed from all fields + prev_hash)
timestamp	UTC timestamp

Step Types

The CoT ledger supports 12 step types for categorizing reasoning:

• observation -- Raw data observation
• analysis -- Analytical reasoning
• hypothesis -- Proposed explanation
• verification -- Checking a hypothesis
• conclusion -- Final determination
• action -- Action taken
• query -- SQL query executed
• result -- Query result summary
• error -- Error encountered
• retry -- Retry attempt
• escalation -- Escalation to human
• approval -- Human approval recorded

Embedding Sampling

To support semantic search over reasoning traces, the CoT ledger optionally generates embeddings for a configurable percentage of entries (default: 10%). Critical step types (conclusion, escalation, approval) are always embedded regardless of the sampling rate.

Configuration

Variable	Default	Description
COT_LEDGER_ENABLED	true	Enable CoT hash-chain ledger
HATIDATA_AUDIT_SINK	local_file	Audit destination (local_file, s3, gcs, noop)
HATIDATA_AUDIT_PATH	/var/lib/hatidata/audit	Audit log directory for local file sink
HATIDATA_DEV_MODE	true	Skip auth for local development

Cleanup

docker compose down -v  # Remove containers and volumes

Next Steps

• Agentic RAG -- Semantic memory for AI agents
• Agentic DataOps -- Branch isolation for speculative queries
• Security Overview -- Security architecture and audit logging