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