perfattr 0.1.0__tar.gz

perfattr-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Generated project outputs
+/.cache/
+
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+/build/
+/dist/
+*.egg-info/
+.eggs/
+
+# Installer remnants
+pip-delete-this-directory.txt
+
+# Tests, type checking, and profiling
+/.pytest_cache/
+/.mypy_cache/
+.dmypy.json
+dmypy.json
+htmlcov/
+.coverage
+.coverage.*
+*.cover
+*.py,cover
+coverage.xml
+*.prof
+.profraw
+
+# pyenv
+.python-version
+
+# Local environment
+.env
+.env.*
+!.env.example
+/.venv/
+
+# IDEs and text editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+.Trash-*
+
+# Temporary files
+.~lock.*#

perfattr-0.1.0/LICENSE

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

perfattr-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: perfattr
+Version: 0.1.0
+Summary: Auditable portfolio performance attribution using pandas and NumPy.
+Project-URL: Repository, https://github.com/JohnDReynolds/perfattr
+Author: John Reynolds
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attribution,brinson,finance,performance,portfolio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pylint>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.409; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# perfattr
+
+`perfattr` is a small, auditable portfolio performance-attribution calculation
+library built with pandas and NumPy.
+
+The 0.1.0 release provides a reusable Brinson-Fachler calculation core for
+prepared reporting-period data. Source loading, portfolio accounting, vendor schemas,
+calendar logic, and presentation are intentionally outside the package boundary.
+
+The calculation core accepts one or more prepared reporting periods and provides
+input validation, universe equalization, Brinson-Fachler allocation and selection,
+logarithmic contribution linking, Carino active-effect linking, cumulative and
+full-horizon results, and financial reconciliation. The governing roadmap is available
+in [`_extras/perfattr_roadmap.md`](_extras/perfattr_roadmap.md), and the complete
+portable calculation contract is defined in
+[`docs/specification.md`](docs/specification.md).
+
+```python
+from perfattr import calculate_attribution
+
+result = calculate_attribution(portfolio, benchmark)
+print(result.period_detail)
+```
+
+## Development
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the package and development dependencies:
+
+```bash
+python -m pip install --editable ".[dev]"
+```
+
+Run the initial checks:
+
+```bash
+python -m pytest
+python -m pylint src/perfattr tests scripts
+python -m pyright
+```
+
+Run the four roadmap performance workloads:
+
+```bash
+python scripts/benchmark_core.py --samples 5
+python scripts/benchmark_core.py --samples 5 --input-form authoritative
+```
+
+Add `--workload monthly_121260 --profile` to inspect one workload's cumulative
+call profile. The benchmark methodology and initial observations are recorded in
+[`docs/performance.md`](docs/performance.md).
+
+## License
+
+`perfattr` is distributed under the MIT License.

perfattr-0.1.0/README.md

@@ -0,0 +1,61 @@
+# perfattr
+
+`perfattr` is a small, auditable portfolio performance-attribution calculation
+library built with pandas and NumPy.
+
+The 0.1.0 release provides a reusable Brinson-Fachler calculation core for
+prepared reporting-period data. Source loading, portfolio accounting, vendor schemas,
+calendar logic, and presentation are intentionally outside the package boundary.
+
+The calculation core accepts one or more prepared reporting periods and provides
+input validation, universe equalization, Brinson-Fachler allocation and selection,
+logarithmic contribution linking, Carino active-effect linking, cumulative and
+full-horizon results, and financial reconciliation. The governing roadmap is available
+in [`_extras/perfattr_roadmap.md`](_extras/perfattr_roadmap.md), and the complete
+portable calculation contract is defined in
+[`docs/specification.md`](docs/specification.md).
+
+```python
+from perfattr import calculate_attribution
+
+result = calculate_attribution(portfolio, benchmark)
+print(result.period_detail)
+```
+
+## Development
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the package and development dependencies:
+
+```bash
+python -m pip install --editable ".[dev]"
+```
+
+Run the initial checks:
+
+```bash
+python -m pytest
+python -m pylint src/perfattr tests scripts
+python -m pyright
+```
+
+Run the four roadmap performance workloads:
+
+```bash
+python scripts/benchmark_core.py --samples 5
+python scripts/benchmark_core.py --samples 5 --input-form authoritative
+```
+
+Add `--workload monthly_121260 --profile` to inspect one workload's cumulative
+call profile. The benchmark methodology and initial observations are recorded in
+[`docs/performance.md`](docs/performance.md).
+
+## License
+
+`perfattr` is distributed under the MIT License.

