credit_tools 0.1.0__tar.gz

credit_tools-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Install docs dependencies
+        run: uv sync --extra docs
+
+      - name: Build site
+        run: uv run jupyter-book build --execute --html --ci
+        env:
+          BASE_URL: /${{ github.event.repository.name }}
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

credit_tools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/credit_tools/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Publish to PyPI
+        run: uv publish

credit_tools-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.uv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+
+# MyST build outputs
+_build/

credit_tools-0.1.0/CONTRIBUTING/README.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync
+```
+
+## Adding a rating scale resource
+
+Rating scales live as plain data in [src/credit_tools/resources/](../src/credit_tools/resources/), one JSON file per scale (e.g. `moody.json`, `fitch.json`), mapping `{rating: expected_default_rate}`. `credit_tools.rating.assign_rating` is independent of any specific agency's scale — it just needs a dict like this. To add a new one, drop `resources/<name>.json` in and load it with `load_rating_scale("<name>")`.
+
+## Docs
+
+Examples live as Jupyter notebooks under [docs/](../docs/) and are built with [MyST/Jupyter Book v2](https://mystmd.org), configured by [myst.yml](../myst.yml) at the repo root.
+
+```bash
+uv sync --extra docs
+uv run jupyter-book build --execute --html   # static site in _build/html
+uv run jupyter-book start                    # live preview with hot reload
+```
+
+`docs/` should only contain notebooks (no hand-written markdown/rst pages) — `myst.yml` is the one config file that lives outside it.
+
+### Adding a new notebook
+
+1. Add the `.ipynb` file under `docs/` (or `docs/examples/`).
+2. Add an entry for it under `project.toc` in `myst.yml`, or regenerate the whole table of contents from what's on disk:
+
+   ```bash
+   uv run jupyter-book init --project --site --write-toc
+   ```
+
+   This only rewrites the `toc:` list — it won't touch metadata you've already filled in (title, description, authors). Run it from the repo root; it refuses to run from inside `docs/`.
+
+Docs are rebuilt with `--execute`, so a notebook that no longer runs against the current code will fail CI — that's intentional, it's what keeps the examples honest.
+
+Docs deploy to GitHub Pages automatically on push to `main` via [.github/workflows/docs.yml](../.github/workflows/docs.yml).

credit_tools-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.5
+Name: credit_tools
+Version: 0.1.0
+Summary: Out-of-the-box credit functionalities (risk rating, scoring, and more)
+Author-email: Rafael Saraiva <rsa.saraiva94@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: docs
+Requires-Dist: jupyter-book>=1.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# credit_tools
+
+Multiple out-of-the-box functionalities for credit, installable via pip/uv.
+
+## Install
+
+```bash
+pip install credit_tools
+# or
+uv add credit_tools
+```
+
+## Structure
+
+```
+src/credit_tools/
+    rating/       # generic borrower-rating assignment (independent of any one scale)
+    resources/    # bundled rating scales as data, e.g. resources/moody.json
+```
+
+## Docs
+
+Examples live as Jupyter notebooks in [docs/](docs/), published to GitHub Pages on every push to `main`: https://jumpingdino.github.io/credit_tools/
+
+## Contributing
+
+See [CONTRIBUTING/README.md](CONTRIBUTING/README.md) for dev setup, adding rating scale resources, and building/updating the docs.

credit_tools-0.1.0/README.md

@@ -0,0 +1,27 @@
+# credit_tools
+
+Multiple out-of-the-box functionalities for credit, installable via pip/uv.
+
+## Install
+
+```bash
+pip install credit_tools
+# or
+uv add credit_tools
+```
+
+## Structure
+
+```
+src/credit_tools/
+    rating/       # generic borrower-rating assignment (independent of any one scale)
+    resources/    # bundled rating scales as data, e.g. resources/moody.json
+```
+
+## Docs
+
+Examples live as Jupyter notebooks in [docs/](docs/), published to GitHub Pages on every push to `main`: https://jumpingdino.github.io/credit_tools/
+
+## Contributing
+
+See [CONTRIBUTING/README.md](CONTRIBUTING/README.md) for dev setup, adding rating scale resources, and building/updating the docs.

credit_tools-0.1.0/docs/examples/rating.ipynb

@@ -0,0 +1,130 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Rating assignment\n",
+    "\n",
+    "`credit_tools.rating.assign_rating` maps borrowers to rating buckets given:\n",
+    "\n",
+    "- a `borrower_id`, `ml_score`, and observed `defaulted` outcome per borrower, and\n",
+    "- a `rating_scale`: a `{rating: expected_default_rate}` dictionary.\n",
+    "\n",
+    "It fits a monotonic realized-default-rate curve against `ml_score` (higher score = higher risk), then maps each borrower's calibrated default probability to the rating with the closest expected default rate. The scale itself is just data — Moody's idealized default rates ship as a bundled resource, but any `{rating: edr}` mapping works."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import random\n",
+    "\n",
+    "from credit_tools.rating import assign_rating\n",
+    "from credit_tools.resources import load_rating_scale\n",
+    "\n",
+    "random.seed(0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Load a rating scale\n",
+    "\n",
+    "`load_rating_scale` reads any bundled `resources/<name>.json` file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "scale = load_rating_scale(\"moody\")\n",
+    "dict(list(scale.items())[:5])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Simulate a borrower portfolio\n",
+    "\n",
+    "In practice `ml_scores` and `defaulted` come from your model's predictions and observed outcomes. Here we simulate them so the notebook is self-contained."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "n = 2000\n",
+    "borrower_ids = [f\"b{i}\" for i in range(n)]\n",
+    "ml_scores = [random.random() for _ in range(n)]\n",
+    "defaulted = [random.random() < score for score in ml_scores]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Assign ratings"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ratings = assign_rating(borrower_ids, ml_scores, defaulted, scale)\n",
+    "{borrower_ids[i]: ratings[borrower_ids[i]] for i in range(5)}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Check calibration\n",
+    "\n",
+    "For each rating, the realized default rate among the borrowers assigned to it should track the target expected default rate from the scale."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from collections import defaultdict\n",
+    "\n",
+    "realized = defaultdict(list)\n",
+    "for i, borrower_id in enumerate(borrower_ids):\n",
+    "    realized[ratings[borrower_id]].append(defaulted[i])\n",
+    "\n",
+    "for rating in sorted(realized, key=lambda r: scale[r]):\n",
+    "    outcomes = realized[rating]\n",
+    "    print(\n",
+    "        f\"{rating:5s} target_edr={scale[rating]:.4f}  n={len(outcomes):4d}  \"\n",
+    "        f\"realized_dr={sum(outcomes) / len(outcomes):.4f}\"\n",
+    "    )"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

credit_tools-0.1.0/docs/index.ipynb

@@ -0,0 +1,42 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# credit_tools\n",
+    "\n",
+    "Out-of-the-box credit functionalities, installable via pip/uv.\n",
+    "\n",
+    "```bash\n",
+    "pip install credit_tools\n",
+    "```\n",
+    "\n",
+    "See the examples in the sidebar for each functionality, e.g. [rating assignment](examples/rating.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import credit_tools\n",
+    "\n",
+    "credit_tools.__version__"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

