medicafe 0.250820.7__py3-none-any.whl → 0.250822.1__py3-none-any.whl

MediBot/MediBot.py

@@ -863,6 +863,22 @@ if __name__ == "__main__":
                 if _ac():
                     _ac().set_pause_status(True)
                 _ = manage_script_pause(csv_data, error_message, reverse_mapping)
+                # Prototype charges enrichment - optional and safe-failed to avoid disrupting existing workflow
+                if e_state.config.get('ENABLE_CHARGES_ENRICHMENT', False):
+                    try:
+                        from MediCafe.smart_import import get_components
+                        MediBot_Charges = get_components('medibot_charges')
+
+                        field_mapping = MediBot_Preprocessor_lib.field_mapping  # Ensure defined for enrichment
+
+                        csv_data, field_mapping, reverse_mapping, fixed_values = MediBot_Charges.enrich_with_charges(
+                            csv_data, field_mapping, reverse_mapping, fixed_values
+                        )
+                    except Exception as e:
+                        MediLink_ConfigLoader.log("Charges enrichment failed (prototype): {}. Continuing without enrichment.".format(e), level="WARNING")
+                        print("Warning: Charges feature skipped due to error. Proceeding with standard flow.")
+                else:
+                    MediLink_ConfigLoader.log("Charges enrichment disabled in config. Skipping.", level="INFO")
                 data_entry_loop(csv_data, MediBot_Preprocessor_lib.field_mapping, reverse_mapping, fixed_values)
                 cleanup()                
             else:

MediBot/MediBot_Charges.py

