expose Receivable Asset Class

Author: yellowbean

absbox/client.py

@@ -143,18 +143,18 @@ def __post_init__(self) -> None:
         :raises VersionMismatch: Failed to match version between client and server
         """
         self.url = isValidUrl(self.url).rstrip("/")
-        with console.status(f"{MsgColor.Info.value}Connecting engine server -> {self.url}") as status:
-            try:
-                _r = requests.get(f"{self.url}/{Endpoints.Version.value}", verify=False, timeout=5).text
-            except (ConnectionRefusedError, ConnectionError):
-                raise AbsboxError(f"❌{MsgColor.Error.value}Error: Can't not connect to API server {self.url}")
-            if _r is None:
-                raise RuntimeError(f"Failed to get version from url:{self.url}")
-            self.server_info = self.server_info | json.loads(_r)
-            engine_version = self.server_info['_version'].split(".")
-            if self.check and (self.version[1] != engine_version[1]):
-                console.print("pls upgrade your api package by: pip -U absbox")
-                raise VersionMismatch('.'.join(self.version), '.'.join(engine_version))
+        console.print(f"{MsgColor.Info.value}Connecting engine server -> {self.url}")
+        try:
+            _r = requests.get(f"{self.url}/{Endpoints.Version.value}", verify=False, timeout=5, headers = {"Origin":"http://localhost:8001"}).text
+        except (ConnectionRefusedError, ConnectionError):
+            raise AbsboxError(f"❌{MsgColor.Error.value}Error: Can't not connect to API server {self.url}")
+        if _r is None:
+            raise RuntimeError(f"Failed to get version from url:{self.url}")
+        self.server_info = self.server_info | json.loads(_r)
+        engine_version = self.server_info['_version'].split(".")
+        if self.check and (self.version[1] != engine_version[1]):
+            console.print("pls upgrade your api package by: pip -U absbox")
+            raise VersionMismatch('.'.join(self.version), '.'.join(engine_version))
         console.print(f"✅{MsgColor.Success.value}Connected, local lib:{'.'.join(self.version)}, server:{'.'.join(engine_version)}")
         self.session = requests.Session()
 
@@ -371,12 +371,15 @@ def readResult(x):
             except Exception as e:
                 print(f"Failed to read result {x} \n with error {e}")
                 return (None, None, None)
+            
         url = f"{self.url}/{Endpoints.RunAsset.value}"
         _assumptions = mkAssumpType(poolAssump) if poolAssump else None
-        _pricing = mkLiqMethod(pricing) if pricing else None
         _rate = lmap(mkRateAssumption, rateAssump) if rateAssump else None
-        assets = lmap(mkAssetUnion, _assets)  # [mkAssetUnion(_) for _ in _assets]
-        req = json.dumps([date, assets, _assumptions, _rate, _pricing], ensure_ascii=False)
+        _pricing = mkLiqMethod(pricing) if pricing else None
+        assets = lmap(mkAssetUnion, _assets) 
+        req = json.dumps([date, assets, _assumptions, _rate, _pricing]
+                         , ensure_ascii=False)
+        #console.print_json(req)
         result = self._send_req(req, url)
         if read:
             return readResult(result)
@@ -539,21 +542,20 @@ def _send_req(self, _req, _url: str, timeout=10, headers={})-> dict | None:
         :return: response in dict
         :rtype: dict | None
         """
