hipaa-agent

Python SDK for HIPAA Agent — 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

pip install hipaa-agent

With LangChain integration:

pip install hipaa-agent[langchain]

With LlamaIndex integration:

pip install hipaa-agent[llama-index]

Both:

pip install hipaa-agent[all]

Quick Start

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. Keys use the format ha_live_* (production) or ha_test_* (sandbox).

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

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

Error Handling

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

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

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
• API Reference
• Get API Key

License

MIT