updatesupport-finance 0.1.0__tar.gz

updatesupport_finance-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 updatesupport contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

updatesupport_finance-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include examples *.py

updatesupport_finance-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: updatesupport-finance
+Version: 0.1.0
+Summary: Financial model-risk extensions for updatesupport
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nahuaque/updatesupport
+Project-URL: Repository, https://github.com/nahuaque/updatesupport
+Project-URL: Issues, https://github.com/nahuaque/updatesupport/issues
+Keywords: credit-risk,expected-loss,financial-model-risk,model-validation,updatesupport
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: updatesupport>=0.1.1
+Dynamic: license-file
+
+# updatesupport-finance
+
+Financial model-risk extensions for
+[`updatesupport`](https://pypi.org/project/updatesupport/).
+
+`updatesupport-finance` audits whether a public risk segmentation is stable
+enough to support a reported portfolio metric.
+
+The core question is:
+
+> If a model report only shows risk by coarse public buckets such as
+> `product x region x FICO band x LTV band`, could the reported expected-loss
+> estimate materially change if the hidden mix inside those buckets shifted?
+
+This is a segmentation adequacy check for reported risk metrics. It is designed
+for model-review and portfolio-monitoring artifacts, not as a replacement for
+model validation, calibration, backtesting, or statistical uncertainty analysis.
+
+Install directly:
+
+```bash
+pip install updatesupport-finance
+uv add updatesupport-finance
+```
+
+Or through the core package extra:
+
+```bash
+pip install "updatesupport[finance]"
+uv add "updatesupport[finance]"
+```
+
+The package provides finance-oriented row metrics, Q preset aliases, portfolio
+compilation, and a model-risk report profile while keeping financial vocabulary
+out of the core `updatesupport` package.
+
+## Why This Is Useful
+
+Financial analysts already monitor model performance, population drift,
+calibration, overrides, and scenario sensitivity. Those checks usually ask
+whether the model or portfolio changed.
+
+`updatesupport-finance` asks a different question:
+
+> Is the reporting segmentation itself adequate for the metric being reported?
+
+For example, a validation pack may report expected loss by:
+
+- `product`
+- `region`
+- `fico_band`
+- `ltv_band`
+
+But inside those public buckets, hidden composition may vary by:
+
+- broker channel
+- employment type
+- vintage
+- hardship history
+- documentation type
+- local housing market
+- borrower cashflow pattern
+
+If those hidden subgroups have different expected-loss rates, the public
+segmentation may not fully support the reported aggregate. The report quantifies
+that hidden-composition ambiguity and identifies which hidden variables would
+most improve the public segmentation.
+
+## What The Report Separates
+
+The package is intentionally narrow. It separates:
+
+- reported risk estimate: the supplied metric, such as expected loss or default
+  rate
+- statistical uncertainty: confidence intervals or model uncertainty supplied by
+  other workflows
+- hidden-composition ambiguity: how far the reported metric can move when hidden
+  mix shifts inside fixed public buckets
+- refinement recommendations: hidden fields that would make the public
+  representation more stable
+
+This is not a confidence interval and not a full model-risk-management system.
+It is a reviewable control for one practical question: whether the reporting
+representation is stable enough for the risk metric.
+
+## Analyst Workflow
+
+1. Choose public buckets from the model report.
+2. Choose hidden refinements that are available internally but not shown in the
+   public segmentation.
+3. Choose the target risk metric.
+4. Choose a plausible hidden-mix shift preset.
+5. Set a review threshold for hidden-composition ambiguity.
+6. Attach the generated Markdown report to a model-review or monitoring pack.
+
+The review status is deliberately simple:
+
+- `pass`: ambiguity and public adequacy checks are within the chosen thresholds
+- `attention required`: the public segmentation may need refinement or explicit
+  acceptance of the ambiguity band
+
+## Example
+
+```python
+import updatesupport_finance as usf
+
+report = usf.model_risk_report(
+    portfolio,
+    public=["product", "region", "fico_band", "ltv_band"],
+    hidden=[
+        "product",
+        "region",
+        "fico_band",
+        "ltv_band",
+        "broker_channel",
+        "employment_type",
+        "vintage",
+    ],
+    metric=usf.expected_loss(pd="pd", lgd="lgd"),
+    exposure="ead",
+    q=usf.q_portfolio_mix_shift(radius=0.25),
+    model_id="EL_RETAIL_2026Q2",
+    portfolio_name="Retail credit portfolio",
+    as_of_date="2026-06-30",
+    intended_use="Expected-loss segmentation model review",
+    ambiguity_limit=0.0025,
+    public_adequacy_required=False,
+)
+
+print(report.to_markdown())
+```
+
+The report answers:
+
+- What is the reported portfolio risk estimate?
+- What range is still possible under hidden mix shifts?
+- Does the ambiguity exceed the review threshold?
+- Which public buckets drive the instability?
+- Which hidden fields are most valuable as public refinements?
+- Which small public segmentation sits on the stability frontier, and why did
+  it beat nearby alternatives?
+
+A synthetic portfolio example is available in `examples/model_risk_portfolio.py`
+in the source repository:
+
+```bash
+uv run --package updatesupport-finance python \
+  packages/updatesupport-finance/examples/model_risk_portfolio.py
+```
+
+The example prints both the finance model-risk report and a core
+`public_representation_frontier(...)` report for the same expected-loss metric.
+The frontier section compares baseline versus selected ambiguity, close
+dominated alternatives, and any screened-out refinement fields.
+
+To write the Markdown report:
+
+```bash
+uv run --package updatesupport-finance python \
+  packages/updatesupport-finance/examples/model_risk_portfolio.py \
+  --output data/finance_model_risk_report.md
+```

updatesupport_finance-0.1.0/README.md

@@ -0,0 +1,162 @@
+# updatesupport-finance
+
+Financial model-risk extensions for
+[`updatesupport`](https://pypi.org/project/updatesupport/).
+
+`updatesupport-finance` audits whether a public risk segmentation is stable
+enough to support a reported portfolio metric.
+
+The core question is:
+
+> If a model report only shows risk by coarse public buckets such as
+> `product x region x FICO band x LTV band`, could the reported expected-loss
+> estimate materially change if the hidden mix inside those buckets shifted?
+
+This is a segmentation adequacy check for reported risk metrics. It is designed
+for model-review and portfolio-monitoring artifacts, not as a replacement for
+model validation, calibration, backtesting, or statistical uncertainty analysis.
+
+Install directly:
+
+```bash
+pip install updatesupport-finance
+uv add updatesupport-finance
+```
+
+Or through the core package extra:
+
+```bash
+pip install "updatesupport[finance]"
+uv add "updatesupport[finance]"
+```
+
+The package provides finance-oriented row metrics, Q preset aliases, portfolio
+compilation, and a model-risk report profile while keeping financial vocabulary
+out of the core `updatesupport` package.
+
+## Why This Is Useful
+
+Financial analysts already monitor model performance, population drift,
+calibration, overrides, and scenario sensitivity. Those checks usually ask
+whether the model or portfolio changed.
+
+`updatesupport-finance` asks a different question:
+
+> Is the reporting segmentation itself adequate for the metric being reported?
+
+For example, a validation pack may report expected loss by:
+
+- `product`
+- `region`
+- `fico_band`
+- `ltv_band`
+
+But inside those public buckets, hidden composition may vary by:
+
+- broker channel
+- employment type
+- vintage
+- hardship history
+- documentation type
+- local housing market
+- borrower cashflow pattern
+
+If those hidden subgroups have different expected-loss rates, the public
+segmentation may not fully support the reported aggregate. The report quantifies
+that hidden-composition ambiguity and identifies which hidden variables would
+most improve the public segmentation.
+
+## What The Report Separates
+
+The package is intentionally narrow. It separates:
+
+- reported risk estimate: the supplied metric, such as expected loss or default
+  rate
+- statistical uncertainty: confidence intervals or model uncertainty supplied by
+  other workflows
+- hidden-composition ambiguity: how far the reported metric can move when hidden
+  mix shifts inside fixed public buckets
+- refinement recommendations: hidden fields that would make the public
+  representation more stable
+
+This is not a confidence interval and not a full model-risk-management system.
+It is a reviewable control for one practical question: whether the reporting
+representation is stable enough for the risk metric.
+
+## Analyst Workflow
+
+1. Choose public buckets from the model report.
+2. Choose hidden refinements that are available internally but not shown in the
+   public segmentation.
+3. Choose the target risk metric.
+4. Choose a plausible hidden-mix shift preset.
+5. Set a review threshold for hidden-composition ambiguity.
+6. Attach the generated Markdown report to a model-review or monitoring pack.
+
+The review status is deliberately simple:
+
+- `pass`: ambiguity and public adequacy checks are within the chosen thresholds
+- `attention required`: the public segmentation may need refinement or explicit
+  acceptance of the ambiguity band
+
+## Example
+
+```python
+import updatesupport_finance as usf
+
+report = usf.model_risk_report(
+    portfolio,
+    public=["product", "region", "fico_band", "ltv_band"],
+    hidden=[
+        "product",
+        "region",
+        "fico_band",
+        "ltv_band",
+        "broker_channel",
+        "employment_type",
+        "vintage",
+    ],
+    metric=usf.expected_loss(pd="pd", lgd="lgd"),
+    exposure="ead",
+    q=usf.q_portfolio_mix_shift(radius=0.25),
+    model_id="EL_RETAIL_2026Q2",
+    portfolio_name="Retail credit portfolio",
+    as_of_date="2026-06-30",
+    intended_use="Expected-loss segmentation model review",
+    ambiguity_limit=0.0025,
+    public_adequacy_required=False,
+)
+
+print(report.to_markdown())
+```
+
+The report answers:
+
+- What is the reported portfolio risk estimate?
+- What range is still possible under hidden mix shifts?
+- Does the ambiguity exceed the review threshold?
+- Which public buckets drive the instability?
+- Which hidden fields are most valuable as public refinements?
+- Which small public segmentation sits on the stability frontier, and why did
+  it beat nearby alternatives?
+
+A synthetic portfolio example is available in `examples/model_risk_portfolio.py`
+in the source repository:
+
+```bash
+uv run --package updatesupport-finance python \
+  packages/updatesupport-finance/examples/model_risk_portfolio.py
+```
+
+The example prints both the finance model-risk report and a core
+`public_representation_frontier(...)` report for the same expected-loss metric.
+The frontier section compares baseline versus selected ambiguity, close
+dominated alternatives, and any screened-out refinement fields.
+
+To write the Markdown report:
+
+```bash
+uv run --package updatesupport-finance python \
+  packages/updatesupport-finance/examples/model_risk_portfolio.py \
+  --output data/finance_model_risk_report.md
+```

updatesupport_finance-0.1.0/examples/model_risk_portfolio.py

@@ -0,0 +1,326 @@
+"""Synthetic financial model-risk report example.
+
+Run from the repository root with:
+
+    uv run --package updatesupport-finance python \
+        packages/updatesupport-finance/examples/model_risk_portfolio.py
+
+Optionally write the Markdown report:
+
+    uv run --package updatesupport-finance python \
+        packages/updatesupport-finance/examples/model_risk_portfolio.py \
+        --output data/finance_model_risk_report.md
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+import updatesupport as us
+import updatesupport_finance as usf
+
+
+PUBLIC_COLUMNS = ("product", "region", "fico_band", "ltv_band")
+HIDDEN_COLUMNS = (
+    "product",
+    "region",
+    "fico_band",
+    "ltv_band",
+    "broker_channel",
+    "employment_type",
+    "vintage",
+    "hardship_history",
+    "documentation_type",
+    "local_housing_market",
+    "cashflow_pattern",
+)
+CANDIDATE_REFINEMENTS = (
+    "broker_channel",
+    "employment_type",
+    "vintage",
+    "hardship_history",
+    "documentation_type",
+    "local_housing_market",
+    "cashflow_pattern",
+)
+
+
+def synthetic_portfolio_rows() -> list[dict[str, Any]]:
+    """Return a small synthetic retail-credit portfolio.
+
+    The public reporting segmentation is intentionally coarse. Several hidden
+    subgroups live inside the same public buckets and have different expected
+    loss rates, which makes the representation-stability question visible.
+    """
+
+    return [
+        {
+            "account_count": 140,
+            "product": "mortgage",
+            "region": "north",
+            "fico_band": "prime",
+            "ltv_band": "low",
+            "broker_channel": "broker",
+            "employment_type": "salaried",
+            "vintage": "2024",
+            "hardship_history": "none",
+            "documentation_type": "full_doc",
+            "local_housing_market": "stable",
+            "cashflow_pattern": "stable",
+            "pd": 0.014,
+            "lgd": 0.32,
+            "ead": 15_400_000,
+        },
+        {
+            "account_count": 90,
+            "product": "mortgage",
+            "region": "north",
+            "fico_band": "prime",
+            "ltv_band": "low",
+            "broker_channel": "direct",
+            "employment_type": "self_employed",
+            "vintage": "2023",
+            "hardship_history": "prior",
+            "documentation_type": "alt_doc",
+            "local_housing_market": "cooling",
+            "cashflow_pattern": "seasonal",
+            "pd": 0.038,
+            "lgd": 0.46,
+            "ead": 8_100_000,
+        },
+        {
+            "account_count": 110,
+            "product": "mortgage",
+            "region": "north",
+            "fico_band": "prime",
+            "ltv_band": "medium",
+            "broker_channel": "broker",
+            "employment_type": "salaried",
+            "vintage": "2022",
+            "hardship_history": "none",
+            "documentation_type": "full_doc",
+            "local_housing_market": "cooling",
+            "cashflow_pattern": "stable",
+            "pd": 0.023,
+            "lgd": 0.39,
+            "ead": 12_650_000,
+        },
+        {
+            "account_count": 70,
+            "product": "mortgage",
+            "region": "north",
+            "fico_band": "prime",
+            "ltv_band": "medium",
+            "broker_channel": "correspondent",
+            "employment_type": "contractor",
+            "vintage": "2021",
+            "hardship_history": "prior",
+            "documentation_type": "full_doc",
+            "local_housing_market": "declining",
+            "cashflow_pattern": "volatile",
+            "pd": 0.049,
+            "lgd": 0.52,
+            "ead": 7_700_000,
+        },
+        {
+            "account_count": 85,
+            "product": "mortgage",
+            "region": "south",
+            "fico_band": "near_prime",
+            "ltv_band": "high",
+            "broker_channel": "broker",
+            "employment_type": "salaried",
+            "vintage": "2024",
+            "hardship_history": "none",
+            "documentation_type": "full_doc",
+            "local_housing_market": "stable",
+            "cashflow_pattern": "stable",
+            "pd": 0.058,
+            "lgd": 0.56,
+            "ead": 7_225_000,
+        },
+        {
+            "account_count": 65,
+            "product": "mortgage",
+            "region": "south",
+            "fico_band": "near_prime",
+            "ltv_band": "high",
+            "broker_channel": "correspondent",
+            "employment_type": "self_employed",
+            "vintage": "2022",
+            "hardship_history": "current",
+            "documentation_type": "alt_doc",
+            "local_housing_market": "declining",
+            "cashflow_pattern": "volatile",
+            "pd": 0.118,
+            "lgd": 0.67,
+            "ead": 5_525_000,
+        },
+        {
+            "account_count": 160,
+            "product": "auto",
+            "region": "west",
+            "fico_band": "prime",
+            "ltv_band": "medium",
+            "broker_channel": "dealer",
+            "employment_type": "salaried",
+            "vintage": "2024",
+            "hardship_history": "none",
+            "documentation_type": "full_doc",
+            "local_housing_market": "stable",
+            "cashflow_pattern": "stable",
+            "pd": 0.031,
+            "lgd": 0.50,
+            "ead": 3_840_000,
+        },
+        {
+            "account_count": 100,
+            "product": "auto",
+            "region": "west",
+            "fico_band": "prime",
+            "ltv_band": "medium",
+            "broker_channel": "online",
+            "employment_type": "contractor",
+            "vintage": "2023",
+            "hardship_history": "prior",
+            "documentation_type": "stated_income",
+            "local_housing_market": "stable",
+            "cashflow_pattern": "seasonal",
+            "pd": 0.061,
+            "lgd": 0.58,
+            "ead": 2_400_000,
+        },
+        {
+            "account_count": 190,
+            "product": "card",
+            "region": "east",
+            "fico_band": "near_prime",
+            "ltv_band": "na",
+            "broker_channel": "direct",
+            "employment_type": "salaried",
+            "vintage": "2024",
+            "hardship_history": "none",
+            "documentation_type": "full_doc",
+            "local_housing_market": "stable",
+            "cashflow_pattern": "stable",
+            "pd": 0.074,
+            "lgd": 0.82,
+            "ead": 1_900_000,
+        },
+        {
+            "account_count": 120,
+            "product": "card",
+            "region": "east",
+            "fico_band": "near_prime",
+            "ltv_band": "na",
+            "broker_channel": "affiliate",
+            "employment_type": "contractor",
+            "vintage": "2022",
+            "hardship_history": "current",
+            "documentation_type": "thin_file",
+            "local_housing_market": "cooling",
+            "cashflow_pattern": "volatile",
+            "pd": 0.132,
+            "lgd": 0.90,
+            "ead": 1_200_000,
+        },
+    ]
+
+
+def build_report(
+    *,
+    q_radius: float = 0.35,
+    ambiguity_limit: float = 0.006,
+) -> usf.ModelRiskReport:
+    return usf.model_risk_report(
+        synthetic_portfolio_rows(),
+        public=PUBLIC_COLUMNS,
+        hidden=HIDDEN_COLUMNS,
+        metric=usf.expected_loss(pd="pd", lgd="lgd"),
+        exposure="ead",
+        candidate_refinements=CANDIDATE_REFINEMENTS,
+        q=usf.q_portfolio_mix_shift(radius=q_radius),
+        model_id="EL_SYNTHETIC_RETAIL_001",
+        portfolio_name="Synthetic retail credit portfolio",
+        as_of_date="2026-06-30",
+        intended_use="Expected-loss segmentation model review",
+        ambiguity_limit=ambiguity_limit,
+        public_adequacy_required=False,
+        top=5,
+    )
+
+
+def build_frontier(
+    *,
+    q_radius: float = 0.35,
+    ambiguity_limit: float = 0.006,
+) -> us.PublicRepresentationFrontier:
+    """Choose the smallest stable public segmentation for the portfolio metric."""
+
+    return us.public_representation_frontier(
+        synthetic_portfolio_rows(),
+        base_public=PUBLIC_COLUMNS,
+        hidden=HIDDEN_COLUMNS,
+        target=usf.expected_loss(pd="pd", lgd="lgd"),
+        weight="ead",
+        candidate_refinements=CANDIDATE_REFINEMENTS,
+        q_presets=(
+            "saturated",
+            usf.q_portfolio_mix_shift(radius=q_radius),
+            "observed",
+        ),
+        min_cell_weights=(1.0,),
+        ambiguity_limit=ambiguity_limit,
+        bucket_budget=12,
+        search="beam",
+        beam_width=8,
+        max_added_columns=3,
+        max_evaluations=96,
+        title="Synthetic Finance Public Representation Frontier",
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate a synthetic finance model-risk report.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Optional Markdown output path.",
+    )
+    parser.add_argument(
+        "--q-radius",
+        type=float,
+        default=0.35,
+        help="Portfolio mix-shift radius for the bounded-shift Q preset.",
+    )
+    parser.add_argument(
+        "--ambiguity-limit",
+        type=float,
+        default=0.006,
+        help="Review threshold for hidden-composition ambiguity.",
+    )
+    args = parser.parse_args()
+
+    report = build_report(
+        q_radius=args.q_radius,
+        ambiguity_limit=args.ambiguity_limit,
+    )
+    frontier = build_frontier(
+        q_radius=args.q_radius,
+        ambiguity_limit=args.ambiguity_limit,
+    )
+    markdown = report.to_markdown() + "\n\n" + frontier.to_markdown()
+    if args.output is None:
+        print(markdown)
+        return
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(markdown + "\n", encoding="utf-8")
+    print(f"Wrote {args.output}")
+
+
+if __name__ == "__main__":
+    main()