credit_tools-0.1.0/myst.yml

@@ -0,0 +1,19 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+project:
+  id: ad4e1e45-29ba-4bf5-917d-5f149e4469d5
+  title: credit_tools
+  description: Out-of-the-box credit functionalities
+  authors:
+    - name: Rafael Saraiva
+  github: https://github.com/JumpingDino/credit_tools
+  toc:
+    - file: docs/index.ipynb
+    - title: Examples
+      children:
+        - file: docs/examples/rating.ipynb
+site:
+  template: book-theme
+  # options:
+  #   favicon: favicon.ico
+  #   logo: site_logo.png

credit_tools-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "credit_tools"
+version = "0.1.0"
+description = "Out-of-the-box credit functionalities (risk rating, scoring, and more)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Rafael Saraiva", email = "rsa.saraiva94@gmail.com" }]
+dependencies = []
+
+[project.optional-dependencies]
+docs = ["jupyter-book>=1.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/credit_tools"]
+
+[tool.uv]
+package = true

credit_tools-0.1.0/src/credit_tools/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("credit_tools")

credit_tools-0.1.0/src/credit_tools/rating/__init__.py

@@ -0,0 +1,3 @@
+from credit_tools.rating.core import assign_rating
+
+__all__ = ["assign_rating"]

credit_tools-0.1.0/src/credit_tools/rating/core.py