perfattr-0.1.0/docs/performance.md

@@ -0,0 +1,60 @@
+# Performance observations
+
+This document records repeatable observations rather than release thresholds. Run the
+benchmark again on the target environment before drawing conclusions from the absolute
+times.
+
+## Method
+
+[`scripts/benchmark_core.py`](../scripts/benchmark_core.py) builds deterministic,
+prepared inputs before measurement, warms the public API once, and reports the median
+of the requested elapsed-time samples. Peak memory is the incremental peak of
+Python-tracked allocations while `calculate_attribution` runs; prepared input memory
+is reported separately.
+
+The four workloads correspond to the roadmap shapes:
+
+- `normal`: 6,063 rows per side across 60 monthly periods;
+- `selected_10x`: 60,630 rows per side across 60 monthly periods;
+- `monthly_121260`: 121,260 rows per side across 120 monthly periods; and
+- `history_25y`: 30,300 rows per side across 300 monthly periods.
+
+The default `derived` form supplies weights and returns. The `authoritative` form also
+supplies contribution, matching the accounting-integrated contract.
+
+## Initial standalone baseline
+
+These observations were collected on September 3, 2026, on an Apple arm64 machine
+using Python 3.11.9, pandas 3.0.5, and NumPy 2.4.6. Each elapsed result is the median of
+five samples.
+
+| Workload | Input form | Median elapsed | Prepared inputs | Peak traced allocation |
+| --- | --- | ---: | ---: | ---: |
+| `normal` | derived | 0.0270 s | 2.0 MiB | 4.6 MiB |
+| `selected_10x` | derived | 0.0971 s | 20.4 MiB | 44.6 MiB |
+| `monthly_121260` | derived | 0.1723 s | 40.7 MiB | 89.0 MiB |
+| `history_25y` | derived | 0.0576 s | 10.2 MiB | 22.4 MiB |
+| `normal` | authoritative | 0.0275 s | 2.1 MiB | 4.6 MiB |
+| `selected_10x` | authoritative | 0.0969 s | 21.3 MiB | 44.6 MiB |
+| `monthly_121260` | authoritative | 0.1718 s | 42.6 MiB | 89.1 MiB |
+| `history_25y` | authoritative | 0.0575 s | 10.6 MiB | 22.4 MiB |
+
+Profiling the largest workload placed most core time in required input validation and
+normalization. The absolute time was already modest, so no core refactor or additional
+dependency was justified.
+
+## `ppar` adapter observation
+
+An isolated 121,260-row-per-side adapter profile used Python 3.12.1, pandas 3.0.0,
+NumPy 2.4.2, and Polars 1.38.0. It identified per-value Python-list materialization at
+the pandas/Polars boundary as the dominant non-core cost. Passing existing columnar
+NumPy arrays in both directions reduced the median of five samples from approximately
+0.52 seconds to 0.23 seconds and reduced peak traced allocation from 142.9 MiB to
+113.1 MiB. The completed differential suite established migration parity; the
+permanent 500x integration gate remains the authority for workflow performance.
+
+After the change, the permanent `ppar` 500x integration command passed all scenarios.
+The large-source workflow took 1.41 seconds at both 12,126 and 6,063,000 source rows;
+the selected-input workflow grew from 0.23 to 0.47 seconds at 10x rows; and the
+long-history workflow grew from 1.28 to 1.85 seconds at 5x history. These timings are
+observations, not thresholds.