-        with console.status("") as status:
-            try:
-                hdrs = self.hdrs | headers
-                r = None
-                if self.session:
-                    r = self.session.post(_url, data=_req.encode('utf-8'), headers=hdrs, verify=False, timeout=timeout)
-                else:
-                    raise AbsboxError(f"❌: None type for session")
-            except (ConnectionRefusedError, ConnectionError):
-                raise AbsboxError(f"❌ Failed to talk to server {_url}")
-            except ReadTimeout:
-                raise AbsboxError(f"❌ Failed to get response from server")
-            if r.status_code != 200:
-                raise EngineError(r)
-            try:
-                return json.loads(r.text)
-            except JSONDecodeError as e:
-                raise EngineError(e)
+        try:
+            hdrs = self.hdrs | headers
+            r = None
+            if self.session:
+                r = self.session.post(_url, data=_req.encode('utf-8'), headers=hdrs, verify=False, timeout=timeout)
+            else:
+                raise AbsboxError(f"❌: None type for session")
+        except (ConnectionRefusedError, ConnectionError):
+            raise AbsboxError(f"❌ Failed to talk to server {_url}")
+        except ReadTimeout:
+            raise AbsboxError(f"❌ Failed to get response from server")
+        if r.status_code != 200:
+            raise EngineError(r)
+        try:
+            return json.loads(r.text)
+        except JSONDecodeError as e:
+            raise EngineError(e)

absbox/local/base.py

@@ -31,6 +31,7 @@
 english_rental_flow = ['Balance', 'Rental']
 china_rental_flow_d = ["日期"] + china_rental_flow
 english_rental_flow_d = ["Date"] + english_rental_flow
+
 ## Loan flow
 china_loan_flow = ["余额", "本金", "利息", "早偿金额", "违约金额", "回收金额", "损失金额", "利率"]
 english_loan_flow = ["Balance", "Principal", "Interest", "Prepayment", "Default", "Recovery", "Loss", "WAC"]
@@ -43,6 +44,12 @@
 china_fixed_flow_d = ["日期"] + china_fixed_flow
 english_fixed_flow_d = ["Date"] + english_fixed_flow
 
+## Receivable 
+china_receivable_flow = ["余额", "应计费用", "本金", "费用", "违约", "回收", "损失"]
+english_receivable_flow = ["Balance", "AccuredFee", "Principal", "Fee", "Default", "Recovery", "Loss"]
+china_receivable_flow_d = ["日期"] + china_receivable_flow
+english_receivable_flow_d = ["Date"] + english_receivable_flow
+
 ## Underlying Bond Flow
 china_uBond_flow = ["余额", "本金", "利息"]
 english_uBond_flow = ["Balance", "Principal", "Interest"]

absbox/local/component.py

@@ -164,6 +164,8 @@ def mkPoolSource(x):
             return "CollectedRental" 
         case "现金" | "Cash" | "现金回款" | "CollectedCash":
             return "CollectedCash"
+        case "费用" | "Fee" | "现金回款" | "CollectedFeePaid":
+            return "CollectedFeePaid"
         case "新增违约" | "Defaults":
             return "NewDefaults"
         case "新增拖欠" | "Delinquencies":
@@ -1131,6 +1133,20 @@ def mkAccRule(x):
         case _ :
             raise RuntimeError(f"Failed to match {x}:mkAccRule")
 
+def mkInvoiceFeeType(x):
+    match x :
+        case ("Fixed", amt) | ("固定", amt):
+            return mkTag(("FixedFee", vNum(amt)))
+        case ("FixedRate", rate) | ("固定比例", rate):
+            return mkTag(("FixedRateFee", vNum(rate)))
+        case ("FactorFee", rate, days, rnd) | ("周期计费", rate, days, rnd):
+            return mkTag(("FactorFee", [vNum(rate), vInt(days), mkRoundingType(rnd)]))
+        case ("AdvanceRate", rate) | ("提前比例", rate):
+            return mkTag(("AdvanceFee", vNum(rate)))
+        case ("CompoundFee", *fs) | ("复合计费", *fs):
+            return mkTag(("CompoundFee", lmap(mkInvoiceFeeType, fs)))
+        case _:
+            raise RuntimeError(f"Failed to match {x}:mkInvoiceFeeType")
 
 def mkCapacity(x):
     match x: 
@@ -1231,6 +1247,12 @@ def mkAsset(x):
                                          ,"period":freqMap[p],"accRule":mkAccRule(ar)
                                          ,"capacity":mkCapacity(cap)} | mkTag("FixedAssetInfo")
                                         ,vInt(rt)]))