@@ -0,0 +1,133 @@
+"""MediBot_Charges.py
+
+Overview
+--------
+This module provides helper functions for MediBot.py to calculate and bundle charges for entry into Medisoft, based on patient data from MediBot (e.g., full patient details plus user-input anesthesia minutes). It focuses on ophthalmology clinics performing cataract surgeries, where patients typically undergo procedures on both eyes as separate events but require price bundling for consistent billing. Charges are generally calculated as piecewise step-functions based on anesthesia minutes (aligned with 837p units/minutes), exhibiting linear mx+b behavior.
+
+The module enriches patient data for backend use in MediBot.py, potentially including flags/tags for billing readiness (e.g., indicating prior surgeries, calculated charges, or bundling status). It does not handle UI display directly—that's for MediBot_UI.py or similar. Output feeds into MediLink for generating 837p files; consider enriching data in 837p-compatible format (e.g., Loop syntax for charges/minutes) for easier conversion to human-readable UI. See MediLink_Charges_Integration_Analysis.md for integration details and safety considerations.
+
+Key Features
+------------
+- Supports batch processing of up to 200 patients (typical: ~20), though serial processing is preferred for user input. Add a "save partial" flag to mitigate risks of inconsistent enriched data if batch fails midway.
+- Implements price bundling to balance charges across multiple procedures (e.g., both eyes), ensuring even total costs per eye to meet patient expectations. Bundling is not affected by unmet deductibles (which instead flag claims as Pending for Deductible to delay sending).
+- Flags "bundling_pending" by defaulting to expect a second procedure within 30 days from first date of service (process refund if expired). Speculate partly on diagnosis codes (e.g., ICD-10 H25.xx for bilateral cataracts), but note variability (e.g., glaucoma in one eye or prior surgery elsewhere) makes this imperfect—err on expecting return visits.
+- Uses tiered pricing schedules from MediLink_Charges.py (loaded via configuration or defaults):
+  - Private insurance:
+    - $450 for 1-15 minutes
+    - $540 for 16-34 minutes
+    - $580 for 35-59 minutes (maximum allowed duration; cap at 59 if exceeded)
+  - Medicare: Placeholder tiers (e.g., $300 for 1-30, $350 for 31-45, $400 for 46-59); override via configuration if different from private.
+- Integrates with historical transaction data (e.g., via MediSoft's MATRAN file, details TBD) for lookups, especially for patients with prior surgeries to support bundling. Never alters MATRAN data—print user notifications for any needed modifications (e.g., "Edit MATRAN for Patient ID: [ID] - Adjust prior charge from [old] to [new] for bundling"). For MediCafe-owned records, adjustments are fine.
+
+Limitations and Assumptions
+---------------------------
+- Bundling for commercial insurance depends on deductibles, claim submission timing (e.g., within 90 days of service), refund timing, and policy conditions. This is not fully specified but aims to minimize patient invoices due to non-payment risks post-surgery. Unmet deductibles flag claims but do not alter bundling.
+- Does not synchronize perfectly with procedure timing (date of service) or insurance events; bundling may fail if conditions like deductibles are unmet. Over-flagging "bundling_pending" could lead to unnecessary prep—monitor via logs.
+- Assumes serial processing: User inputs minutes per patient, module enriches data, repeat. Batch processing is inefficient without all data (e.g., minutes) available upfront. If batch fails midway, use "save partial" flag for recovery; no automatic rollback.
+- Medicare handling uses placeholders; assumes similarity to private insurance unless configured otherwise.
+- For missing historical data: Notify user (print, similar to MAINS failures; minimal logging to avoid DEBUG/INFO clutter [[memory:4184036]]), use any existing first/second visit data; prompt manually if none available (e.g., display table-like line from enhanced patient table, user fills 'minutes' column, line progresses with added charges and pre-loaded deductible data if available).
+- For durations >59 minutes: Cap at 59, log minimal INFO warning (no HIPAA data), and print notify for user confirmation (rare case, likely typo).
+- No direct risk to existing functionality, but bundling logic could affect billing accuracy if assumptions about insurance conditions are incorrect (e.g., over-bundling risks claim rejections; user errors in manual MATRAN edits could break audits if notifications aren't precise).
+
+Usage
+-----
+Intended as a data enricher for MediBot.py to automate Medisoft charge entry. Example flow:
+1. Receive patient data from MediBot.py.
+2. User inputs anesthesia minutes (possibly via enhanced patient table in MediBot_UI.py; extend display_enhanced_patient_table() with serial pauses/prompts).
+3. Enrich data with calculated/bundled charges, flags (e.g., bundling_pending, Pending for Deductible), and 837p-compatible fields.
+4. Pass enriched data back for MediSoft entry or 837p generation. For prior billed charges, lookup without alteration; notify user for manual MATRAN edits if needed.
+
+Integration Notes
+-----------------
+- Integrate with MediBot_UI.py for displaying an enhanced patient table, user input for minutes (table-like prompts where user fills 'minutes' column, line progresses), and historical lookups (e.g., for prior charges in bundling). Handle UI pauses serially; use "save partial" flag on errors.
+- Run serially per patient for real-time enrichment during input.
+- Future: Specify how to display bundled charges in UI and handle MATRAN file parsing for transactions (read-only).
+
+Compatibility
+-------------
+Always ensure XP SP3 + Python 3.4.4 + ASCII-only environment compatibility. Avoid f-strings and include inline commentary where assumptions may differ (e.g., Medicare handling).
+
+Note: This module is a helper; place any additional helper functions in a separate .py file per preferences.
+"""
+
+from MediCafe.smart_import import get_components
+from MediCafe.core_utils import get_config_loader_with_fallback
+
+# Import MediLink_Charges via smart_import (ensures no circular imports)
+MediLink_Charges = get_components('medilink_charges')
+MediLink_ConfigLoader = get_config_loader_with_fallback()  # Using centralized config loader for consistency with MediBot.py
+
+# Prototype function to enrich data with charges (called from MediBot.py TODO)
+def enrich_with_charges(csv_data, field_mapping, reverse_mapping, fixed_values):
+    # Inline commentary: This function enriches csv_data with charges using MediLink_Charges.
+    # Assumes serial processing; add "save partial" flag for batch recovery.
+    # No alterations to MATRAN - read-only lookups with user notifications.
+    # XP/Python 3.4.4 compatible: No f-strings, ASCII-only.
+
+    enriched_data = []
+    for row in csv_data:
+        # Get anesthesia minutes (prototype: assume from user input via UI prompt)
+        minutes = get_anesthesia_minutes(row, reverse_mapping)  # Placeholder call to UI prompt
+
+        # Cap minutes at 59
+        if minutes > 59:
+            minutes = 59
+            print("Capped duration to 59 minutes for patient ID: {}".format(row.get(reverse_mapping.get('Patient ID #2', ''), 'Unknown')))
+            # Minimal log (no HIPAA data)
+            if MediLink_ConfigLoader:
+                MediLink_ConfigLoader.log("Capped duration to 59 minutes", level="INFO")
+
+        # Determine insurance type (prototype: from row)
+        insurance_type = 'medicare' if 'MEDICARE' in row.get(reverse_mapping.get('Primary Insurance', ''), '').upper() else 'private'
+
+        # Calculate charge using MediLink_Charges
+        charge_info = MediLink_Charges.calculate_procedure_charge(
+            minutes=minutes,
+            insurance_type=insurance_type,
+            procedure_code=row.get(reverse_mapping.get('Procedure Code', ''), '66984'),  # Default cataract code
+            service_date=datetime.strptime(row.get('Surgery Date', ''), '%m-%d-%Y'),
+            patient_id=row.get(reverse_mapping.get('Patient ID #2', ''), '')
+        )
+
+        # Bundling and flagging (prototype: check for multi-eye)
+        prior_charges = lookup_historical_charges(charge_info.patient_id)  # Read-only MATRAN lookup
+        if prior_charges:
+            bundled = MediLink_Charges.bundle_bilateral_charges([charge_info] + prior_charges)
+            # Notify user for MATRAN edits if needed (no alterations)
+            print("Edit MATRAN for Patient ID: {} - Adjust prior charge from {} to {} for bundling".format(
+                charge_info.patient_id, prior_charges[0].base_charge, bundled[0].adjusted_charge))
+        else:
+            # Flag bundling_pending: Expect second within 30 days, based on diagnosis
+            diagnosis = row.get(reverse_mapping.get('Diagnosis Code', ''), '')
+            if 'H25' in diagnosis.upper():  # Speculative bilateral check
+                charge_info.bundling_group = 'bundling_pending'  # Refund if expires after 30 days
+
+        # Enrich row (prototype: add fields)
+        row['Calculated Charge'] = str(charge_info.adjusted_charge)
+        row['Minutes'] = charge_info.minutes
+        # Add flags (e.g., Pending for Deductible - prototype check)
+        if check_deductible_unmet(row):  # Placeholder
+            row['Status'] = 'Pending for Deductible'
+
+        enriched_data.append(row)
+
+    return enriched_data, field_mapping, reverse_mapping, fixed_values  # As per TODO
+
+# Prototype helpers (add more as needed)
+def get_anesthesia_minutes(row, reverse_mapping):
+    # Inline: Use interactive table from MediBot_UI for input.
+    from MediBot_UI import display_enhanced_patient_table
+    # Wrap single row as list (prototype)
+    patient_info = [(row.get('Surgery Date', ''), row.get(reverse_mapping.get('Patient Name', ''), 'Unknown'),
+                     row.get(reverse_mapping.get('Patient ID #2', ''), ''), row.get('Diagnosis Code', ''), row)]
+    enriched_info = display_enhanced_patient_table(patient_info, "Enter Minutes for Patient", interactive=True)
+    return enriched_info[0][4]['Minutes']  # Extract from enriched dict in tuple
+
+def lookup_historical_charges(patient_id):
+    # Inline: Read-only MATRAN lookup (details TBD). Never alter.
+    # If missing, prompt user via table-like UI.
+    return []  # Prototype: Return list of prior ChargeInfo
+
+def check_deductible_unmet(row):
+    # Inline: Prototype check; doesn't affect bundling.
+    return True  # Placeholder

