> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhara.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Company name is Akhara AI (never Rubric AI). Keep lowercase rubric/rubrics only when meaning grading criteria.
> Expert Review (docs path talent/) is enterprise BYO experts for audit and review: invite customer specialists; do not pitch Akhara recruiting or a public expert career portal. RLHF and domain writing are secondary work types.
> Prefer concrete API examples against public hosts: Environments eval API https://agi.akhara.ai, Control plane PDP https://api.akhara.dev, Evaluation https://app.akhara.ai / https://api.akhara.ai, Expert Review portal https://talent.akhara.ai.
> Do not invent a public hostname for private orchestrators or env API internals.
> Do not confuse control-plane latches with Environments confirmation latches.
> Environments SDK/API examples: curl against https://agi.akhara.ai. Evaluation SDK: from akhara import Akhara and AKHARA_API_KEY.
> Start with /llms.txt for the docs index and OpenAPI links; fetch individual pages as .md exports.

# Audit & Provenance Pipeline

> Complete audit trail architecture, event capture, tamper-proof storage, compliance reporting, and data provenance.

## Overview

Healthcare AI evaluation requires comprehensive audit trails for compliance, debugging, and accountability. Akhara captures every action with cryptographic integrity guarantees.

```mermaid theme={null}
flowchart LR
    A[Action Occurs] --> B[Capture Event]
    B --> C[Sign & Hash]
    C --> D[Store Immutably]
    D --> E[Index for Query]
```

## Audit Architecture

### Core Principles

<CardGroup cols={2}>
  <Card title="Complete Capture" icon="eye">
    Every action, access, and change is logged
  </Card>

  <Card title="Immutability" icon="lock">
    Audit records cannot be modified or deleted
  </Card>

  <Card title="Cryptographic Integrity" icon="shield-halved">
    Hash chains prevent tampering
  </Card>

  <Card title="Queryable" icon="magnifying-glass">
    Fast search across billions of events
  </Card>
</CardGroup>

### Event Flow

```mermaid theme={null}
flowchart TB
    subgraph Capture
        A[API Request] --> B[Event Interceptor]
        C[Service Action] --> B
        D[Data Access] --> B
    end
    
    subgraph Process
        B --> E[Enrich Metadata]
        E --> F[Compute Hash]
        F --> G[Chain to Previous]
        G --> H[Sign Event]
    end
    
    subgraph Store
        H --> I[Write to Timestream]
        H --> J[Replicate to S3]
        H --> K[Index in OpenSearch]
    end
```

## Event Categories

### Event Types

| Category              | Event Types                                                   | Retention |
| --------------------- | ------------------------------------------------------------- | --------- |
| **Data Events**       | `sample.created`, `sample.updated`, `sample.deleted`          | 7 years   |
| **Evaluation Events** | `evaluation.started`, `evaluation.completed`, `score.created` | 7 years   |
| **Review Events**     | `task.assigned`, `review.submitted`, `consensus.reached`      | 7 years   |
| **Access Events**     | `phi.accessed`, `export.requested`, `api.called`              | 7 years   |
| **System Events**     | `config.changed`, `user.invited`, `role.updated`              | 7 years   |
| **Export Events**     | `export.started`, `export.completed`, `export.downloaded`     | 7 years   |

### Event Schema

```json theme={null}
{
  "event_id": "evt_abc123def456",
  "timestamp": "2025-01-15T10:30:00.123Z",
  "event_type": "review.submitted",
  
  "actor": {
    "type": "user",
    "id": "user_xyz789",
    "email": "dr.smith@hospital.org",
    "role": "reviewer",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0...",
    "session_id": "sess_abc123"
  },
  
  "resource": {
    "type": "review",
    "id": "rev_def456",
    "project": "proj_ghi789",
    "organization": "org_jkl012"
  },
  
  "action": {
    "type": "create",
    "details": {
      "task_id": "task_mno345",
      "sample_id": "smp_pqr678",
      "scores": {
        "triage_correct": "under_triaged",
        "red_flags_caught": "all"
      }
    }
  },
  
  "context": {
    "request_id": "req_stu901",
    "correlation_id": "corr_vwx234",
    "source": "review_ui"
  },
  
  "integrity": {
    "content_hash": "sha256:a1b2c3d4...",
    "previous_hash": "sha256:e5f6g7h8...",
    "chain_position": 1847293,
    "signature": "sig_yza567..."
  }
}
```

## Cryptographic Integrity

### Hash Chain

```mermaid theme={null}
flowchart LR
    A[Event N-1<br/>hash: abc123] --> B[Event N<br/>prev: abc123<br/>hash: def456]
    B --> C[Event N+1<br/>prev: def456<br/>hash: ghi789]
```

Each event includes:

* **Content Hash**: SHA-256 of event payload
* **Previous Hash**: Hash of the preceding event
* **Chain Position**: Sequential position in the chain
* **Signature**: KMS-signed hash for non-repudiation

### Verification Process

