aipoch/icd10-cpt-coding-assistant

ICD-10 & CPT Coding Assistant

A medical coding assistant that parses clinical notes and recommends appropriate ICD-10 diagnosis codes and CPT procedure codes with confidence scoring.

Overview

This skill analyzes clinical documentation to extract relevant medical information and map it to standardized coding systems:

• ICD-10-CM: International Classification of Diseases, 10th Revision, Clinical Modification (diagnosis codes)
• CPT: Current Procedural Terminology (procedure/service codes)

Technical Difficulty: HIGH ⚠️

⚠️ HUMAN REVIEW REQUIRED: Medical coding directly impacts billing, reimbursement, and clinical documentation. All recommendations must be verified by a certified medical coder or healthcare provider.

Usage

python scripts/main.py --input "clinical_note.txt" [--format json|text]

Or use programmatically:

from scripts.main import CodingAssistant

assistant = CodingAssistant()
result = assistant.analyze("Patient presents with acute bronchitis...")
print(result.icd10_codes)
print(result.cpt_codes)

Parameters

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --input, -i | string | - | Yes | Path to clinical note file | | --format, -f | string | json | No | Output format (json, text) | | --output, -o | string | stdout | No | Output file path | | --confidence-threshold | float | 0.7 | No | Minimum confidence score (0.0-1.0) | | --include-alternatives | flag | false | No | Include alternative code suggestions |

Input Format

Accepts clinical notes in various formats:

• Free-text narrative
• SOAP notes (Subjective, Objective, Assessment, Plan)
• Discharge summaries
• Progress notes
• Procedure reports

Output Format

ICD-10 Recommendations

{
  "icd10_codes": [
    {
      "code": "J20.9",
      "description": "Acute bronchitis, unspecified",
      "confidence": 0.92,
      "evidence": ["cough for 5 days", "wheezing on exam"],
      "alternatives": ["J20.0", "J44.9"]
    }
  ]
}

CPT Recommendations

{
  "cpt_codes": [
    {
      "code": "99213",
      "description": "Office visit, established patient, moderate complexity",
      "confidence": 0.85,
      "evidence": ["detailed history", "low complexity decision making"],
      "time": "20 minutes"
    }
  ]
}

Confidence Scoring

• 0.90-1.00: High confidence - Clear documentation, unambiguous mapping
• 0.70-0.89: Medium confidence - Good documentation, some interpretation required
• 0.50-0.69: Low confidence - Incomplete documentation, multiple possibilities
• <0.50: Very low confidence - Insufficient information, manual review essential

Limitations

1. No Medical Advice: This tool does not provide clinical advice or diagnoses
2. Coding Complexity: Cannot handle all coding nuances (comorbidities, sequencing, modifiers)
3. Regional Variations: May not account for payer-specific coding requirements
4. Updates: Code sets may not reflect the latest annual updates

References

See references/ folder for:

• icd10_common_codes.json: Frequently used ICD-10 codes by specialty
• cpt_common_codes.json: Frequently used CPT codes by specialty
• coding_guidelines.md: General coding guidelines and conventions

Safety & Compliance

• HIPAA Awareness: Ensure de-identification of PHI before processing
• Audit Trail: Maintain records of automated recommendations for compliance
• Human Oversight: All codes must be reviewed and approved by qualified personnel

Dependencies

• Python 3.8+
• See requirements.txt for package dependencies

Risk Assessment

| Risk Indicator | Assessment | Level | |----------------|------------|-------| | Code Execution | Python/R scripts executed locally | Medium | | Network Access | No external API calls | Low | | File System Access | Read input files, write output files | Medium | | Instruction Tampering | Standard prompt guidelines | Low | | Data Exposure | Output files saved to workspace | Low |

Security Checklist

• [ ] No hardcoded credentials or API keys
• [ ] No unauthorized file system access (../)
• [ ] Output does not expose sensitive information
• [ ] Prompt injection protections in place
• [ ] Input file paths validated (no ../ traversal)
• [ ] Output directory restricted to workspace
• [ ] Script execution in sandboxed environment
• [ ] Error messages sanitized (no stack traces exposed)
• [ ] Dependencies audited

Prerequisites

# Python dependencies
pip install -r requirements.txt

Evaluation Criteria

Success Metrics

• [ ] Successfully executes main functionality
• [ ] Output meets quality standards
• [ ] Handles edge cases gracefully
• [ ] Performance is acceptable

Test Cases

1. Basic Functionality: Standard input → Expected output
2. Edge Case: Invalid input → Graceful error handling
3. Performance: Large dataset → Acceptable processing time

Lifecycle Status

• Current Stage: Draft
• Next Review Date: 2026-03-06
• Known Issues: None
• Planned Improvements:
  • Performance optimization
  • Additional feature support