+        case ["Invoice", {"start":sd,"originBalance":ob,"originAdvance":oa,"dueDate":dd,"feeType":ft},{"status":status}] :
+            return mkTag(("Invoice",[{"startDate":vDate(sd),"originBalance":vNum(ob),"originAdvance":vNum(oa),"dueDate":vDate(dd),"feeType":mkInvoiceFeeType(ft)} | mkTag("ReceivableInfo")
+                                     ,mkAssetStatus(status)]))
+        case ["Invoice", {"start":sd,"originBalance":ob,"originAdvance":oa,"dueDate":dd},{"status":status}] :
+            return mkTag(("Invoice",[{"startDate":vDate(sd),"originBalance":vNum(ob),"originAdvance":vNum(oa),"dueDate":vDate(dd),"feeType":None} | mkTag("ReceivableInfo")
+                                     ,mkAssetStatus(status)]))
         case _:
             raise RuntimeError(f"Failed to match {x}:mkAsset")
 
@@ -1254,6 +1276,8 @@ def id_by_pool_assets(z):
                 return "RDeal"
             case {"assets": [{'tag': 'FixedAsset'}, *rest]}:
                 return "FDeal"
+            case {"assets": [{'tag': 'Invoice'}, *rest]}:
+                return "VDeal"
             case _:
                 raise RuntimeError(f"Failed to identify deal type {z}")
     y = None
@@ -1311,6 +1335,8 @@ def mkAssumpDefault(x):
             return mkTag(("DefaultCDR", vNum(r)))
         case {"ByAmount": (bal, rs)}:
             return mkTag(("DefaultByAmt", (vNum(bal), vList(rs,float))))
+        case "DefaultAtEnd":
+            return mkTag(("DefaultAtEnd"))
         case _ :
             raise RuntimeError(f"failed to match {x}")
 
@@ -1428,6 +1454,10 @@ def mkExtraStress(y):
         case ("Fixed",utilCurve,priceCurve):
             return mkTag(("FixedAssetAssump",[mkTs("RatioCurve",utilCurve)
                                               ,mkTs("BalanceCurve",priceCurve)]))
+        case ("Receivable", md, mr, mes):
+            d = earlyReturnNone(mkAssumpDefault,md)
+            r = earlyReturnNone(mkAssumpRecovery,mr)
+            return mkTag(("ReceivableAssump",[d, r, mkExtraStress(mes)]))
         case _:
             raise RuntimeError(f"failed to match {x}")
 
@@ -1467,6 +1497,8 @@ def mkAssetUnion(x):
             return mkTag(("LS", mkAsset(x)))
         case "固定资产" | "FixedAsset" : 
             return mkTag(("FA", mkAsset(x)))
+        case "应收帐款" | "Invoice" : 
+            return mkTag(("RE", mkAsset(x)))
         case _:
             raise RuntimeError(f"Failed to match AssetUnion {x}")
 
@@ -1507,7 +1539,8 @@ def mkPoolComp(asOfDate, x, mixFlag) -> dict:
 
 def mkPool(x: dict):
     mapping = {"LDeal": "LPool", "MDeal": "MPool",
-               "IDeal": "IPool", "RDeal": "RPool", "FDeal":"FPool"}
+               "IDeal": "IPool", "RDeal": "RPool", "FDeal":"FPool",
+               "VDeal": "VPool"}
     match x:
         case {"清单": assets, "封包日": d} | {"assets": assets, "cutoffDate": d}:
             _pool = {"assets": [mkAsset(a) for a in assets] , "asOfDate": d}

absbox/local/util.py

@@ -269,6 +269,10 @@ def guess_pool_flow_header(x, l):
             return (china_fixed_flow_d, "日期", False)
         case ('FixedFlow', 6, 'english'):
             return (english_fixed_flow_d, "Date", False)
