Ready for release

Author: soumick1

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          pip install -e .
+      - name: Pytest
+        run: pytest -q

samples/label_descs.json

@@ -0,0 +1,21 @@
+{
+  "Billing": "charges, fees, refunds, adjustments, statements, interest, taxation",
+  "Refunds": "request or status of refunds, reversals, chargebacks",
+  "Disputes": "dispute a transaction, incorrect billing, merchant issues",
+  "Fees": "monthly fees, ATM fees, foreign exchange fees, brokerage commissions",
+  "Statements": "download statements, line-item explanations, interest charged",
+  "TaxDocs": "tax certificates, 1099/INT, W-8BEN, capital gains/loss statements",
+  "TechSupport": "app or website problems, login, authentication, device issues",
+  "LoginIssues": "password reset, two-factor auth, locked account",
+  "AppBugs": "crashes, slow, update problems, notifications not working",
+  "CardIssues": "card not working at ATM or POS, declines",
+  "Connectivity": "cannot connect, network timeouts, proxy/VPN issues",
+  "AccountClosure": "close account, terminate service, transfer out, exit",
+  "Opening": "open account, eligibility, required documents, minimum balance",
+  "Limits": "increase/decrease limits, wire/ACH caps, withdrawal/transfer limits",
+  "Profile": "update address, phone, email, name; re-KYC; document uploads",
+  "Trading": "place orders, order types, execution, after-hours, margin",
+  "Dividends": "dividend schedules, DRIP enrollment, withholding tax",
+  "CorporateActions": "splits, mergers, rights issues, de-listing, proxy voting",
+  "Research": "screeners, analyst ratings, news feeds, reports access"
+}

samples/label_descs_dense.json

