pybrinson 1.0.0__tar.gz

pybrinson-1.0.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# uv
+.venv/
+uv.lock.bak
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/

pybrinson-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pybrinson 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.

pybrinson-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pybrinson
+Version: 1.0.0
+Summary: Portfolio return attribution in Python: Brinson-Hood-Beebower, Brinson-Fachler, and multi-period linking.
+Project-URL: Homepage, https://github.com/gghez/pybrinson
+Project-URL: Repository, https://github.com/gghez/pybrinson
+Project-URL: Issues, https://github.com/gghez/pybrinson/issues
+Author: pybrinson contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asset-management,attribution,brinson,finance,performance,portfolio
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# pybrinson
+
+[![CI](https://github.com/gghez/pybrinson/actions/workflows/ci.yml/badge.svg)](https://github.com/gghez/pybrinson/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Portfolio return attribution in Python — with sources you can audit.
+
+`pybrinson` decomposes a portfolio's excess return versus a benchmark into
+**allocation**, **selection**, and **interaction** effects, across any
+user-defined classification (sector, country, asset class). Every formula
+ships with its mathematical statement, an academic citation, and a
+clickable URL — readers can verify the math without leaving the file.
+
+It targets the gap left by the existing Python finance stack: R has the
+`pa` package on CRAN and MATLAB ships `brinsonAttribution`, but no
+maintained PyPI package implements the Brinson family of models.
+
+## Status
+
+v1.0 — single-period BHB and Brinson-Fachler plus Cariño / GRAP /
+geometric multi-period linking. Single-level classification only;
+nested hierarchies are scheduled for v1.1.
+
+## Methods supported
+
+| | Method | Reference |
+|---|---|---|
+| Single-period | Brinson-Hood-Beebower (3-effect) | Brinson, Hood & Beebower (1986) |
+| Single-period | Brinson-Fachler (3-effect) | Brinson & Fachler (1985) |
+| Multi-period linking | Cariño log-smoothing | Cariño (1999) |
+| Multi-period linking | GRAP factors | GRAP (1997) |
+| Multi-period linking | Geometric (Bacon) | Bacon (2008), chap. 6 |
+
+Deferred to v1.1+: Menchero / Frongello linking, multi-level (nested)
+classification, currency attribution.
+
+## Install
+
+```bash
+pip install pybrinson
+```
+
+`pybrinson` has **zero runtime dependencies** — just the Python standard
+library. Requires Python 3.14+.
+
+## Quickstart
+
+```python
+from pybrinson import Segment, bhb
+
+segments = [
+    Segment("UK Equity", portfolio_weight=0.40, benchmark_weight=0.40,
+            portfolio_return=0.20, benchmark_return=0.10),
+    Segment("Japan Equity", portfolio_weight=0.30, benchmark_weight=0.20,
+            portfolio_return=-0.05, benchmark_return=-0.04),
+    Segment("US Equity", portfolio_weight=0.30, benchmark_weight=0.40,
+            portfolio_return=0.06, benchmark_return=0.08),
+]
+
+result = bhb(segments, period="2024-Q1")
+print(result)
+```
+
+```text
+BHB attribution — period 2024-Q1
+  R_p = 8.3000%   R_b = 6.4000%   excess = 1.9000%
+
+Segment       Allocation  Selection  Interaction     Total
+------------  ----------  ---------  -----------  --------
+UK Equity        0.0000%    4.0000%      0.0000%   4.0000%
+Japan Equity    -0.4000%   -0.2000%     -0.1000%  -0.7000%
+US Equity       -0.8000%   -0.8000%      0.2000%  -1.4000%
+Total           -1.2000%    3.0000%      0.1000%   1.9000%
+```
+
+The identity ``allocation + selection + interaction == excess_return``
+holds within ``1e-9`` by construction; pybrinson **raises**
+`AttributionError` rather than storing a silent residual when it fails.
+
+### Multi-period linking
+
+```python
+from pybrinson import bhb, link_carino, Segment
+
+period_attrs = [
+    bhb([Segment("Equities", 0.6, 0.5, 0.10, 0.05),
+         Segment("Bonds",    0.4, 0.5, 0.05, 0.10)], period="P1"),
+    bhb([Segment("Equities", 0.5, 0.5, 0.20, 0.10),
+         Segment("Bonds",    0.5, 0.5, 0.05, 0.10)], period="P2"),
+]
+
+print(link_carino(period_attrs))
+```
+
+See `examples/` for runnable scripts covering BHB, Brinson-Fachler, and
+Cariño / GRAP / geometric linking.
+
+## Design principles
+
+- **Pure Python first.** Zero runtime dependencies. Realistic attribution
+  inputs are small (≤1k segments × ≤1k periods); a NumPy dependency
+  would not pay for itself.
+- **Specification-driven, externally verified.** Every function carries
+  its formula, an academic citation, and a clickable URL. The math is
+  cross-checked against published worked examples.
+- **No silent residuals.** Identity failures raise. Bad inputs raise.
+  pybrinson never imputes, rescales or swallows residuals.
+- **Typed and tested.** Public API is fully type-annotated; ships
+  `py.typed`; tests cover both pinned worked examples and randomised
+  identity checks.
+
+## Positioning vs `ppar` / `fincore`
+
+| | `ppar` | `fincore` | `pybrinson` |
+|---|---|---|---|
+| BHB | no | yes | yes |
+| Brinson-Fachler 3-effect | 2-effect only | no | yes |
+| Cariño linking | yes | no | yes |
+| GRAP linking | no | no | **yes** |
+| Geometric linking | no | no | **yes** |
+| Inline source citations | no | no | **mandatory** |
+| Identity failure handling | n/a | silent residual | **raises** |
+| Runtime dependencies | 9 | 2 | **0** |
+
+See `docs/implementation-v1.md` for the audited findings against pinned
+upstream commits.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and targets Python 3.14.
+
+```bash
+uv sync                  # install deps, fetch Python 3.14 if needed
+uv run pytest            # full test suite
+uv run pytest -k bhb     # subset
+uv build                 # sdist + wheel into dist/
+```
+
+## References
+
+Primary papers cited in the source:
+
+- Brinson, G. P., Hood, L. R., & Beebower, G. L. (1986). "Determinants of Portfolio Performance." *Financial Analysts Journal*, 42(4). [DOI](https://doi.org/10.2469/faj.v42.n4.39)
+- Brinson, G. P., & Fachler, N. (1985). "Measuring Non-U.S. Equity Portfolio Performance." *Journal of Portfolio Management*, 11(3). [DOI](https://doi.org/10.3905/jpm.1985.409005)
+- Cariño, D. R. (1999). "Combining Attribution Effects Over Time." *Journal of Performance Measurement*, 3(4).
+- Groupe de Recherche en Attribution de Performance (1997). *Synthèse des modèles d'attribution de performance*.
+- Bacon, C. R. (2008). *Practical Portfolio Performance Measurement and Attribution*, 2nd ed., Wiley. [Wiley page](https://www.wiley.com/en-us/Practical+Portfolio+Performance+Measurement+and+Attribution%2C+2nd+Edition-p-9780470059289)
+- Bacon, C. R. (2019). *Performance Attribution: History and Progress*. CFA Institute Research Foundation. [Free PDF](https://www.cfainstitute.org/-/media/documents/book/rf-publication/2019/rf-v2019-n4-1-pdf.pdf)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pybrinson-1.0.0/README.md

@@ -0,0 +1,152 @@
+# pybrinson
+
+[![CI](https://github.com/gghez/pybrinson/actions/workflows/ci.yml/badge.svg)](https://github.com/gghez/pybrinson/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Portfolio return attribution in Python — with sources you can audit.
+
+`pybrinson` decomposes a portfolio's excess return versus a benchmark into
+**allocation**, **selection**, and **interaction** effects, across any
+user-defined classification (sector, country, asset class). Every formula
+ships with its mathematical statement, an academic citation, and a
+clickable URL — readers can verify the math without leaving the file.
+
+It targets the gap left by the existing Python finance stack: R has the
+`pa` package on CRAN and MATLAB ships `brinsonAttribution`, but no
+maintained PyPI package implements the Brinson family of models.
+
+## Status
+
+v1.0 — single-period BHB and Brinson-Fachler plus Cariño / GRAP /
+geometric multi-period linking. Single-level classification only;
+nested hierarchies are scheduled for v1.1.
+
+## Methods supported
+
+| | Method | Reference |
+|---|---|---|
+| Single-period | Brinson-Hood-Beebower (3-effect) | Brinson, Hood & Beebower (1986) |
+| Single-period | Brinson-Fachler (3-effect) | Brinson & Fachler (1985) |
+| Multi-period linking | Cariño log-smoothing | Cariño (1999) |
+| Multi-period linking | GRAP factors | GRAP (1997) |
+| Multi-period linking | Geometric (Bacon) | Bacon (2008), chap. 6 |
+
+Deferred to v1.1+: Menchero / Frongello linking, multi-level (nested)
+classification, currency attribution.
+
+## Install
+
+```bash
+pip install pybrinson
+```
+
+`pybrinson` has **zero runtime dependencies** — just the Python standard
+library. Requires Python 3.14+.
+
+## Quickstart
+
+```python
+from pybrinson import Segment, bhb
+
+segments = [
+    Segment("UK Equity", portfolio_weight=0.40, benchmark_weight=0.40,
+            portfolio_return=0.20, benchmark_return=0.10),
+    Segment("Japan Equity", portfolio_weight=0.30, benchmark_weight=0.20,
+            portfolio_return=-0.05, benchmark_return=-0.04),
+    Segment("US Equity", portfolio_weight=0.30, benchmark_weight=0.40,
+            portfolio_return=0.06, benchmark_return=0.08),
+]
+
+result = bhb(segments, period="2024-Q1")
+print(result)
+```
+
+```text
+BHB attribution — period 2024-Q1
+  R_p = 8.3000%   R_b = 6.4000%   excess = 1.9000%
+
+Segment       Allocation  Selection  Interaction     Total
+------------  ----------  ---------  -----------  --------
+UK Equity        0.0000%    4.0000%      0.0000%   4.0000%
+Japan Equity    -0.4000%   -0.2000%     -0.1000%  -0.7000%
+US Equity       -0.8000%   -0.8000%      0.2000%  -1.4000%
+Total           -1.2000%    3.0000%      0.1000%   1.9000%
+```
+
+The identity ``allocation + selection + interaction == excess_return``
+holds within ``1e-9`` by construction; pybrinson **raises**
+`AttributionError` rather than storing a silent residual when it fails.
+
+### Multi-period linking
+
+```python
+from pybrinson import bhb, link_carino, Segment
+
+period_attrs = [
+    bhb([Segment("Equities", 0.6, 0.5, 0.10, 0.05),
+         Segment("Bonds",    0.4, 0.5, 0.05, 0.10)], period="P1"),
+    bhb([Segment("Equities", 0.5, 0.5, 0.20, 0.10),
+         Segment("Bonds",    0.5, 0.5, 0.05, 0.10)], period="P2"),
+]
+
+print(link_carino(period_attrs))
+```
+
+See `examples/` for runnable scripts covering BHB, Brinson-Fachler, and
+Cariño / GRAP / geometric linking.
+
+## Design principles
+
+- **Pure Python first.** Zero runtime dependencies. Realistic attribution
+  inputs are small (≤1k segments × ≤1k periods); a NumPy dependency
+  would not pay for itself.
+- **Specification-driven, externally verified.** Every function carries
+  its formula, an academic citation, and a clickable URL. The math is
+  cross-checked against published worked examples.
+- **No silent residuals.** Identity failures raise. Bad inputs raise.
+  pybrinson never imputes, rescales or swallows residuals.
+- **Typed and tested.** Public API is fully type-annotated; ships
+  `py.typed`; tests cover both pinned worked examples and randomised
+  identity checks.
+
+## Positioning vs `ppar` / `fincore`
+
+| | `ppar` | `fincore` | `pybrinson` |
+|---|---|---|---|
+| BHB | no | yes | yes |
+| Brinson-Fachler 3-effect | 2-effect only | no | yes |
+| Cariño linking | yes | no | yes |
+| GRAP linking | no | no | **yes** |
+| Geometric linking | no | no | **yes** |
+| Inline source citations | no | no | **mandatory** |
+| Identity failure handling | n/a | silent residual | **raises** |
+| Runtime dependencies | 9 | 2 | **0** |
+
+See `docs/implementation-v1.md` for the audited findings against pinned
+upstream commits.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and targets Python 3.14.
+
+```bash
+uv sync                  # install deps, fetch Python 3.14 if needed
+uv run pytest            # full test suite
+uv run pytest -k bhb     # subset
+uv build                 # sdist + wheel into dist/
+```
+
+## References
+
+Primary papers cited in the source:
+
+- Brinson, G. P., Hood, L. R., & Beebower, G. L. (1986). "Determinants of Portfolio Performance." *Financial Analysts Journal*, 42(4). [DOI](https://doi.org/10.2469/faj.v42.n4.39)
+- Brinson, G. P., & Fachler, N. (1985). "Measuring Non-U.S. Equity Portfolio Performance." *Journal of Portfolio Management*, 11(3). [DOI](https://doi.org/10.3905/jpm.1985.409005)
+- Cariño, D. R. (1999). "Combining Attribution Effects Over Time." *Journal of Performance Measurement*, 3(4).
+- Groupe de Recherche en Attribution de Performance (1997). *Synthèse des modèles d'attribution de performance*.
+- Bacon, C. R. (2008). *Practical Portfolio Performance Measurement and Attribution*, 2nd ed., Wiley. [Wiley page](https://www.wiley.com/en-us/Practical+Portfolio+Performance+Measurement+and+Attribution%2C+2nd+Edition-p-9780470059289)
+- Bacon, C. R. (2019). *Performance Attribution: History and Progress*. CFA Institute Research Foundation. [Free PDF](https://www.cfainstitute.org/-/media/documents/book/rf-publication/2019/rf-v2019-n4-1-pdf.pdf)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pybrinson-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "pybrinson"
+version = "1.0.0"
+description = "Portfolio return attribution in Python: Brinson-Hood-Beebower, Brinson-Fachler, and multi-period linking."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "pybrinson contributors" }]
+keywords = [
+    "finance",
+    "portfolio",
+    "attribution",
+    "brinson",
+    "performance",
+    "asset-management",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/gghez/pybrinson"
+Repository = "https://github.com/gghez/pybrinson"
+Issues = "https://github.com/gghez/pybrinson/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pybrinson"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pybrinson",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"

pybrinson-1.0.0/src/pybrinson/__init__.py

@@ -0,0 +1,55 @@
+"""Portfolio return attribution: Brinson-Hood-Beebower, Brinson-Fachler, multi-period linking.
+
+Public API
+----------
+Single-period attribution:
+
+- :func:`bhb` — Brinson-Hood-Beebower (3-effect)
+- :func:`fachler` — Brinson-Fachler (3-effect)
+
+Multi-period linking:
+
+- :func:`link_carino` — Cariño (1999) log-smoothing
+- :func:`link_grap` — GRAP (1997) factor linking
+- :func:`link_geometric` — Bacon-style geometric linking
+
+Data model:
+
+- :class:`Segment` — input row
+- :class:`SegmentAttribution`, :class:`PeriodAttribution`,
+  :class:`LinkedAttribution` — result types
+
+Errors:
+
+- :class:`AttributionError` — raised on bad input or identity failure
+  (subclass of :class:`ValueError`)
+"""
+
+from ._format import linked_to_table, period_to_table  # noqa: F401  (side effect: __repr__)
+from ._types import (
+    LinkedAttribution,
+    PeriodAttribution,
+    Segment,
+    SegmentAttribution,
+)
+from .errors import AttributionError
+from .linking import link_carino, link_geometric, link_grap
+from .single_period import bhb, fachler
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AttributionError",
+    "LinkedAttribution",
+    "PeriodAttribution",
+    "Segment",
+    "SegmentAttribution",
+    "__version__",
+    "bhb",
+    "fachler",
+    "link_carino",
+    "link_geometric",
+    "link_grap",
+    "linked_to_table",
+    "period_to_table",
+]

pybrinson-1.0.0/src/pybrinson/_format.py

@@ -0,0 +1,94 @@
+"""Plain-text rendering of attribution results.
+
+Pure stdlib formatting. Returns fixed-width tables with explicit columns
+for allocation, selection, interaction and per-segment / total rows.
+"""
+
+from __future__ import annotations
+
+from ._types import LinkedAttribution, PeriodAttribution
+
+_HEAD = ("Segment", "Allocation", "Selection", "Interaction", "Total")
+_PCT_DECIMALS = 4
+
+
+def _fmt_pct(x: float) -> str:
+    return f"{x * 100:.{_PCT_DECIMALS}f}%"
+
+
+def _row(name: str, alloc: float, sel: float, inter: float) -> tuple[str, ...]:
+    return (
+        name,
+        _fmt_pct(alloc),
+        _fmt_pct(sel),
+        _fmt_pct(inter),
+        _fmt_pct(alloc + sel + inter),
+    )
+
+
+def _render(rows: list[tuple[str, ...]], header_lines: list[str]) -> str:
+    widths = [
+        max(len(row[col]) for row in (rows + [_HEAD]))
+        for col in range(len(_HEAD))
+    ]
+    sep = "  "
+
+    def _line(row: tuple[str, ...]) -> str:
+        return sep.join(
+            cell.ljust(widths[i]) if i == 0 else cell.rjust(widths[i])
+            for i, cell in enumerate(row)
+        )
+
+    out: list[str] = list(header_lines)
+    out.append(_line(_HEAD))
+    out.append(sep.join("-" * w for w in widths))
+    for row in rows:
+        out.append(_line(row))
+    return "\n".join(out)
+
+
+def period_to_table(result: PeriodAttribution) -> str:
+    """Render a single-period attribution result as a fixed-width table."""
+    label = result.period or "(unlabelled)"
+    header_lines = [
+        f"{result.method} attribution — period {label}",
+        f"  R_p = {_fmt_pct(result.portfolio_return)}   "
+        f"R_b = {_fmt_pct(result.benchmark_return)}   "
+        f"excess = {_fmt_pct(result.excess_return)}",
+        "",
+    ]
+    rows = [
+        _row(s.name, s.allocation, s.selection, s.interaction)
+        for s in result.by_segment
+    ]
+    rows.append(
+        _row("Total", result.allocation, result.selection, result.interaction)
+    )
+    return _render(rows, header_lines)
+
+
+def linked_to_table(result: LinkedAttribution) -> str:
+    """Render a multi-period linked attribution result."""
+    header_lines = [
+        f"{result.method}-linked attribution — {len(result.periods)} periods",
+        f"  R_p = {_fmt_pct(result.portfolio_return)}   "
+        f"R_b = {_fmt_pct(result.benchmark_return)}   "
+        f"excess = {_fmt_pct(result.excess_return)}",
+        "",
+    ]
+    rows = [_row("Total", result.allocation, result.selection, result.interaction)]
+    return _render(rows, header_lines)
+
+
+# Attach __repr__ overrides on the dataclasses. Done here (not in
+# _types.py) to keep _types.py free of formatting concerns.
+def _period_repr(self: PeriodAttribution) -> str:
+    return period_to_table(self)
+
+
+def _linked_repr(self: LinkedAttribution) -> str:
+    return linked_to_table(self)
+
+
+PeriodAttribution.__repr__ = _period_repr  # type: ignore[method-assign]
+LinkedAttribution.__repr__ = _linked_repr  # type: ignore[method-assign]

pybrinson-1.0.0/src/pybrinson/_math.py

@@ -0,0 +1,79 @@
+"""Internal numeric helpers: validation, aggregation, identity check.
+
+Tolerances
+----------
+``WEIGHT_SUM_TOL = 1e-8`` — used to check ``|Σw − 1|``.
+``RESIDUAL_TOL = 1e-9`` — used to check the per-period identity
+``Σ(A + S + I) ≈ R_p − R_b`` returned by BHB / Brinson-Fachler.
+
+These are deliberately tight: pybrinson never silently rescales weights
+or absorbs a residual, because a wrong fill rule (zero-fill, drop, …)
+would propagate into the identity without the reader noticing — exactly
+the bug that fincore's ``residual`` field hides
+(``fincore/attribution/brinson.py`` line 97-98).
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from .errors import AttributionError
+
+WEIGHT_SUM_TOL: float = 1e-8
+RESIDUAL_TOL: float = 1e-9
+
+
+def reject_non_finite(values: Sequence[float], *, name: str) -> None:
+    """Raise :class:`AttributionError` if any value is ``NaN`` or ``±inf``."""
+    for v in values:
+        if not math.isfinite(v):
+            raise AttributionError(
+                f"{name} contains a non-finite value ({v!r}). "
+                "pybrinson does not silently impute or drop missing data — "
+                "the caller must clean inputs before calling."
+            )
+
+
+def validate_weights(weights: Sequence[float], *, name: str) -> None:
+    """Raise unless ``weights`` are finite and sum to ``1`` within tolerance."""
+    reject_non_finite(weights, name=name)
+    total = math.fsum(weights)
+    if abs(total - 1.0) > WEIGHT_SUM_TOL:
+        raise AttributionError(
+            f"{name} weights must sum to 1 within {WEIGHT_SUM_TOL:g}; "
+            f"got {total!r}. pybrinson never silently rescales — fix the input."
+        )
+
+
+def aggregate_return(weights: Sequence[float], returns: Sequence[float]) -> float:
+    r"""Compute the weighted return :math:`\sum_i w_i r_i`.
+
+    Uses :func:`math.fsum` for an exact, order-independent sum so that the
+    identity check downstream is not polluted by accumulated rounding.
+    """
+    if len(weights) != len(returns):
+        raise AttributionError(
+            f"weights/returns length mismatch: {len(weights)} vs {len(returns)}"
+        )
+    return math.fsum(w * r for w, r in zip(weights, returns, strict=True))
+
+
+def check_identity(
+    allocation: float,
+    selection: float,
+    interaction: float,
+    excess: float,
+    *,
+    method: str,
+) -> None:
+    """Raise if ``A + S + I`` does not match ``R_p − R_b`` within tolerance."""
+    residual = (allocation + selection + interaction) - excess
+    if abs(residual) > RESIDUAL_TOL:
+        raise AttributionError(
+            f"{method} identity violated: "
+            f"A + S + I = {allocation + selection + interaction!r}, "
+            f"excess = {excess!r}, residual = {residual!r}. "
+            "This is either a numerical pathology or a bug — pybrinson "
+            "refuses to store a silent residual."
+        )