```mermaid theme={null}
flowchart TB
    A[Load Event] --> B[Recompute Content Hash]
    B --> C{Hash Matches?}
    
    C -->|No| D[TAMPERED]
    C -->|Yes| E[Load Previous Event]
    
    E --> F{Chain Links?}
    F -->|No| G[CHAIN BROKEN]
    F -->|Yes| H[Verify Signature]
    
    H --> I{Signature Valid?}
    I -->|No| J[INVALID SIGNATURE]
    I -->|Yes| K[VERIFIED ✓]
```

### Verification API

```python theme={null}
# Verify audit trail integrity
verification = client.audit.verify(
    start_event="evt_abc123",
    end_event="evt_xyz789"
)

print(f"Events Verified: {verification.events_checked}")
print(f"Chain Intact: {verification.chain_intact}")
print(f"All Signatures Valid: {verification.signatures_valid}")

if not verification.valid:
    for issue in verification.issues:
        print(f"Issue at {issue.event_id}: {issue.description}")
```

## Storage Architecture

### Storage Tiers

```mermaid theme={null}
flowchart TB
    A[New Events] --> B[Hot: Timestream<br/>0-90 days]
    B --> C[Warm: OpenSearch<br/>90 days - 1 year]
    C --> D[Cold: S3 Glacier<br/>1-7 years]
```

| Tier     | Storage           | Retention        | Query Latency    |
| -------- | ----------------- | ---------------- | ---------------- |
| **Hot**  | Amazon Timestream | 0-90 days        | \< 100ms         |
| **Warm** | Amazon OpenSearch | 90 days - 1 year | \< 1s            |
| **Cold** | S3 Glacier        | 1-7 years        | Minutes to hours |

### Immutability Controls

* **S3 Object Lock**: WORM (Write Once Read Many) compliance mode
* **No Delete API**: Audit events have no delete endpoint
* **Append Only**: Events can only be added, never modified
* **Multi-Region**: Replicated to prevent single-point tampering

## Query API

### Basic Queries

```python theme={null}
# Query audit events
events = client.audit.query(
    project="proj_abc123",
    
    filters={
        "event_type": {"$in": ["review.submitted", "score.created"]},
        "timestamp": {
            "$gte": "2025-01-01T00:00:00Z",
            "$lt": "2025-02-01T00:00:00Z"
        },
        "actor.id": "user_xyz789"
    },
    
    order_by="timestamp",
    order="desc",
    limit=100
)

for event in events:
    print(f"{event.timestamp}: {event.event_type} by {event.actor.email}")
```

### PHI Access Tracking

```python theme={null}
# Track all PHI access for a sample
phi_access = client.audit.query(
    filters={
        "event_type": "phi.accessed",
        "resource.id": "smp_abc123"
    }
)

print(f"Total PHI accesses: {len(phi_access)}")
for access in phi_access:
    print(f"  {access.timestamp}: {access.actor.email} - {access.action.details.phi_elements}")
```

### Full-Text Search

```python theme={null}
# Search across all audit events
results = client.audit.search(
    query="chest pain emergency",
    project="proj_abc123",
    event_types=["review.submitted"],
    date_range=("2025-01-01", "2025-01-31")
)
```

## Compliance Reporting

### HIPAA Audit Requirements

| Requirement               | Implementation                                 |
| ------------------------- | ---------------------------------------------- |
| **Access Logging**        | All PHI access logged with user, time, purpose |
| **Modification Tracking** | All changes to PHI logged with before/after    |
| **Disclosure Logging**    | All exports and shares logged                  |
| **User Activity**         | Login, logout, session activity tracked        |
| **System Events**         | Configuration changes, security events logged  |

### Generating Reports

```python theme={null}
# Generate HIPAA compliance report
report = client.compliance.generate_report(
    report_type="hipaa_audit",
    organization="org_abc123",
    period={
        "start": "2025-01-01",
        "end": "2025-03-31"
    },
    include_sections=[
        "phi_access_summary",
        "user_activity",
        "security_events",
        "data_exports",
        "anomaly_detection"
    ]
)

# Download report
report.download("hipaa_audit_q1_2025.pdf")
```

### PHI Access Report

```python theme={null}
# Generate PHI access report for a patient
phi_report = client.compliance.phi_access_report(
    sample_id="smp_abc123",  # or patient_id if tracked
    period={
        "start": "2025-01-01",
        "end": "2025-12-31"
    }
)

print(f"Total Accesses: {phi_report.total_accesses}")
print(f"Unique Users: {phi_report.unique_users}")
print(f"Access Purposes: {phi_report.purposes}")
```

## Real-Time Alerting

### Alert Configuration

