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 ```bash python scripts/main.py --input "clinical_note.txt" [--format json|text] ``` Or use programmatically: ```python 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 ```json { "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 ```json { "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 ```bash # 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