autoicd 0.2.0

Official Python SDK for the AutoICD API — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP

AutoICD API — Python SDK

Official Python SDK for the AutoICD API — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP.

Single dependency (httpx). Works in Python 3.10+.

Built for EHR integrations, health-tech platforms, medical billing, clinical decision support, and revenue cycle management.

---

Why AutoICD API

AI-Powered ICD-10 Coding	Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM codes — no manual lookup required
74,000+ ICD-10-CM Codes	Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching
Negation & Context Detection	Knows the difference between "patient has diabetes" and "patient denies diabetes" — flags negated, historical, uncertain, and family-history mentions
PHI De-identification	HIPAA-compliant anonymization of names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages
Confidence Scoring	Every code match includes a similarity score and confidence level so you can set your own acceptance thresholds
Spell Correction	Handles misspellings in clinical text — "diabeties" still maps to the right code
Fully Typed	Complete type annotations for all requests and responses

---

Install

pip install autoicd

uv / poetry / pdm

uv add autoicd
poetry add autoicd
pdm add autoicd

---

Quick Start

from autoicd import AutoICD

client = AutoICD(api_key="sk_...")

result = client.code(
    "Patient has type 2 diabetes and essential hypertension"
)

for entity in result.entities:
    print(entity.entity_text, "→", entity.codes[0].code)
# "type 2 diabetes"       → "E11.9"
# "essential hypertension" → "I10"

---

Features

Automated ICD-10 Medical Coding

Extract diagnosis entities from clinical notes and map them to ICD-10-CM codes. Each entity includes ranked candidates with confidence scores, negation status, and context flags.

result = client.code(
    "History of severe COPD with acute exacerbation. Patient denies chest pain."
)

for entity in result.entities:
    print(entity.entity_text)
    print(f"  Negated: {entity.negated}")
    print(f"  Historical: {entity.historical}")
    for match in entity.codes:
        print(
            f"  {match.code} — {match.description} "
            f"({match.confidence}, {match.similarity * 100:.1f}%)"
        )

Fine-tune results with coding options:

from autoicd import CodeOptions

result = client.code(
    "Patient presents with acute bronchitis and chest pain",
    options=CodeOptions(
        top_k=3,               # Top 3 ICD-10 candidates per entity (default: 5)
        strategy="merged",     # "individual" or "merged" entity strategy
        include_negated=False, # Exclude negated conditions from results
    ),
)

ICD-10 Code Search

Search the full ICD-10-CM 2025 code set by description. Perfect for building code lookup UIs, autocomplete fields, and validation workflows.

results = client.codes.search("diabetes mellitus")
# results.codes → [CodeDetail(code="E11.9", short_description="...", ...), ...]

from autoicd import SearchOptions
results = client.codes.search("heart failure", options=SearchOptions(limit=5))

ICD-10 Code Details

Get full details for any ICD-10-CM code — descriptions, billable status, and indexed terms.

detail = client.codes.get("E11.9")
print(detail.code)              # "E11.9"
print(detail.long_description)  # "Type 2 diabetes mellitus without complications"
print(detail.is_billable)       # True

ICD-10 Code Terms & Synonyms

Retrieve all indexed terms and synonyms for a code — includes SNOMED CT mappings and clinical variants.

terms = client.codes.terms("E11.9")
for t in terms:
    print(t.term, f"({t.term_type})")
# "Type 2 diabetes mellitus without complications" (long_desc)
# "adult onset diabetes" (synonym)
# ...

PHI De-identification

Strip protected health information from clinical notes before storage or analysis. HIPAA-compliant de-identification for names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages.

result = client.anonymize(
    "John Smith, DOB 01/15/1980, MRN 123456, has COPD"
)

print(result.anonymized_text)
# "[NAME], DOB [DATE], MRN [MRN], has COPD"

print(result.pii_count)     # 3
print(result.pii_entities)  # [PIIEntity(text="John Smith", label="NAME", ...), ...]

---

Use Cases

• EHR / EMR Integration — Auto-code clinical notes as providers type, reducing manual coding burden
• Medical Billing & RCM — Accelerate claim submission with accurate ICD-10 codes
• Clinical Decision Support — Map patient conditions to standardized codes for analytics and alerts
• Health-Tech SaaS — Add ICD-10 coding to your platform without building ML infrastructure
• Clinical Research — Extract and standardize diagnoses from unstructured medical records
• Insurance & Payer Systems — Validate and suggest diagnosis codes during claims processing
• Telehealth Platforms — Generate diagnosis codes from visit notes and transcriptions

---

Error Handling

from autoicd import (
    AutoICD,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.code("...")
except AuthenticationError:
    # Invalid or revoked API key (401)
    ...
except RateLimitError as e:
    # Request limit exceeded (429)
    print(e.rate_limit.remaining, e.rate_limit.reset_at)
except NotFoundError:
    # ICD-10 code not found (404)
    ...

Rate limit info is available after every request:

client.code("...")
print(client.last_rate_limit)
# RateLimit(limit=1000, remaining=987, reset_at=datetime(...))

---

Configuration

client = AutoICD(
    api_key="sk_...",                   # Required — get yours at https://autoicdapi.com
    base_url="https://...",             # Default: https://autoicdapi.com
    timeout=60.0,                       # Default: 30.0 seconds
    http_client=httpx.Client(...),      # Custom httpx client (for proxies, mTLS, etc.)
)

Use as a context manager for automatic cleanup:

with AutoICD(api_key="sk_...") as client:
    result = client.code("Patient has diabetes")

---

API Reference

Full REST API documentation at autoicdapi.com/docs.

Method	Description
client.code(text, options?)	Code clinical text to ICD-10-CM diagnoses
client.anonymize(text)	De-identify PHI/PII in clinical text
client.codes.search(query, options?)	Search ICD-10-CM codes by description
client.codes.get(code)	Get details for an ICD-10-CM code
client.codes.terms(code)	Get indexed terms/synonyms for a code

---

Types

All request and response types are exported:

from autoicd import (
    CodingResponse,
    CodingEntity,
    CodeMatch,
    CodeOptions,
    CodeDetail,
    CodeSearchResponse,
    CodeTermInfo,
    AnonymizeResponse,
    PIIEntity,
    RateLimit,
    SearchOptions,
)

---

Requirements

• Python 3.10+
• An API key from autoicdapi.com

---

Links

• AutoICD API — Homepage and API key management
• API Documentation — Full REST API reference
• TypeScript SDK — npm install autoicd
• ICD-10-CM 2025 Code Set — Official CMS reference

---

License

MIT