+        case ('ReceivableFlow', 9, 'chinese'):
+            return (china_receivable_flow_d+china_cumStats, "日期", True)
+        case ('ReceivableFlow', 9, 'english'):
+            return (english_receivable_flow_d+english_cumStats, "Date", True)
         case ('BondFlow', 4, 'chinese'):
             return (china_uBond_flow_d, "日期", False)
         case ('BondFlow', 4, 'english'):

docs/source/analytics.rst

@@ -168,6 +168,38 @@ Installment
 * <default assump> : ``{"CDR":<%>}``
 * <prepayment assump> : ``{"CPR":<%>}``
 
+Receivable 
+^^^^^^^^^^^^^^^^^^^^^
+
+user can set assumption on receivable asset class:
+
+* assume default at last period ( 0 cash received )
+* a CDR way ,whcih is a percentage of current balance remains.
+
+.. code-block:: python
+
+  # apply on asset level
+  r = localAPI.run(test01
+              ,runAssump=[]
+              ,poolAssump = ("ByIndex"
+                                ,([0],(("Receivable", {"CDR":0.12}, None, None)
+                                      ,None,None))
+                                ,([1],(("Receivable", "DefaultAtEnd", None, None)
+                                      ,None,None))
+                                )
+              ,read=True)
+
+  receivableAssump = ("Pool"
+                      ,("Receivable", {"CDR":0.01}, None, None)
+                      ,None
+                      ,None)
+
+  # apply on pool level
+  r = localAPI.run(test01
+              ,runAssump=[]
+              ,poolAssump = receivableAssump
+              ,read=True)
+
 Extra Stress 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/source/modeling.rst

@@ -1349,6 +1349,74 @@ This type of asset can be used to model `future flow of securitization` : `Hotel
   To project cashflow , user MUST set assumption for this type asset.
 
 
+Receivable
+^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.26.5
+
+``Receivable`` is a type of asset which has a fixed amount of receivable in last period, with optional fee collected at end
+
+* if No fee was set, the receivable will be paid off at last period without fee.
+* if there are multiple fee being setup, then ALL fees are sum up and paid off at last period.
+
+syntax
+  ``["Invoice", {<asset description>}, {<status>}]``
+
+  * ``asset description`` -> a map describe the asset
+  * ``status`` -> a map describe the status of asset
+
+* feeType
+
+  * ``Fixed`` -> fixed amount of fee
+  * ``FixedRate`` -> fixed rate of fee, the base was the ``originBalance``
+  * ``AdvanceRate`` -> annualized rate of advance amount, the base was the ``originAdvance``
+  * ``(FactorFee,<service rate>,<days of period>,<rounding>)`` -> total fee = ``service rate`` *  ``originBalance`` * (``days of the invioce``/ ``<days of periods>``)
+  * ``(CompoundFee,<feeType1>,<feeType2>.....)`` -> a compound fee with multiple fee type
+
+
+.. code-block:: python
+
+  receivable = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-06-01"}
+                ,{"status":"Current"}]
+
+
+  receivable1 = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-08-01"
+                  ,"feeType":("Fixed",150)}
+                ,{"status":"Current"}]
+
+  receivable2 = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-06-01"
+                  ,"feeType":("FixedRate",0.1)}
+                ,{"status":"Current"}]
+
+  receivable3 = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-06-01"
+                  ,"feeType":("AdvanceRate", 0.12)}
+                ,{"status":"Current"}]
+
+  receivable4 = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-06-01"
+                  ,"feeType":("FactorFee", 0.01, 25,["floor",0.1])}
+                ,{"status":"Current"}]
+
+  receivable5 = ["Invoice"
+                ,{"start":"2024-04-01","originBalance":2000
+                  ,"originAdvance":1500,"dueDate":"2024-06-01"
+                  ,"feeType":("CompoundFee"
+                              ,("AdvanceRate", 0.12)
+                              ,("Fixed",150)
+                              )}
+                ,{"status":"Current"}]
+
+
+
 Collection Rules 
 -------------------