> ## 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.

# PHI/PII Handling Model

> How Akhara protects sensitive patient data, detection, de-identification, encryption, access controls, and compliance.

## Overview

Healthcare AI evaluation inherently involves sensitive patient data. Akhara implements defense-in-depth protections for Protected Health Information (PHI) and Personally Identifiable Information (PII) throughout the data lifecycle.

<Warning>
  Akhara is designed to HIPAA requirements; the compliance program and BAA process are in progress. A Business Associate Agreement (BAA) is required before processing PHI. Contact [sales@akhara.ai](mailto:sales@akhara.ai) for current BAA status.
</Warning>

## Data Classification

### PHI Categories

| Category                 | Examples                              | Sensitivity |
| ------------------------ | ------------------------------------- | ----------- |
| **Direct Identifiers**   | Name, SSN, MRN, phone, email, address | Critical    |
| **Indirect Identifiers** | DOB, ZIP, dates of service            | High        |
| **Clinical Data**        | Diagnoses, medications, vitals, notes | High        |
| **Genetic/Biometric**    | DNA, fingerprints, voice prints       | Critical    |
| **Images**               | Photos, X-rays, pathology             | High        |

### PII Categories

| Category              | Examples                    | Treatment   |
| --------------------- | --------------------------- | ----------- |
| **Direct PII**        | Name, email, phone          | De-identify |
| **Quasi-Identifiers** | Age, gender, location       | Generalize  |
| **Behavioral**        | Usage patterns, preferences | Anonymize   |

## PHI Detection Pipeline

```mermaid theme={null}
flowchart TB
    A[Incoming Data] --> B[Format Detection]
    
    B --> C[PHI Detection Engines]
    
    subgraph Engines
        C --> D[Regex Rules]
        C --> E[NER Model]
        C --> F[Pattern Match]
        C --> G[Custom Rules]
    end
    
    D --> H[PHI Locations + Types]
    E --> H
    F --> H
    G --> H
    
    H --> I[Confidence Scoring]
    I --> J[PHI Report]
```

### Detection Methods

<AccordionGroup>
  <Accordion title="Regex Pattern Matching" icon="magnifying-glass">
    Fast detection of structured identifiers:

    | Pattern | Example                  | Precision |
    | ------- | ------------------------ | --------- |
    | SSN     | `\d{3}-\d{2}-\d{4}`      | 99%       |
    | Phone   | `\(\d{3}\) \d{3}-\d{4}`  | 98%       |
    | Email   | RFC 5322 pattern         | 99%       |
    | MRN     | Client-specific patterns | 95%       |
    | Date    | Multiple formats         | 90%       |

    ```python theme={null}
    # Example patterns
    patterns = {
        "SSN": r"\b\d{3}-\d{2}-\d{4}\b",
        "PHONE": r"\b\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b",
        "EMAIL": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
        "DATE": r"\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b"
    }
    ```
  </Accordion>

  <Accordion title="NER Model Detection" icon="brain">
    ML-based detection for unstructured text:

    **Model**: Fine-tuned Clinical BERT on i2b2/n2c2 datasets

    **Entity Types**:

    * `PERSON` - Patient and provider names
    * `LOCATION` - Addresses, facilities
    * `DATE` - Dates of service, DOB
    * `ID` - MRN, account numbers
    * `CONTACT` - Phone, fax, email
    * `AGE` - Patient age mentions

    ```python theme={null}
    # Detection example
    text = "John Smith, DOB 03/15/1965, was seen at Main St Clinic"

    entities = phi_detector.detect(text)
    # [
    #   {"text": "John Smith", "type": "PERSON", "start": 0, "end": 10},
    #   {"text": "03/15/1965", "type": "DATE", "start": 16, "end": 26},
    #   {"text": "Main St Clinic", "type": "LOCATION", "start": 40, "end": 54}
    # ]
    ```
  </Accordion>

  <Accordion title="Image PHI Detection" icon="image">
    For DICOM and clinical images:

    * **Burned-in annotations**: OCR detection of text overlays
    * **DICOM headers**: Automatic tag scanning
    * **Face detection**: For photos with patient faces

    ```python theme={null}
    # DICOM PHI tags scanned
    PHI_DICOM_TAGS = [
        (0x0010, 0x0010),  # Patient Name
        (0x0010, 0x0020),  # Patient ID
        (0x0010, 0x0030),  # Patient Birth Date
        (0x0010, 0x1000),  # Other Patient IDs
        (0x0008, 0x0080),  # Institution Name
        (0x0008, 0x0081),  # Institution Address
        # ... 50+ additional tags
    ]
    ```
  </Accordion>