@@ -0,0 +1,82 @@
+{
+  "CardDecline_ATM": "card declined at ATM, cash withdrawal failure, terminal error, network or insufficient funds message",
+  "CardDecline_POS": "point-of-sale card decline at merchant checkout, terminal decline, payment refused",
+  "CardDecline_Online": "online purchase payment declined by card issuer, e-commerce transaction refused",
+  "CardDecline_International": "card declined abroad or for foreign merchant, cross-border or FX restrictions",
+  "CardDecline_ChipError": "chip read error, EMV failure, insert card multiple times, cannot read chip",
+  "CardDecline_SwipeError": "magstripe read failure, swipe error, try alternate method",
+  "CardDecline_Contactless": "tap to pay / NFC contactless decline or not recognized",
+  "CardDecline_WrongPIN": "PIN attempts failing at ATM/POS, incorrect PIN or blocked",
+  "CardDecline_Expired": "card expired, out-of-date card validity causing declines",
+  "CardDecline_NotActivated": "new or replacement card not activated leads to decline",
+  "Login_ResetPassword": "forgot password, reset link or flow, cannot sign in",
+  "Login_2FA_NoSMS": "two-factor code by SMS not arriving, OTP missing or delayed",
+  "Login_2FA_Authenticator": "authenticator app code not accepted, TOTP mismatch",
+  "Login_DeviceLost": "lost phone/device, cannot access app, need recovery",
+  "Login_Lockout": "account locked due to too many attempts, need unlock",
+  "App_Crash_Launch": "app crashes on startup, immediately closes on opening",
+  "App_Crash_Transfer": "app crashes on transfer or payments screen, force close",
+  "App_NoNotifications": "push notifications not received, approval prompts missing",
+  "App_Stuck_Update": "update caused errors, roll back or stuck during update",
+  "App_SessionLoop": "session expired loop, repeated login prompts, redirect loops",
+  "ACH_Pending": "ACH transfer pending review, funds not yet posted",
+  "ACH_Reversed_NSF": "ACH reversed due to insufficient funds, return code R01",
+  "Wire_Pending": "wire transfer pending compliance or cut-off delay",
+  "Wire_Returned_Beneficiary": "wire returned due to wrong beneficiary name or details mismatch",
+  "Instant_Transfer_Risk": "instant transfer failed due to risk checks or velocity limits",
+  "BillPay_Delayed": "bill payment delayed or not received by payee yet",
+  "P2P_Pending": "peer-to-peer payment pending acceptance or in hold",
+  "External_Microdeposits": "external account verification micro-deposits not appearing",
+  "StandingOrder_Duplicate": "standing order or scheduled transfer duplicated or repeated",
+  "Remittance_FX_Dispute": "international remittance FX rate dispute or spread concern",
+  "Fee_ForeignTxn": "foreign transaction fee charged, DCC or cross-border fee dispute",
+  "Fee_ATM_Refund": "ATM surcharge refund request or network fee reversal",
+  "Fee_Monthly_Waiver": "monthly maintenance fee waiver eligibility or request",
+  "Fee_Overdraft_Reversal": "overdraft fee reversal request, courtesy refund",
+  "Stmt_Charge_Explain": "explain statement charge, unknown debit or descriptor",
+  "Interest_Charge_Query": "interest assessed on balance, clarify accrual or APR",
+  "Chargeback_Initiate": "initiate chargeback for unauthorized or defective goods",
+  "Chargeback_Status": "check chargeback investigation status or evidence",
+  "Merchant_DoubleCharge": "merchant charged twice, duplicate transaction on statement",
+  "DCC_Complaint": "dynamic currency conversion complaint, charged in wrong currency",
+  "Acct_Close": "close account, terminate service, transfer out remaining balance",
+  "Acct_Reopen": "reopen previously closed or dormant account",
+  "Acct_AddressChange": "update residential address or mailing address, proof of address",
+  "Acct_NameChange": "change legal name, submit documents, profile update",
+  "Acct_Limit_Withdrawal": "increase cash withdrawal limit at ATM or POS",
+  "Acct_Limit_Wire": "increase wire transfer limit or daily cap",
+  "Acct_Add_Joint": "add joint account holder or authorized user",
+  "Acct_Remove_Joint": "remove joint account holder, ownership changes",
+  "Acct_TaxResidency": "update tax residency, W-8BEN/W-9 forms, CRS/FATCA",
+  "Acct_ReKYC": "re-submit KYC, re-verification, document resubmission",
+  "Trade_Market_Unfilled": "market order not filled due to halt or venue issues",
+  "Trade_Limit_Expired": "limit order expired or canceled without fill",
+  "Trade_AfterHours_Rejected": "after-hours trade rejected due to eligibility or liquidity",
+  "Margin_Call": "margin call notification, equity below maintenance requirement",
+  "Dividend_Missing": "dividend not posted, expected payout missing",
+  "Dividend_Withholding": "withholding tax on dividends, treaty rate or reclaims",
+  "CorpAction_Split": "stock split or reverse split details, position adjustment",
+  "CorpAction_Merger": "merger or acquisition, exchange ratio, new ticker",
+  "DRIP_Change": "dividend reinvestment plan enroll/unenroll, DRIP settings",
+  "Fractional_Settlement": "fractional share not settling or pending",
+  "Card_Virtual_Create": "create virtual card number for online purchases",
+  "Card_Freeze": "freeze or lock card temporarily to prevent use",
+  "Card_Unfreeze": "unfreeze or unlock card to resume use",
+  "Card_Replace_Damaged": "replace damaged or worn card, new card request",
+  "Card_Replace_Lost": "replace lost or stolen card, block immediately",
+  "Card_Activate": "activate new or replacement card via app or phone",
+  "Card_TravelNotice": "set travel notice to reduce foreign declines",
+  "Card_Add_Wallet": "add card to Apple Pay / Google Wallet or similar",
+  "Card_Remove_Wallet": "remove card from wallet app, unlink device",
+  "Card_Change_PIN": "change card PIN, reset or unblock",
+  "Conn_VPN_Block": "VPN or corporate network blocking app or site access",
+  "Conn_Firewall": "firewall or security policy preventing connections",
+  "Conn_Proxy_Timeouts": "HTTP/HTTPS proxy causing timeouts or handshake failures",
+  "Conn_Cellular_Weak": "poor cellular data network, intermittent connectivity",
+  "Conn_Wifi_Captive": "Wi\u2011Fi captive portal requiring login interferes with app",
+  "Conn_Region_Restrict": "region or geo restriction message, service not available",
+  "Conn_TLS_SSL": "TLS/SSL certificate or handshake error messages",
+  "Conn_OS_Outdated": "outdated OS version incompatible with latest app build",
+  "Conn_Storage_Full": "device storage full, app cannot write cache or update",
+  "Conn_BatterySaver": "battery saver / background restrictions killing app sessions"
+}

samples/labels_min.txt

@@ -0,0 +1,6 @@
+Billing
+Refunds
+TechSupport
+AppBugs
+CardIssues
+AccountClosure

samples/long_example.txt

@@ -0,0 +1,7 @@
+I have several issues today. My debit card keeps failing at four different ATMs with a 
+'transaction declined' message, even though my balance is fine. The mobile app started crashing right after 
+I upgraded from the Play Store, and push notifications have stopped, so approving 2FA is impossible.
+I also want to begin closing my brokerage account and transfer my holdings to another provider this month. 
+Before that, please explain the foreign transaction fees I saw in my June statement and if those can be waived, 
+and how dividend withholding will be treated if I stay in DRIP a few more weeks. Finally, I changed my address 
+last week and uploaded re-KYC documents—please confirm it has been applied to all my linked accounts.