MediBot/MediBot_UI.py

@@ -28,7 +28,7 @@ except ImportError:
 from MediCafe.core_utils import create_config_cache
 _get_config, (_config_cache, _crosswalk_cache) = create_config_cache()
 
-def display_enhanced_patient_table(patient_info, title, show_line_numbers=True):
+def display_enhanced_patient_table(patient_info, title, show_line_numbers=True, interactive=False):
     """
     Display an enhanced patient table with multiple surgery dates and diagnosis codes.
     
@@ -189,6 +189,47 @@ def display_enhanced_patient_table(patient_info, title, show_line_numbers=True):
                 primary_format = "     {:<6} | {:<" + str(max_patient_id_len) + "} | {:<" + str(max_patient_name_len) + "} | {:<" + str(max_diagnosis_len) + "}"
                 print(primary_format.format(formatted_date, patient_id, patient_name, display_diagnosis))
 
+    if interactive:
+        for i in range(len(patient_info)):
+            # Redraw table up to current row (prototype: simple print)
+            print("\n" + title)
+            print("|" + "-" * 80 + "|")  # ASCII table border
+            print("| Date | Name | ID | Diagnosis | Minutes | Deductible | Charge | Flags |")
+            print("|" + "-" * 80 + "|")
+
+            # Print previous rows (enriched)
+            for j in range(i):
+                r = patient_info[j]
+                print("| {} | {} | {} | {} | {} | {} | {} | {} |".format(
+                    r[0], r[1][:10], r[2], r[3], r.get('Minutes', ''), r.get('Deductible', 'N/A'), r.get('Charge', ''), r.get('Flags', '')))
+
+            # Prompt for current row
+            current = patient_info[i]
+            print("| {} | {} | {} | {} | [Input] | {} |        |               |".format(
+                current[0], current[1][:10], current[2], current[3], current.get('Deductible', 'N/A')))  # Highlight Minutes column
+
+            while True:
+                try:
+                    minutes_str = raw_input("Enter Minutes (1-59): ")
+                    minutes = int(minutes_str)
+                    if minutes > 59:
+                        minutes = 59
+                        confirm = raw_input("Capped to 59. Proceed? (Y/N): ").upper()
+                        if confirm != 'Y': continue
+                    if 1 <= minutes <= 59: break
+                    print("Invalid: 1-59 only.")
+                except ValueError:
+                    print("Invalid: Enter number.")
+
+            # Enrich and update row
+            enriched_row = enrich_single_row(current, minutes, patient_info[i][4])  # Pass original row dict
+            patient_info[i] = (enriched_row['Surgery Date'], enriched_row['Patient Name'], enriched_row['Patient ID #2'], enriched_row['Diagnosis Code'], enriched_row)  # Update tuple
+
+            # Redraw full table after update
+            # (Repeat print logic above with all rows up to i)
+
+        return patient_info  # Enriched
+
 # Function to check if a specific key is pressed
 def _get_vk_codes():
     """Get VK codes from config."""

MediBot/__init__.py

@@ -19,7 +19,7 @@ Smart Import Integration:
         medibot_main = get_components('medibot_main')
 """
 