@@ -0,0 +1,64 @@
+from collections.abc import Sequence
+
+
+def assign_rating(
+    borrower_ids: Sequence[str],
+    ml_scores: Sequence[float],
+    defaulted: Sequence[bool],
+    rating_scale: dict[str, float],
+) -> dict[str, str]:
+    if not (len(borrower_ids) == len(ml_scores) == len(defaulted)):
+        raise ValueError("borrower_ids, ml_scores, and defaulted must have the same length")
+    if not rating_scale:
+        raise ValueError("rating_scale must not be empty")
+
+    order = sorted(range(len(ml_scores)), key=lambda i: ml_scores[i])
+    sorted_scores = [ml_scores[i] for i in order]
+    sorted_targets = [float(defaulted[i]) for i in order]
+
+    calibrated_pd = _isotonic_regression(sorted_scores, sorted_targets)
+    ratings_by_edr = sorted(rating_scale.items(), key=lambda item: item[1])
+
+    assigned: dict[str, str] = {}
+    for i, pd in zip(order, calibrated_pd):
+        rating, _ = min(ratings_by_edr, key=lambda item: abs(item[1] - pd))
+        assigned[borrower_ids[i]] = rating
+    return assigned
+
+
+def _isotonic_regression(sorted_scores: Sequence[float], sorted_targets: Sequence[float]) -> list[float]:
+    """Pool-adjacent-violators fit of an increasing curve through (score, target)."""
+    unique_scores: list[float] = []
+    group_sums: list[float] = []
+    group_weights: list[float] = []
+    for score, target in zip(sorted_scores, sorted_targets):
+        if unique_scores and unique_scores[-1] == score:
+            group_sums[-1] += target
+            group_weights[-1] += 1
+        else:
+            unique_scores.append(score)
+            group_sums.append(target)
+            group_weights.append(1)
+
+    values = [s / w for s, w in zip(group_sums, group_weights)]
+    weights = list(group_weights)
+    sizes = [1] * len(values)
+
+    i = 0
+    while i < len(values) - 1:
+        if values[i] <= values[i + 1]:
+            i += 1
+            continue
+        merged_weight = weights[i] + weights[i + 1]
+        merged_value = (values[i] * weights[i] + values[i + 1] * weights[i + 1]) / merged_weight
+        values[i : i + 2] = [merged_value]
+        weights[i : i + 2] = [merged_weight]
+        sizes[i : i + 2] = [sizes[i] + sizes[i + 1]]
+        i = max(i - 1, 0)
+
+    fitted_by_group: list[float] = []
+    for value, size in zip(values, sizes):
+        fitted_by_group.extend([value] * size)
+
+    fitted_by_score = dict(zip(unique_scores, fitted_by_group))
+    return [fitted_by_score[score] for score in sorted_scores]

credit_tools-0.1.0/src/credit_tools/resources/__init__.py

@@ -0,0 +1,8 @@
+import json
+from importlib import resources
+
+
+def load_rating_scale(name: str) -> dict[str, float]:
+    path = resources.files(__package__).joinpath(f"{name}.json")
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)

credit_tools-0.1.0/src/credit_tools/resources/fitch.json

@@ -0,0 +1,23 @@
+{
+  "AAA": 0.0001,
+  "AA+": 0.0002,
+  "AA": 0.0003,
+  "AA-": 0.0004,
+  "A+": 0.0006,
+  "A": 0.0008,
+  "A-": 0.0012,
+  "BBB+": 0.0020,
+  "BBB": 0.0030,
+  "BBB-": 0.0045,
+  "BB+": 0.0075,
+  "BB": 0.0110,
+  "BB-": 0.0170,
+  "B+": 0.0270,
+  "B": 0.0400,
+  "B-": 0.0600,
+  "CCC+": 0.0900,
+  "CCC": 0.1300,
+  "CCC-": 0.1900,
+  "CC": 0.3000,
+  "C": 0.5000
+}

credit_tools-0.1.0/src/credit_tools/resources/moody.json

@@ -0,0 +1,23 @@
+{
+  "Aaa": 0.0001,
+  "Aa1": 0.0002,
+  "Aa2": 0.0003,
+  "Aa3": 0.0004,
+  "A1": 0.0006,
+  "A2": 0.0008,
+  "A3": 0.0012,
+  "Baa1": 0.0020,
+  "Baa2": 0.0030,
+  "Baa3": 0.0045,
+  "Ba1": 0.0075,
+  "Ba2": 0.0110,
+  "Ba3": 0.0170,
+  "B1": 0.0270,
+  "B2": 0.0400,
+  "B3": 0.0600,
+  "Caa1": 0.0900,
+  "Caa2": 0.1300,
+  "Caa3": 0.1900,
+  "Ca": 0.3000,
+  "C": 0.5000
+}