```python theme={null}
# Configure audit alerts
client.audit.configure_alerts(
    organization="org_abc123",
    
    alerts=[
        {
            "name": "Unusual PHI Access",
            "condition": {
                "event_type": "phi.accessed",
                "aggregation": "count",
                "threshold": 100,
                "window": "1h",
                "group_by": "actor.id"
            },
            "channels": ["slack:#security", "pagerduty"]
        },
        {
            "name": "Failed Auth Spike",
            "condition": {
                "event_type": "auth.failed",
                "aggregation": "count",
                "threshold": 10,
                "window": "5m"
            },
            "channels": ["pagerduty"]
        },
        {
            "name": "Bulk Export",
            "condition": {
                "event_type": "export.requested",
                "filter": {"action.details.record_count": {"$gt": 1000}}
            },
            "channels": ["email:compliance@company.com"]
        }
    ]
)
```

### Anomaly Detection

```mermaid theme={null}
flowchart TB
    A[Event Stream] --> B[ML Anomaly Detection]
    
    B --> C{Anomaly Score}
    
    C -->|High| D[Alert: Investigate]
    C -->|Medium| E[Flag for Review]
    C -->|Low| F[Normal Logging]
```

Detected patterns:

* Unusual access times (off-hours activity)
* Abnormal data volumes
* New access patterns for users
* Geographic anomalies
* Privilege escalation attempts

## SIEM Integration

### Supported Platforms

| Platform             | Integration Method   |
| -------------------- | -------------------- |
| **Splunk**           | HTTP Event Collector |
| **Datadog**          | Log forwarding       |
| **Sumo Logic**       | HTTP source          |
| **Elastic**          | Logstash/Filebeat    |
| **AWS Security Hub** | Native integration   |
| **Azure Sentinel**   | Webhook              |
| **Chronicle**        | API ingestion        |

### Configuration

```python theme={null}
# Configure SIEM forwarding
client.audit.configure_siem(
    organization="org_abc123",
    
    siem={
        "type": "splunk",
        "endpoint": "https://splunk.company.com:8088",
        "token": "splunk_hec_token",
        
        "filters": {
            "event_types": ["auth.*", "phi.*", "export.*", "security.*"],
            "min_severity": "warning"
        },
        
        "format": "json",
        "batch_size": 100,
        "flush_interval_seconds": 30
    }
)
```

## Data Provenance

### Lineage Tracking

Track the complete history of any data point:

```python theme={null}
# Get full provenance for a score
provenance = client.audit.get_provenance(
    resource_type="score",
    resource_id="scr_abc123"
)

print("Data Lineage:")
for step in provenance.lineage:
    print(f"  {step.timestamp}: {step.action} by {step.actor}")
    
# Output:
# Data Lineage:
#   2025-01-15T10:00:00Z: sample.created by api_key:gr_live_xxx
#   2025-01-15T10:00:05Z: evaluation.queued by system
#   2025-01-15T10:00:30Z: evaluator.executed by system
#   2025-01-15T10:00:35Z: score.created by evaluator:triage_accuracy
#   2025-01-15T10:01:00Z: task.created by system
#   2025-01-15T11:30:00Z: review.submitted by user:dr_smith
#   2025-01-15T11:30:05Z: score.updated by user:dr_smith
```

## Retention & Archival

### Retention Policies

| Data Type       | Minimum Retention | Maximum    | Configurable |
| --------------- | ----------------- | ---------- | ------------ |
| Audit Events    | 7 years           | Indefinite | No           |
| PHI Access Logs | 7 years           | Indefinite | No           |
| System Events   | 3 years           | 7 years    | Yes          |
| Debug Logs      | 90 days           | 1 year     | Yes          |

### Archival Process

```mermaid theme={null}
flowchart LR
    A[Hot Storage<br/>90 days] --> B[Archive Job<br/>Daily]
    B --> C[Warm Storage<br/>1 year]
    C --> D[Archive Job<br/>Monthly]
    D --> E[Cold Storage<br/>7 years]
```

## Best Practices

<AccordionGroup>
  <Accordion title="Enable Comprehensive Logging" icon="list-check">
    Log all access, not just writes:

    ```python theme={null}
    client.projects.update(
        project="patient-triage",
        audit_config={
            "log_reads": True,
            "log_searches": True,
            "include_query_params": True
        }
    )
    ```
  </Accordion>

  <Accordion title="Regular Integrity Checks" icon="shield-check">
    Schedule periodic verification:

    ```python theme={null}
    # Weekly integrity check
    client.audit.schedule_verification(
        schedule="0 2 * * SUN",  # Sunday 2 AM
        scope="full_chain",
        alert_on_failure=True
    )
    ```
  </Accordion>

  <Accordion title="Monitor for Anomalies" icon="chart-line">
    Set up baseline and detect deviations:

    ```python theme={null}
    client.audit.enable_anomaly_detection(
        baseline_period_days=30,
        sensitivity="medium"
    )
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="PHI Handling" icon="user-shield" href="/evaluation/docs/architecture/phi-pii-handling">
    How sensitive data is protected
  </Card>

  <Card title="System Overview" icon="sitemap" href="/evaluation/docs/architecture/overview">
    High-level platform architecture
  </Card>
</CardGroup>