</AccordionGroup>

## De-identification Options

### De-identification Modes

| Mode             | Description                        | Use Case                       |
| ---------------- | ---------------------------------- | ------------------------------ |
| **None**         | PHI preserved as-is                | BAA in place, full data needed |
| **Redact**       | Replace PHI with `[REDACTED]`      | When PHI not needed for eval   |
| **Pseudonymize** | Replace with consistent fake data  | When relationships matter      |
| **Generalize**   | Reduce precision (age → age range) | Statistical analysis           |

### Configuration

```python theme={null}
# Configure de-identification per project
client.projects.update(
    project="patient-triage",
    
    phi_config={
        "mode": "pseudonymize",
        
        "rules": {
            # Names → Consistent fake names
            "PERSON": {
                "method": "pseudonymize",
                "preserve_format": True
            },
            
            # Dates → Shift by random offset
            "DATE": {
                "method": "date_shift",
                "max_shift_days": 365,
                "preserve_relationships": True
            },
            
            # Ages → Generalize to ranges
            "AGE": {
                "method": "generalize",
                "buckets": [[0, 17], [18, 44], [45, 64], [65, 89], [90, 120]]
            },
            
            # Locations → Redact
            "LOCATION": {
                "method": "redact"
            },
            
            # Direct IDs → Hash
            "ID": {
                "method": "hash",
                "salt": "project_specific_salt"
            }
        },
        
        "always_detect": True,
        "log_detections": True
    }
)
```

### De-identification Example

**Original Text:**

```
John Smith (DOB: 03/15/1965, MRN: 12345678) presented to 
Main Street Clinic on 01/10/2025 with chest pain. 
Dr. Sarah Johnson ordered an EKG.
```

**Pseudonymized:**

```
Robert Chen (DOB: 07/22/1964, MRN: [HASH:a3f2b1]) presented to 
[REDACTED] on 05/18/2024 with chest pain. 
Dr. Emily Martinez ordered an EKG.
```

## Encryption Architecture

### Encryption at Rest

```mermaid theme={null}
flowchart TB
    KMS[AWS KMS HSM] --> Master[Master Key]
    Master --> DataKeys[Data Keys]
    
    DataKeys --> Aurora[(Aurora TDE)]
    DataKeys --> DocDB[(DocumentDB TDE)]
    DataKeys --> S3[(S3 SSE-KMS)]
    DataKeys --> Redis[(Redis TLS+disk)]
```

**Encryption**: AES-256-GCM\
**Key Rotation**: Automatic (annual) or on-demand

### Encryption in Transit

| Connection         | Protocol | Certificate  |
| ------------------ | -------- | ------------ |
| Client → API       | TLS 1.3  | Public CA    |
| Service → Service  | mTLS     | Internal PKI |
| Service → Database | TLS 1.2+ | AWS RDS CA   |
| Service → S3       | HTTPS    | AWS CA       |

### Key Management

```yaml theme={null}
# Key hierarchy
AWS KMS Master Key (HSM-backed):
  - Project Data Key (per project):
      - Sample Encryption Key
      - Audio Encryption Key
      - DICOM Encryption Key
  - Audit Log Key
  - Backup Encryption Key
```

## Access Control

### Role-Based Access Control (RBAC)

```mermaid theme={null}
flowchart TB
    User[User] --> Role[Role<br/>Owner/Admin/Member/Reviewer]
    Role --> Permissions[Permissions]
    
    Permissions --> Read[Read]
    Permissions --> Write[Write]
    Permissions --> Admin[Admin]
    
    User --> Project[Project Membership]
    Project --> Scoped[Scoped to Project]
```

### Permission Matrix