-__version__ = "0.250820.7"
+__version__ = "0.250822.1"
 __author__ = "Daniel Vidaud"
 __email__ = "daniel@personalizedtransformation.com"
 

MediBot/update_medicafe.py

@@ -268,9 +268,17 @@ def verify_post_install(package, expected_version):
 
 
 def upgrade_package(package):
-    # Try with [binary] first; if pip doesn't recognize it, fall back to plain package
-    strategies = [
+    # Default to using existing system packages: skip dependencies first
+    # Light strategies: --no-deps to avoid heavy reinstall of dependencies
+    light_strategies = [
+        ['install', '--upgrade', '--no-deps', package + '[binary]', '--no-cache-dir', '--disable-pip-version-check'],
+        ['install', '--upgrade', '--no-deps', package, '--no-cache-dir', '--disable-pip-version-check']
+    ]
+
+    # Heavy strategies: allow dependencies as a last resort
+    heavy_strategies = [
         ['install', '--upgrade', package + '[binary]', '--no-cache-dir', '--disable-pip-version-check'],
+        ['install', '--upgrade', package, '--no-cache-dir', '--disable-pip-version-check'],
         ['install', '--upgrade', '--force-reinstall', package + '[binary]', '--no-cache-dir', '--disable-pip-version-check'],
         ['install', '--upgrade', '--force-reinstall', '--ignore-installed', '--user', package + '[binary]', '--no-cache-dir', '--disable-pip-version-check']
     ]
@@ -279,9 +287,11 @@ def upgrade_package(package):
     if not latest_before:
         print_status('WARNING', 'Unable to determine latest version from PyPI; proceeding with blind install')
 
-    for idx, parts in enumerate(strategies):
+    print_status('INFO', 'Using existing system packages when possible (skipping dependencies)')
+
+    for idx, parts in enumerate(light_strategies):
         attempt = idx + 1
-        print_section("Attempt {}/3".format(attempt))
+        print_section("Light attempt {}".format(attempt))
         cmd = [sys.executable, '-m', 'pip'] + parts
         print_status('INFO', 'Running: {} -m pip {}'.format(sys.executable, ' '.join(parts)))
         code, out, err = run_pip_install(cmd)
@@ -305,26 +315,58 @@ def upgrade_package(package):
                         print(tail)
                 except Exception:
                     pass
-            # Detect extras error and fall back to non-binary package
-            if 'Invalid requirement' in err or 'extras' in err or '[binary]' in err:
-                print_status('INFO', 'Falling back to installing without [binary] extra')
-                fb_cmd = [sys.executable, '-m', 'pip', 'install', '--upgrade', package, '--no-cache-dir', '--disable-pip-version-check']
-                code2, out2, err2 = run_pip_install(fb_cmd)
-                if code2 == 0:
-                    ok, installed = verify_post_install(package, latest_before)
-                    if ok:
-                        print_status('SUCCESS', 'Installed without [binary]: {}'.format(installed))
-                        return True
-                if err2:
-                    print(err2.strip())
-                elif out2:
-                    try:
-                        lines2 = out2.strip().splitlines()
-                        tail2 = '\n'.join(lines2[-15:])
-                        if tail2:
-                            print(tail2)
-                    except Exception:
-                        pass
+            print_status('WARNING', 'pip returned non-zero exit code ({})'.format(code))
+
+    # If we reached here, light attempts did not succeed conclusively
+    # Check command-line flags for non-interactive approval
+    auto_yes = False
+    for arg in sys.argv[1:]:
+        if arg.strip().lower() in ('--aggressive', '--yes-deps', '--full-deps'):
+            auto_yes = True
+            break
+
+    proceed_heavy = auto_yes
+    if not proceed_heavy:
+        print_section('Confirmation required')
+        print_status('INFO', 'Light update did not complete. A full dependency reinstall may take a long time.')
+        print_status('INFO', 'Proceeding will uninstall/reinstall related packages as needed (e.g., requests, lxml, msal).')
+        try:
+            answer = input('Proceed with full dependency update? (y/N): ').strip().lower()
+        except Exception:
+            answer = ''
+        proceed_heavy = (answer == 'y' or answer == 'yes')
+
+    if not proceed_heavy:
+        print_status('INFO', 'User declined full dependency update. Keeping existing dependencies.')
+        return False
+
+    print_section('Full dependency update')
+    print_status('INFO', 'Running heavy update with dependencies (this may take several minutes)')
+
+    for idx, parts in enumerate(heavy_strategies):
+        attempt = idx + 1
+        print_section('Heavy attempt {}'.format(attempt))
+        cmd = [sys.executable, '-m', 'pip'] + parts
+        print_status('INFO', 'Running: {} -m pip {}'.format(sys.executable, ' '.join(parts)))
+        code, out, err = run_pip_install(cmd)
+        if code == 0:
+            ok, installed = verify_post_install(package, latest_before)
+            if ok:
+                print_status('SUCCESS', 'Installed version: {}'.format(installed))
+                return True
+            else:
+                print_status('WARNING', 'Install returned success but version not updated yet{}'.format(
+                    '' if not installed else ' (detected {})'.format(installed)))
+        else:
+            combined = err or out
+            if combined:
+                try:
+                    lines3 = combined.strip().splitlines()
+                    tail3 = '\n'.join(lines3[-15:])
+                    if tail3:
+                        print(tail3)
+                except Exception:
+                    pass
             print_status('WARNING', 'pip returned non-zero exit code ({})'.format(code))
 
     return False

MediCafe/__init__.py

@@ -27,7 +27,7 @@ Smart Import System:
         api_suite = get_api_access()
 """
 
-__version__ = "0.250820.7"
+__version__ = "0.250822.1"
 __author__ = "Daniel Vidaud"
 __email__ = "daniel@personalizedtransformation.com"
 

MediCafe/api_core.py

@@ -861,8 +861,50 @@ def get_eligibility_super_connector(client, payer_id, provider_last_name, search
     if payer_id not in valid_payer_ids:
         raise ValueError("Invalid payer_id: {}. Must be one of: {}".format(payer_id, ", ".join(valid_payer_ids)))
     
-    endpoint_name = 'UHCAPI'
-    url_extension = client.config['MediLink_Config']['endpoints'][endpoint_name]['additional_endpoints']['eligibility_super_connector']
+    # Prefer OPTUMAI endpoint if configured, otherwise fall back to legacy UHCAPI super connector
+    try:
+        endpoints_cfg = client.config['MediLink_Config']['endpoints']
+    except Exception:
+        endpoints_cfg = {}
+
+    endpoint_name = None
+    url_extension = None
+
+    try:
+        optumai_cfg = endpoints_cfg.get('OPTUMAI', {})
+        optumai_additional = optumai_cfg.get('additional_endpoints', {}) if isinstance(optumai_cfg, dict) else {}
+        optumai_url = optumai_additional.get('eligibility_optumai')
+        if optumai_cfg and optumai_cfg.get('api_url') and optumai_url:
+            endpoint_name = 'OPTUMAI'
+            url_extension = optumai_url
+    except Exception:
+        # Safe ignore; will fall back below
+        pass
+
+    if not endpoint_name:
+        # Fallback to legacy UHCAPI super connector path for backward compatibility
+        endpoint_name = 'UHCAPI'
+        try:
+            url_extension = endpoints_cfg.get(endpoint_name, {}).get('additional_endpoints', {}).get('eligibility_super_connector')
+        except Exception:
+            url_extension = None
+
+    if not url_extension:
+        raise ValueError("Eligibility endpoint not configured for {}".format(endpoint_name))
+
+    # Debug/trace: indicate which endpoint/path is being used for the Super Connector call
+    try:
+        MediLink_ConfigLoader.log(
+            "Super Connector eligibility using endpoint '{}' with path '{}'".format(endpoint_name, url_extension),
+            level="INFO",
+            console_output=CONSOLE_LOGGING
+        )
+    except Exception:
+        pass
+    try:
+        print("[Eligibility] Using endpoint: {} (path: {})".format(endpoint_name, url_extension))
+    except Exception:
+        pass
     
     # Get provider TIN from config (using existing billing_provider_tin)
     from MediCafe.core_utils import extract_medilink_config
@@ -870,6 +912,19 @@ def get_eligibility_super_connector(client, payer_id, provider_last_name, search
     provider_tin = medi.get('billing_provider_tin')
     if not provider_tin:
         raise ValueError("Provider TIN not found in configuration")
+    # Normalize provider TIN to 9-digit numeric string
+    try:
+        provider_tin_str = ''.join([ch for ch in str(provider_tin) if ch.isdigit()])
+        if len(provider_tin_str) == 9:
+            provider_tin = provider_tin_str
+        else:
+            MediLink_ConfigLoader.log(
+                "Warning: Provider TIN '{}' is not 9 digits after normalization".format(provider_tin),
+                level="WARNING",
+                console_output=CONSOLE_LOGGING
+            )
+    except Exception:
+        pass
     
     # Construct GraphQL query variables using the consolidated module
     graphql_variables = MediLink_GraphQL.build_eligibility_variables(
@@ -896,8 +951,17 @@ def get_eligibility_super_connector(client, payer_id, provider_last_name, search
         MediLink_ConfigLoader.log("Using SAMPLE DATA from swagger documentation", level="INFO")
     else:
         # Build GraphQL request with actual data using consolidated module
-        graphql_body = MediLink_GraphQL.build_eligibility_request(graphql_variables)
-        MediLink_ConfigLoader.log("Using CONSTRUCTED DATA with consolidated GraphQL module", level="INFO")
+        # OPTUMAI now uses an enriched query aligned to production schema
+        try:
+            if endpoint_name == 'OPTUMAI' and hasattr(MediLink_GraphQL, 'build_optumai_enriched_request'):
+                graphql_body = MediLink_GraphQL.build_optumai_enriched_request(graphql_variables)
+                MediLink_ConfigLoader.log("Using OPTUMAI ENRICHED GraphQL request", level="INFO")
+            else:
+                graphql_body = MediLink_GraphQL.build_eligibility_request(graphql_variables)
+                MediLink_ConfigLoader.log("Using CONSTRUCTED DATA with consolidated GraphQL module", level="INFO")
+        except Exception:
+            graphql_body = MediLink_GraphQL.build_eligibility_request(graphql_variables)
+            MediLink_ConfigLoader.log("Fallback to standard GraphQL request body", level="WARNING")
         
         # Compare with sample data for debugging
         sample_data = MediLink_GraphQL.get_sample_eligibility_request()
@@ -924,8 +988,27 @@ def get_eligibility_super_connector(client, payer_id, provider_last_name, search
     headers = {
         'Content-Type': 'application/json',
         'Accept': 'application/json',
-        'tin': str(provider_tin)  # Ensure TIN is a string
+        'tin': str(provider_tin)  # Ensure TIN is a string (used for legacy UHC super connector)
     }
+
+    # OPTUMAI requires 'providertaxid' header (mapped from billing_provider_tin)
+    try:
+        if endpoint_name == 'OPTUMAI' and provider_tin:
+            # OPTUMAI expects providerTaxId; remove legacy 'tin' header to avoid confusion
+            if 'tin' in headers:
+                try:
+                    del headers['tin']
+                except Exception:
+                    pass
+            headers['providerTaxId'] = str(provider_tin)
+            # Add trace header for observability (optional per spec)
+            try:
+                corr_id = 'mc-{}'.format(int(time.time() * 1000))
+            except Exception:
+                corr_id = 'mc-{}'.format(int(time.time()))
+            headers['x-optum-consumer-correlation-id'] = corr_id
+    except Exception:
+        pass
     
     # Only add env header when using sample data
     if USE_SAMPLE_DATA:
@@ -937,12 +1020,86 @@ def get_eligibility_super_connector(client, payer_id, provider_last_name, search
     # Log the final headers being sent
     MediLink_ConfigLoader.log("Final headers being sent: {}".format(json.dumps(headers, indent=2)), level="DEBUG")
     
-    # Make the GraphQL API call
-    response = client.make_api_call(endpoint_name, 'POST', url_extension, params=None, data=graphql_body, headers=headers)
+    # Make the GraphQL API call with enhanced error diagnostics for endpoint failures
+    try:
+        response = client.make_api_call(endpoint_name, 'POST', url_extension, params=None, data=graphql_body, headers=headers)
+    except Exception as e:
+        # Best-effort diagnostics without exposing secrets or PHI
+        try:
+            status = getattr(getattr(e, 'response', None), 'status_code', None)
+            diag = "Eligibility request to {}{} failed".format(
+                endpoint_name and (endpoint_name + " ") or "", url_extension)
+            if status is not None:
+                diag += " with status {}".format(status)
+            MediLink_ConfigLoader.log(diag, level="ERROR", console_output=CONSOLE_LOGGING)
+            try:
+                print("[Eligibility] Request failed (status: {}). See logs for details.".format(status))
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+        # Progressive hardening: allow disabling fallback to UHC via config
+        try:
+            disable_fallback = False
+            try:
+                disable_fallback = bool(medi.get('optumai_disable_fallback', False))
+            except Exception:
+                disable_fallback = False
+            if not disable_fallback and endpoint_name == 'OPTUMAI':
+                fallback_url = endpoints_cfg.get('UHCAPI', {}).get('additional_endpoints', {}).get('eligibility_super_connector')
+                if fallback_url:
+                    try:
+                        MediLink_ConfigLoader.log(
+                            "OPTUMAI call failed. Falling back to UHCAPI path '{}'".format(fallback_url),
+                            level="WARNING",
+                            console_output=CONSOLE_LOGGING
+                        )
+                    except Exception:
+                        pass
+                    try:
+                        print("[Eligibility] Fallback to UHCAPI (path: {})".format(fallback_url))
+                    except Exception:
+                        pass
+                    response = client.make_api_call('UHCAPI', 'POST', fallback_url, params=None, data=graphql_body, headers=headers)
+                else:
+                    raise
+            else:
+                raise
+        except Exception:
+            # Propagate original error if fallback not possible or also fails
+            raise
     
     # Transform GraphQL response to match REST API format
     # This ensures the calling code doesn't know the difference
     transformed_response = MediLink_GraphQL.transform_eligibility_response(response)
+
+    # Post-transform sanity: if non-200, emit brief diagnostics to aid validation sessions
+    try:
+        sc_status = transformed_response.get('statuscode') if isinstance(transformed_response, dict) else None
+        if sc_status and sc_status != '200':
+            msg = transformed_response.get('message')
+            MediLink_ConfigLoader.log(
+                "Super Connector transformed response status: {} msg: {}".format(sc_status, msg),
+                level="INFO",
+                console_output=CONSOLE_LOGGING
+            )
+            raw_errs = None
+            try:
+                raw = transformed_response.get('rawGraphQLResponse', {})
+                raw_errs = raw.get('errors')
+            except Exception:
+                raw_errs = None
+            if raw_errs:
+                try:
+                    first_err = raw_errs[0]
+                    code = first_err.get('code') or first_err.get('extensions', {}).get('code')
+                    desc = first_err.get('description') or first_err.get('message')
+                    print("[Eligibility] GraphQL error code={} desc={}".format(code, desc))
+                except Exception:
+                    pass
+    except Exception:
+        pass
     
     return transformed_response
 

MediCafe/graphql_utils.py

@@ -7,7 +7,17 @@ Handles query templates, query building, and response transformations
 import json
 
 class GraphQLQueryBuilder:
-    """Builder class for constructing GraphQL queries for Super Connector API"""
+    """Builder class for constructing GraphQL queries for Super Connector API
+
+    Note on ID card images (idCardImages):
+    - Intentionally excluded from all active queries to avoid fetching large
+      image payloads and to reduce PHI handling risk in standard flows.
+    - If a future feature requires downloading insurance ID cards, add this
+      selection to the desired query:
+        idCardImages { side content contentType }
+      and ensure the implementation does NOT log or persist raw image content.
+      Gate any new behavior behind an explicit, opt-in feature flag.
+    """
     
     @staticmethod
     def get_eligibility_query():
@@ -161,6 +171,53 @@ class GraphQLQueryBuilder:
             }
         }
 
+    # ------------------------------------------------------------------
+    # OPTUMAI compatibility: minimal query that avoids fields not present
+    # ------------------------------------------------------------------
+    @staticmethod
+    def get_optumai_minimal_query():
+        """
+        Returns a minimal GraphQL query for OPTUMAI endpoint that avoids
+        fields reported as undefined by the schema.
+        """
+        return """query Query($input: EligibilityInput!) {\r\n  checkEligibility(input: $input) {\r\n    eligibility {\r\n      eligibilityInfo {\r\n        trnId\r\n        member {\r\n          memberId\r\n          firstName\r\n          lastName\r\n          middleName\r\n          dateOfBirth\r\n          gender\r\n          relationshipCode\r\n          dependentSequenceNumber\r\n          individualRelationship { code description }\r\n          relationshipType { code description }\r\n        }\r\n        insuranceInfo {\r\n          policyStatus\r\n          planTypeDescription\r\n          payerId\r\n        }\r\n        planLevels { level }\r\n      }\r\n    }\r\n  }\r\n}"""
+
+    @staticmethod
+    def build_optumai_minimal_request(variables):
+        """
+        Builds the minimal GraphQL request body for OPTUMAI.
+        """
+        return {
+            "query": GraphQLQueryBuilder.get_optumai_minimal_query(),
+            "variables": {
+                "input": variables
+            }
+        }
+
+    # ------------------------------------------------------------------
+    # OPTUMAI compatibility: enriched query with commonly used fields
+    # ------------------------------------------------------------------
+    @staticmethod
+    def get_optumai_enriched_query():
+        """
+        Returns an enriched GraphQL query for OPTUMAI that includes
+        eligibilityInfo core fields plus planLevels details that our
+        downstream logic commonly uses. Avoids legacy-only fields.
+        """
+        return """query Query($input: EligibilityInput!) {\r\n  checkEligibility(input: $input) {\r\n    eligibility {\r\n      eligibilityInfo {\r\n        trnId\r\n        member {\r\n          memberId\r\n          firstName\r\n          lastName\r\n          middleName\r\n          dateOfBirth\r\n          gender\r\n          relationshipCode\r\n          dependentSequenceNumber\r\n          individualRelationship { code description }\r\n          relationshipType { code description }\r\n        }\r\n        insuranceInfo {\r\n          policyNumber\r\n          eligibilityStartDate\r\n          eligibilityEndDate\r\n          planStartDate\r\n          planEndDate\r\n          policyStatus\r\n          planTypeDescription\r\n          payerId\r\n          lineOfBusinessCode\r\n          coverageType\r\n          insuranceTypeCode\r\n          insuranceType\r\n          stateOfIssueCode\r\n          productType\r\n          productId\r\n          productCode\r\n        }\r\n        associatedIds {\r\n          alternateId\r\n          medicaidRecipientId\r\n          exchangeMemberId\r\n          alternateSubscriberId\r\n          hicNumber\r\n          mbiNumber\r\n          subscriberMemberFacingIdentifier\r\n          survivingSpouseId\r\n          subscriberId\r\n          memberReplacementId\r\n          legacyMemberId\r\n          healthInsuranceExchangeId\r\n        }\r\n        planLevels {\r\n          level\r\n          family {\r\n            networkStatus\r\n            planAmount\r\n            planAmountFrequency\r\n            remainingAmount\r\n          }\r\n          individual {\r\n            networkStatus\r\n            planAmount\r\n            planAmountFrequency\r\n            remainingAmount\r\n          }\r\n        }\r\n      }\r\n      providerNetwork { status tier }\r\n    }\r\n  }\r\n}"""
+
+    @staticmethod
+    def build_optumai_enriched_request(variables):
+        """
+        Builds the enriched GraphQL request body for OPTUMAI.
+        """
+        return {
+            "query": GraphQLQueryBuilder.get_optumai_enriched_query(),
+            "variables": {
+                "input": variables
+            }
+        }
+
 class GraphQLResponseTransformer:
     """Transforms GraphQL responses to match REST API format"""
     
@@ -437,6 +494,14 @@ def build_eligibility_request(variables):
     """Build complete GraphQL request body with working format"""
     return GraphQLQueryBuilder.build_eligibility_request(variables)
 
+def build_optumai_minimal_request(variables):
+    """Build minimal GraphQL request body for OPTUMAI"""
+    return GraphQLQueryBuilder.build_optumai_minimal_request(variables)
+
+def build_optumai_enriched_request(variables):
+    """Build enriched GraphQL request body for OPTUMAI"""
+    return GraphQLQueryBuilder.build_optumai_enriched_request(variables)
+
 def transform_eligibility_response(graphql_response):
     """Transform GraphQL eligibility response to REST format"""
     return GraphQLResponseTransformer.transform_eligibility_response(graphql_response)