Upload 3 files

thicc/insurance/coverage_explainer.py

@@ -0,0 +1,248 @@
+"""
+Coverage Explanations Module - Provides insurance term explanations.
+"""
+
+class CoverageExplainer:
+    """Explains insurance coverage terms in user-friendly language."""
+
+    COVERAGE_TERMS = {
+        "deductible": {
+            "brief": "The amount you pay before insurance starts covering costs",
+            "detailed": """A deductible is the amount you must pay out-of-pocket for covered healthcare services before your insurance plan starts to pay.
+
+**Example**: If you have a $1,000 deductible:
+• You pay the first $1,000 of covered services yourself
+• After meeting your deductible, you typically pay only copays or coinsurance
+• Deductibles reset yearly
+
+**Important**: Some services like preventive care may be covered before you meet your deductible.""",
+            "keywords": ["deductible", "deductibles", "yearly amount", "before insurance pays"],
+        },
+
+        "copay": {
+            "brief": "A fixed amount you pay for a covered service",
+            "detailed": """A copay (copayment) is a fixed amount you pay for a covered healthcare service, usually at the time of service.
+
+**Example**: 
+• Doctor visit: $25 copay
+• Specialist visit: $50 copay
+• Prescription: $10 copay
+
+**Key Points**:
+• Copays are typically the same regardless of the actual cost
+• You usually pay copays even after meeting your deductible
+• Different services have different copay amounts""",
+            "keywords": ["copay", "copayment", "fixed amount", "flat fee"],
+        },
+
+        "coinsurance": {
+            "brief": "Your percentage share of costs after deductible",
+            "detailed": """Coinsurance is your share of the costs of a covered healthcare service, calculated as a percentage of the allowed amount for the service.
+
+**Example**: With 20% coinsurance:
+• Insurance pays 80% of covered costs
+• You pay 20% of covered costs
+• This applies AFTER you meet your deductible
+
+**Real Scenario**: 
+MRI costs $1,000 (after deductible met)
+• Insurance pays: $800 (80%)
+• You pay: $200 (20%)""",
+            "keywords": ["coinsurance", "percentage", "percent of cost", "cost sharing", "80/20", "70/30"],
+        },
+
+        "out_of_network": {
+            "brief": "Higher costs for providers not in your insurance network",
+            "detailed": """Out-of-network refers to healthcare providers who haven't contracted with your insurance company to provide services at negotiated rates.
+
+**Penalties and Higher Costs**:
+• Higher deductibles (often double in-network amounts)
+• Higher coinsurance (40-50% vs 20-30%)
+• No negotiated rates (you may pay full price)
+• Balance billing (provider can bill you the difference)
+
+**Example Cost Difference**:
+Same procedure:
+• In-network: You pay $500 (20% coinsurance)
+• Out-of-network: You pay $2,000 (50% coinsurance + balance billing)
+
+**Tip**: Always check if a provider is in-network before receiving care, except in emergencies.""",
+            "keywords": [
+                "out of network",
+                "out-of-network",
+                "network penalties",
+                "provider network",
+                "in-network",
+                "network",
+            ],
+        },
+
+        "out_of_pocket_maximum": {
+            "brief": "The most you'll pay in a year for covered services",
+            "detailed": """The out-of-pocket maximum is the most you have to pay for covered services in a plan year. After you reach this amount, your insurance pays 100% of covered services.
+
+**What Counts**:
+✓ Deductibles
+✓ Copayments
+✓ Coinsurance
+
+**What Doesn't Count**:
+✗ Monthly premiums
+✗ Out-of-network costs (usually)
+✗ Non-covered services
+
+**Example**: $8,000 out-of-pocket maximum
+Once you've paid $8,000 in deductibles, copays, and coinsurance, your insurance covers 100% for the rest of the year.""",
+            "keywords": [
+                "out of pocket maximum",
+                "out-of-pocket maximum",
+                "max",
+                "maximum",
+                "yearly limit",
+                "annual limit",
+                "oop max",
+            ],
+        },
+
+        "premium": {
+            "brief": "Monthly payment to maintain insurance coverage",
+            "detailed": """Your premium is the amount you pay for your health insurance every month to maintain coverage, regardless of whether you use services.
+
+**Key Points**:
+• Due monthly whether you use healthcare or not
+• Doesn't count toward deductible or out-of-pocket maximum
+• Higher premiums often mean lower deductibles/copays
+• Employer may pay part of your premium
+
+**Example Monthly Premiums**:
+• Individual: $450/month
+• Family: $1,200/month""",
+            "keywords": ["premium", "monthly payment", "monthly cost", "insurance payment"],
+        },
+
+        "prior_authorization": {
+            "brief": "Insurance approval needed before certain services",
+            "detailed": """Prior authorization (preauthorization) means your insurance company must approve a service before you receive it for the service to be covered.
+
+**Common Services Requiring Authorization**:
+• MRI/CT scans
+• Surgery
+• Expensive medications
+• Specialist referrals (HMO plans)
+
+**Important**:
+• Without authorization, insurance may deny coverage
+• Your doctor typically handles the authorization
+• Can take days to weeks for approval
+• Emergency services don't require prior authorization""",
+            "keywords": [
+                "prior authorization",
+                "preauthorization",
+                "pre-approval",
+                "authorization",
+                "approval needed",
+            ],
+        },
+    }
+
+    @classmethod
+    def explain_term(cls, term: str) -> str | None:
+        """Get detailed explanation for a specific coverage term."""
+        term_lower = term.lower().strip()
+
+        for key, info in cls.COVERAGE_TERMS.items():
+            if key in term_lower or any(keyword in term_lower for keyword in info["keywords"]):
+                return info["detailed"]
+
+        return None
+
+    @classmethod
+    def get_brief_explanation(cls, term: str) -> str | None:
+        """Get brief explanation for a coverage term."""
+        term_lower = term.lower().strip()
+
+        for key, info in cls.COVERAGE_TERMS.items():
+            if key in term_lower or any(keyword in term_lower for keyword in info["keywords"]):
+                return info["brief"]
+
+        return None
+
+    @classmethod
+    def explain_all_terms(cls) -> str:
+        """Return explanations for all coverage terms."""
+        explanations = ["**Understanding Your Insurance Coverage**\n"]
+
+        for term, info in cls.COVERAGE_TERMS.items():
+            title = term.replace("_", " ").title()
+            explanations.append(f"**{title}**")
+            explanations.append(info["detailed"])
+            explanations.append("")
+
+        return "\n".join(explanations)
+
+    @classmethod
+    def identify_coverage_question(cls, user_input: str) -> bool:
+        """Check if user is asking about coverage terms."""
+        user_input_lower = user_input.lower()
+
+        # General coverage question patterns
+        general_terms = [
+            "what is",
+            "what's",
+            "explain",
+            "how does",
+            "how do",
+            "tell me about",
+            "help me understand",
+            "coverage",
+            "insurance terms",
+            "insurance work",
+        ]
+
+        # Check for general questions with coverage terms
+        if any(term in user_input_lower for term in general_terms):
+            for term_info in cls.COVERAGE_TERMS.values():
+                if any(keyword in user_input_lower for keyword in term_info["keywords"]):
+                    return True
+
+        # Direct term mentions
+        for term_info in cls.COVERAGE_TERMS.values():
+            if any(keyword in user_input_lower for keyword in term_info["keywords"]):
+                return True
+
+        return False
+
+    @classmethod
+    def get_matching_term(cls, user_input: str) -> str | None:
+        """Extract which coverage term the user is asking about."""
+        user_input_lower = user_input.lower()
+
+        for term_key, term_info in cls.COVERAGE_TERMS.items():
+            for keyword in term_info["keywords"]:
+                if keyword in user_input_lower:
+                    return term_key
+
+        return None
+
+    @classmethod
+    def format_plan_coverage_summary(cls, plan_name: str, plan_details: dict) -> str:
+        """Format a summary of coverage for a specific plan."""
+        deductible = plan_details.get("deductible", 0)
+        copay = plan_details.get("copay", 0)
+        coinsurance = plan_details.get("coinsurance", 0) * 100
+
+        return f"""**Your {plan_name} Plan Coverage**
+
+**Deductible**: ${deductible:,.0f}
+• You pay this amount first before insurance helps
+
+**Copay**: ${copay:.0f}
+• Fixed amount you pay per visit
+
+**Coinsurance**: {coinsurance:.0f}%
+• Your percentage share after deductible
+
+**How it works**:
+1. You pay 100% until you meet your ${deductible:,.0f} deductible
+2. Then you pay ${copay:.0f} copays or {coinsurance:.0f}% coinsurance
+3. Insurance covers the rest up to allowed amounts"""