| Action            | Owner | Admin | Member | Reviewer | Viewer |
| ----------------- | ----- | ----- | ------ | -------- | ------ |
| View samples      | ✅     | ✅     | ✅      | ✅\*      | ✅      |
| Create samples    | ✅     | ✅     | ✅      | ❌        | ❌      |
| Delete samples    | ✅     | ✅     | ❌      | ❌        | ❌      |
| Run evaluations   | ✅     | ✅     | ✅      | ❌        | ❌      |
| Submit reviews    | ✅     | ✅     | ✅      | ✅        | ❌      |
| Manage team       | ✅     | ✅     | ❌      | ❌        | ❌      |
| Access audit logs | ✅     | ✅     | ❌      | ❌        | ❌      |
| Delete project    | ✅     | ❌     | ❌      | ❌        | ❌      |

\*Reviewers can only view samples assigned to them

### Minimum Necessary Access

Akhara enforces minimum necessary access principles:

```python theme={null}
# Reviewer sees only assigned samples
GET /v1/samples?assigned_to=me

# Response contains only:
{
  "id": "smp_abc123",
  "input": {...},        # Clinical content for review
  "output": {...},       # AI decision to evaluate
  # NO access to: other samples, raw audio URLs, full metadata
}
```

## Audit Logging

All PHI access is logged:

```json theme={null}
{
  "event_id": "evt_abc123",
  "timestamp": "2025-01-15T10:30:00Z",
  "event_type": "phi.access",
  
  "actor": {
    "user_id": "user_xyz789",
    "role": "reviewer",
    "ip_address": "192.0.2.1"
  },
  
  "resource": {
    "type": "sample",
    "id": "smp_def456",
    "project": "proj_ghi789"
  },
  
  "action": "read",
  
  "phi_elements_accessed": [
    "transcript",
    "ai_decision"
  ],
  
  "context": {
    "task_id": "task_jkl012",
    "purpose": "clinical_review"
  }
}
```

See [Audit & Provenance Pipeline](/evaluation/docs/architecture/audit-provenance) for complete audit documentation.

## Compliance Controls

### HIPAA Technical Safeguards

| Safeguard                 | Implementation                              |
| ------------------------- | ------------------------------------------- |
| **Access Control**        | RBAC, MFA, session management               |
| **Audit Controls**        | Comprehensive logging, tamper-proof storage |
| **Integrity**             | Checksums, digital signatures               |
| **Transmission Security** | TLS 1.3, mTLS for internal                  |
| **Encryption**            | AES-256 at rest, TLS in transit             |

### Data Residency

| Region  | Location      | Designed for               |
| ------- | ------------- | -------------------------- |
| US      | AWS us-east-1 | HIPAA (in progress)        |
| US-West | AWS us-west-2 | HIPAA (in progress)        |
| EU      | AWS eu-west-1 | HIPAA + GDPR (in progress) |
| Custom  | Your VPC      | Enterprise                 |

<Info>
  Data never leaves the configured region. Cross-region replication is disabled by default and requires explicit configuration with compliance review.
</Info>

## Configuration Reference

### Project PHI Settings

```python theme={null}
client.projects.update(
    project="patient-triage",
    
    phi_config={
        "mode": "pseudonymize",
        "detection_threshold": 0.8,
        "custom_patterns": [...],
        "rules": {...},
        "log_all_access": True,
        "log_phi_locations": True,
        "phi_retention_days": 365,
        "auto_delete_on_expiry": True
    },
    
    encryption_config={
        "key_id": "alias/project-key",
        "algorithm": "AES-256-GCM"
    },
    
    access_config={
        "require_mfa": True,
        "session_timeout_minutes": 30,
        "ip_allowlist": ["192.0.2.0/24"]
    }
)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Minimize PHI Collection" icon="minimize">
    Only collect PHI that's necessary for evaluation:

    ```python theme={null}
    # Consider de-identified upload
    client.log(
        transcript=[...],  # De-identified before upload
        phi_config={"mode": "none"}  # Already clean
    )
    ```
  </Accordion>

  <Accordion title="Use Test Data for Development" icon="flask">
    Never use production PHI in development:

    ```python theme={null}
    # Development: use a test workspace with synthetic data
    client = Akhara(
        api_key="gr_test_xxx"
    )
    ```
  </Accordion>

  <Accordion title="Regular Access Reviews" icon="user-check">
    Periodically review who has access to PHI:

    ```python theme={null}
    # Get access report
    report = client.compliance.access_report(
        project="patient-triage",
        period_days=90
    )
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Audit Pipeline" icon="scroll" href="/evaluation/docs/architecture/audit-provenance">
    Complete audit trail architecture
  </Card>

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