samples/stress_texts.txt

@@ -0,0 +1,52 @@
+Tap-to-pay keeps failing at two grocery stores, then the app crashed when I tried to approve a 2FA prompt.
+ATM said transaction declined but I have funds; chip read errors when I tried again at POS.
+International online purchase rejected and the NFC tap doesn't register on my transit card readers.
+New card replacement still declines because activation didn't go through and PIN keeps saying incorrect.
+ACH to my external bank is pending for days and I also see a foreign transaction fee on a hotel booking.
+Wire returned for mismatched name and now my beneficiary wants proof; the maintenance fee also posted.
+Instant transfer blocked for risk; can I get the ATM surcharge refunded from last weekend?
+Standing order sent twice this month and the remittance FX rate looks off compared to mid-market.
+Please close my account after confirming the new address—re-KYC documents were uploaded yesterday.
+Reopen my dormant account and increase the wire limit; I also changed my tax residency this year.
+My market order didn't fill during a trading halt and later my fractional share stayed pending.
+DRIP didn't reinvest and the dividend withholding looks higher than the treaty rate.
+Limit order expired unfilled after-hours; are quote delays making it miss prices?
+I froze my card due to duplicate merchant charges, but tap to pay is still failing at terminals.
+I need to change PIN and add the card to my phone wallet; contactless failed at a cafe.
+Corporate firewall and proxy timeouts prevent login; 2FA SMS codes never arrive when I'm on VPN.
+TLS handshake errors on hotel Wi‑Fi captive portal; app sessions loop and log me out.
+Device storage is full and the new update keeps crashing on launch.
+Monthly maintenance fee waiver eligibility? Also chargeback status for a defective item.
+Can you explain a weird descriptor on my statement; I think the merchant charged me twice.
+Overdraft fee reversal please, plus why was the bill payment delayed to my utility?
+Micro-deposits to verify my external account haven't shown up yet.
+International remittance spread seems high; the FX is worse than quoted.
+Card declined at a POS terminal, 2FA authenticator codes rejected, and my standing order duplicated.
+App crashes on transfer screen, VPN blocks the site, and my wire is still pending.
+Can't connect on cellular data, battery saver kills background tasks, and a limit order expired.
+My address change applied but joint holder removal is still pending; also dividend missing this cycle.
+Travel notice set but still declined abroad; DCC complaint because charged in wrong currency.
+Fractional share never settled; corporate action split adjusted my holdings oddly.
+Lost device so can't access authenticator app; please unfreeze my card and reset 2FA.
+Please activate the new card, remove from old wallet, and waive the ATM fees from last trip.
+Name change processed but wire limit remains too low and the app doesn't send notifications.
+Session keeps expiring during sign-in; update got stuck; push approvals never pop up.
+Tap works at POS but fails for transit; ATM says decline and chip read error shows at a pharmacy.
+ACH reversed NSF while my peer payment is pending; can you also check a chargeback initiation?
+My dividend didn't post and the DRIP setting seems off; what's the corporate action about a merger?
+Overdraft fee reversal and interest charge clarification for last month.
+Merchant did a double charge and dynamic currency conversion hit me in euros.
+External account micro-deposits posted but the bill pay is still delayed.
+Wire returned wrong beneficiary details; FX rate for my remittance looks off too.
+Card expired last week; contactless won't register and online purchases get declined.
+PIN fails at ATMs; swipe works sometimes but chip throws errors repeatedly.
+Re-KYC requested and tax residency update needed; please increase the ATM withdrawal limit.
+Close my account after I transfer out positions; dividend withholding seems incorrect.
+Add joint holder and change my address; also need the monthly fee waived.
+Lost phone so device is gone; 2FA authenticator isn't available and I can't receive SMS.
+App crashes on launch after the update; TLS/SSL errors when I try via hotel Wi‑Fi.
+Region restriction blocks research screens; real-time quotes are delayed too.
+Freeze my card due to international declines and replace it because the chip is damaged.
+Unfreeze the card now; set a travel notice and add it to Apple Pay.
+Proxy causes timeouts and VPN blocks connectivity; session loop keeps me out.
+Please reopen my dormant account, remove a joint holder, and raise the wire limit.

src/zsc_llm/__init__.py

@@ -0,0 +1,5 @@
+"""
+zsc_llm: Zero-shot hierarchical classification (notebook methodology)
+"""
+__all__ = ["__version__"]
+__version__ = "0.2.0"