# hipaa-agent

Python SDK for [HIPAA Agent](https://hipaaagent.ai) — the autonomous AI HIPAA compliance officer for healthcare practices.

30 typed methods covering scanning, grading, breach intelligence, compliance tracking, document generation, and more. Built-in retries, rate-limit handling, and optional LangChain/LlamaIndex integrations.

## Installation

```bash
pip install hipaa-agent
```

With LangChain integration:
```bash
pip install hipaa-agent[langchain]
```

With LlamaIndex integration:
```bash
pip install hipaa-agent[llama-index]
```

Both:
```bash
pip install hipaa-agent[all]
```

## Quick Start

```python
from hipaa_agent import HIPAAAgent

client = HIPAAAgent(api_key="ha_live_...")

# Get compliance grade
score = client.get_compliance_score("1234567890")
print(f"Grade: {score['grade']}, Score: {score['score']}")

# Check breach history
breach = client.get_breach(entity_name="Example Health")
print(f"Breaches found: {len(breach)}")

# Look up a practice by NPI
practice = client.lookup_practice("1234567890")
print(f"Practice: {practice['name']}")
```

## Authentication

Get your API key at [hipaaagent.ai/developers](https://hipaaagent.ai/developers). Keys use the format `ha_live_*` (production) or `ha_test_*` (sandbox).

```python
client = HIPAAAgent(
    api_key="ha_live_...",
    base_url="https://hipaaagent.ai",  # default
    timeout=120.0,                      # seconds, default 120
    max_retries=3,                      # default 3
)
```

## Methods

### Scanning

| Method | Description | Credits |
|--------|-------------|---------|
| `scan(npi, domain?)` | Launch 73-tool HIPAA compliance scan | 150 |
| `get_scan_status(scan_id)` | Poll scan status | 25 |
| `batch_scan(targets)` | Queue multiple practices (max 50) | 150/ea |
| `get_compliance_score(npi)` | HIPAA Agent Compliance Score (10 categories) | 25 |

### Reports & Evidence

| Method | Description | Credits |
|--------|-------------|---------|
| `get_report(npi)` | Full findings with HIPAA citations | 25 |
| `get_audit_log(npi)` | SHA-256 hash chain audit trail | 25 |
| `get_evidence_package(npi)` | 10-component evidence bundle | 25 |

### Documents

| Method | Description | Credits |
|--------|-------------|---------|
| `generate_baa(vendor_name, npi?)` | Business Associate Agreement | 25 |
| `get_policies(category?)` | 18 HIPAA policy documents | 25 |
| `generate_sra(npi)` | Security Risk Assessment | 500 |

### Breach Intelligence

| Method | Description | Credits |
|--------|-------------|---------|
| `get_breach(entity_name?, state?)` | HHS breach records | 25 |
| `get_breach_score(npi)` | Breach risk scoring | 25 |
| `get_breach_probability(npi)` | 12-month breach probability | 25 |

### Internal Network

| Method | Description | Credits |
|--------|-------------|---------|
| `trigger_internal_scan(npi, agent_id)` | Deploy network agent | 25 |
| `get_internal_scan_status(scan_id)` | Agent status | 25 |
| `get_internal_findings(scan_id)` | Internal findings | 25 |

### Practice Info

| Method | Description | Credits |
|--------|-------------|---------|
| `lookup_practice(npi)` | NPPES lookup + scan data | 25 |
| `get_outreach_status(npi)` | Outreach/drip status | 25 |
| `get_practice_summary(npi)` | Comprehensive summary | 25 |

### Platform

| Method | Description | Credits |
|--------|-------------|---------|
| `get_training_status(npi)` | Staff training modules | 25 |
| `get_vendor_baa_list(npi)` | Vendor BAA records | 25 |
| `log_incident(npi, title, severity?)` | Log security incident | 25 |
| `get_incidents(npi, status?)` | Incident history | 25 |

### Controls & Compliance

| Method | Description | Credits |
|--------|-------------|---------|
| `get_controls(npi)` | 13 HIPAA/NIST control signals | 25 |
| `validate_workflow(workflow_type, npi?)` | HIPAA workflow guardrail | 25 |
| `get_compliance_state(npi)` | May 2026 deadline tracker | 25 |
| `get_compliance_delta(npi, since?)` | Compliance change detection | 25 |
| `check_vendor(vendor_name, vendor_domain?)` | Vendor risk graph | 25 |

### Webhooks

| Method | Description | Credits |
|--------|-------------|---------|
| `subscribe_webhook(url, events)` | Register webhook | 25 |
| `list_webhooks()` | List active subscriptions | 25 |

## Context Manager

```python
with HIPAAAgent(api_key="ha_live_...") as client:
    score = client.get_compliance_score("1234567890")
    # Connection automatically closed on exit
```

## Error Handling

```python
from hipaa_agent.client import (
    HIPAAAgentError,       # Base exception
    AuthenticationError,   # 401/403
    RateLimitError,        # 429 after retries exhausted
    ServerError,           # 5xx after retries exhausted
    ValidationError,       # Invalid parameters
)

try:
    result = client.scan(npi="1234567890")
except AuthenticationError:
    print("Check your API key")
except RateLimitError:
    print("Rate limited — try again later")
except ValidationError as e:
    print(f"Invalid input: {e}")
```

## Retry Behavior

The client automatically retries on transient failures:

- **Retryable status codes:** 429, 500, 502, 503
- **Backoff schedule:** 1s, 2s, 4s (exponential)
- **Retry-After header:** Respected when present on 429 responses
- **Max retries:** 3 (configurable)
- **Non-retryable:** 401, 403, 404, 400 (fail immediately)

## LangChain Integration

```python
from hipaa_agent.tools import get_langchain_tools
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

tools = get_langchain_tools(api_key="ha_live_...")
llm = ChatOpenAI(model="gpt-4")

agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
result = agent.run("What is the HIPAA compliance grade for NPI 1234567890?")
```

## LlamaIndex Integration

```python
from hipaa_agent.tools import HIPAAAgentToolSpec

tool_spec = HIPAAAgentToolSpec(api_key="ha_live_...")
tools = tool_spec.to_tool_list()
```

## Requirements

- Python 3.9+
- `httpx >= 0.24.0`
- `pydantic >= 2.0.0`

## Links

- [Documentation](https://hipaaagent.ai/developers)
- [API Reference](https://hipaaagent.ai/openapi.json)
- [Get API Key](https://hipaaagent.ai/developers)

## License

MIT
