autoicd-js 0.6.0 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-blue.svg)](https://www.typescriptlang.org/)
 
-Official TypeScript SDK for the [AutoICD API](https://autoicdapi.com) — clinical text to ICD-10-CM and ICD-11 diagnosis codes, powered by AI and medical NLP.
+Official TypeScript SDK for the [AutoICD API](https://autoicdapi.com) — AI medical coding that converts clinical text to ICD-10-CM, ICD-11, and ICF codes using medical NLP. Automate ICD-10 coding, ICF functioning classification, and disability assessment in your application.
 
 Zero dependencies. Works in **Node.js 18+**, **Deno**, **Bun**, and **edge runtimes**.
 
@@ -16,9 +16,12 @@ Zero dependencies. Works in **Node.js 18+**, **Deno**, **Bun**, and **edge runti
 
 | | |
 |---|---|
-| **AI-Powered ICD-10 & ICD-11 Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM or ICD-11 codes — no manual lookup required |
+| **AI-Powered ICD-10, ICD-11 & ICF Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM, ICD-11, or ICF codes — no manual lookup required |
+| **Chart Audit with HCC Gap Capture** | Find missed HCCs, unsupported codes, and specificity upgrades with RAF-weighted revenue estimates (CMS v22 + v28 PY2026). Every finding carries evidence spans |
+| **Cross-Standard Code Translation** | Map a code between ICD-10, ICD-11, SNOMED CT, UMLS, and ICF in one call. Forward ICD-10 → all other systems, plus reverse ICD-11 → ICD-10 and ICF → ICD-10 |
 | **74,000+ ICD-10-CM Codes** | Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching |
 | **ICD-11 Support** | Search and look up ICD-11 codes, with full ICD-10 ↔ ICD-11 crosswalk mappings |
+| **ICF Functioning Codes** | Code clinical text to WHO ICF categories, search 1,400+ codes, and access Core Sets for 12+ conditions |
 | **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 |
@@ -69,6 +72,87 @@ for (const entity of result.entities) {
 
 ## Features
 
+### Chart Audit (HCC gap capture, RADV defense, specificity, denial risk)
+
+Audit a chart to surface coding gaps, unsupported codes, specificity upgrades, and denial-risk flags in a single call. Every finding carries extractive evidence spans pointing back to the source text, and HCC gaps include RAF-weighted revenue estimates using the CMS PY2026 V22 and V28 community models.
+
+```ts
+const audit = await autoicd.audit({
+  text:
+    "68yo M, type 2 diabetes stable on metformin, chronic systolic heart failure " +
+    "on furosemide, edema controlled. A1c 7.4 today.",
+  codes: [{ code: "E11.9", kind: "icd10" }],
+  capabilities: ["hcc", "radv", "specificity", "denial", "problem_list"],
+  context: {
+    patient: { coverage: "medicare_advantage" },
+    hcc_model: "both",
+  },
+});
+
+console.log(`Missed revenue: $${audit.totals.estimated_revenue_recovery.toFixed(0)}`);
+console.log(`RADV exposure:  $${audit.totals.radv_exposure.toFixed(0)}`);
+
+for (const m of audit.missed) {
+  console.log(
+    `MISSED ${m.code} (${m.hcc_category ?? "non-HCC"} ${m.hcc_model ?? ""}) ` +
+    `→ $${m.estimated_revenue?.toFixed(0) ?? 0}: ${m.description}`
+  );
+  for (const span of m.evidence) {
+    console.log(`    evidence: "${span.quote}" [${span.start}-${span.end}]`);
+  }
+}
+```
+
+| Capability | What it surfaces |
+|---|---|
+| `hcc` | Missed HCC codes with `hcc_category`, `raf_weight`, `estimated_revenue` per v22/v28 model |
+| `radv` | Submitted codes with no supporting documentation, with `what_would_support_it` guidance and exposure dollars |
+| `specificity` | Upgrade opportunities from unspecified to more specific child codes |
+| `denial` | Documentation-quality risk flags (missing laterality, missing duration, age/sex mismatches) |
+| `problem_list` | Deduplicated active-conditions list with status (active/historical) and evidence |
+
+Default behavior runs all five capabilities. Pass `capabilities: ["hcc"]` to run a targeted audit.
+
+> **`hcc_model`:** use `"v22"`, `"v28"`, or `"both"` (default). CMS PY2026 MA payment uses V22 and V28 as the two main community models. V24 is the ESRD-specific model and is not accepted here.
+
+Read more about the Audit endpoint at [autoicdapi.com/audit](https://autoicdapi.com/audit).
+
+### Cross-Standard Code Translation
+
+Translate a code between healthcare coding systems in one call. Forward from ICD-10 to ICD-11, SNOMED CT, UMLS, and ICF, plus reverse ICD-11 → ICD-10 and ICF → ICD-10. Built on CMS-published crosswalks, code-level SNOMED / UMLS concept IDs, and WHO ICF Core Sets.
+
+```ts
+const mapping = await autoicd.translate({
+  from: { code: "E11.9", system: "icd10" },
+});
+
+console.log(mapping.mappings.icd11);
+// [{ code: "5A11", description: "Type 2 diabetes mellitus", mapping_type: "equivalent" }]
+console.log(mapping.mappings.snomed);
+// [{ code: "44054006" }, { code: "73211009" }, ...]
+console.log(mapping.mappings.icf);
+// [{ code: "b540", description: "General metabolic functions", component: "b" }, ...]
+```
+
+Narrow the targets when you only need specific systems:
+
+```ts
+const targeted = await autoicd.translate({
+  from: { code: "I50.9", system: "icd10" },
+  to: ["icd11"],
+});
+```
+
+Requested systems that aren't reachable from the source are returned in `unsupported_targets[]` rather than as errors, so clients can request a broad target list and use whatever comes back.
+
+| From | To | Source |
+|------|----|--------|
+| ICD-10-CM | ICD-11, SNOMED, UMLS, ICF | CMS crosswalk + concept refsets + WHO Core Sets |
+| ICD-11 MMS | ICD-10-CM | Reverse CMS crosswalk |
+| ICF | ICD-10-CM | Reverse WHO ICF Core Set index |
+
+Read more about the Translate endpoint at [autoicdapi.com/interop](https://autoicdapi.com/interop).
+
 ### 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.
@@ -167,6 +251,30 @@ for (const mapping of detail.icd11_mappings ?? []) {
 }
 ```
 
+### ICF Functioning Codes
+
+Code clinical text to WHO ICF categories, look up codes, search, and access ICF Core Sets for 12+ conditions.
+
+```typescript
+// Code clinical text to ICF categories
+const icf = await client.icf.code("Patient with stroke and hemiplegia");
+console.log(icf.results[0].codes);
+// [{ code: "b730", description: "Muscle power functions", component: "b", ... }]
+
+// Look up an ICF code
+const code = await client.icf.lookup("d450");
+console.log(code.title); // "Walking"
+console.log(code.definition); // "Moving along a surface on foot..."
+
+// Search ICF codes
+const results = await client.icf.search("mobility");
+
+// Get ICF Core Set for a diagnosis
+const coreSet = await client.icf.coreSet("E11.9");
+console.log(coreSet.conditionName); // "Diabetes Mellitus"
+console.log(coreSet.brief); // [{ code: "b530", title: "Weight maintenance functions", ... }]
+```
+
 ### 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.
@@ -281,6 +389,10 @@ Full REST API documentation at [autoicdapi.com/docs](https://autoicdapi.com/docs
 | `autoicd.icd10.get(code)` | Get details for an ICD-10-CM code (incl. ICD-11 crosswalk) |
 | `autoicd.icd11.search(query, options?)` | Search ICD-11 codes by description |
 | `autoicd.icd11.get(code)` | Get details for an ICD-11 code (incl. ICD-10 crosswalk) |
+| `autoicd.icf.code(text, options?)` | Code clinical text to ICF functioning categories |
+| `autoicd.icf.lookup(code)` | Get details for an ICF code |
+| `autoicd.icf.search(query, options?)` | Search ICF codes by keyword |
+| `autoicd.icf.coreSet(icd10Code)` | Get ICF Core Set for an ICD-10 diagnosis |
 
 ---
 
@@ -303,6 +415,10 @@ import type {
   ICD11CodeDetailFull,
   ICD11CodeSearchResponse,
   CrosswalkMapping,
+  ICFCodingResponse,
+  ICFCodeDetail,
+  ICFCodeSearchResponse,
+  ICFCoreSetResponse,
 } from "autoicd";
 ```