heavytails 0.1.0__tar.gz

heavytails-0.1.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Python 3.13 support, covered by the CI test matrix and declared in the package
+  classifiers.
+- `py.typed` marker, so the type annotations that ship with the package are
+  visible to downstream type checkers. The `Typing :: Typed` classifier was
+  previously advertised without one.
+- `heavytails.__version__`, resolved from the installed distribution metadata.
+- `--version` / `-V` flag on the `heavytails` command-line interface.
+- `cli` installation extra (`pip install "heavytails[cli]"`). The console script
+  depends on `typer` and `rich`, which were previously development-only
+  dependencies, so the entry point was broken for anyone installing from PyPI.
+- CodeQL analysis and dependency-review workflows.
+- `.github/CODEOWNERS`, `.gitattributes` and `.zenodo.json`.
+- `StudentT.cdf`, `StudentT.sf` and `StudentT.ppf`. The class previously offered
+  only `pdf` and `rvs`, with a docstring stating that the CDF and PPF "require
+  special functions not in stdlib" — but the regularized incomplete beta needed
+  to write them was already implemented in `extra_distributions`. All three
+  agree with SciPy to around 1e-14.
+- `Cauchy.sf`, `Frechet.sf` and `GEV_Frechet.sf`, so every continuous family now
+  provides the full interface the documentation advertises.
+- `YuleSimon.sf` and `YuleSimon.ppf`. The survival function uses the closed form
+  `P(X > k) = k * B(k, rho + 1)`, and the quantile function brackets and bisects
+  rather than scanning linearly.
+- `heavytails._special`, holding the shared numeric special functions so that
+  both distribution modules can use them without an import cycle. The previous
+  names remain importable from `heavytails.extra_distributions`.
+- `_betaincinv_reg`, an inverse for the regularized incomplete beta. It solves in
+  log-space with a symmetry reduction, which is what keeps extreme quantiles
+  accurate.
+- Documentation pages that existing pages already linked to but which had never
+  been written: CLI reference, diagnostics guide, extreme value theory, tail
+  index estimation theory, validation studies, architecture, benchmarking, code
+  review, and an executable `basic_usage` notebook.
+
+### Changed
+
+- Migrated project metadata to the PEP 621 `[project]` table.
+- Grouped Dependabot updates so routine bumps arrive as a few reviewable pull
+  requests rather than one per package.
+- Continuous integration now also runs on pull requests targeting `develop`,
+  builds and metadata-checks the distributions before publishing, verifies that
+  `poetry.lock` matches `pyproject.toml`, and builds the documentation with
+  `--strict`.
+- Security scanning fails the build on findings instead of uploading a report
+  that no one reads. `safety` was replaced by `pip-audit`, which needs no
+  account to run.
+- Refreshed the locked dependency set, clearing 116 known vulnerabilities
+  reported against the previously locked development and documentation
+  toolchain.
+- Pre-commit hooks are pinned to the same tool versions as the development
+  dependencies, so local hooks and CI now agree.
+- Replaced the `Makefile` targets, which measured coverage of `scripts/` rather
+  than of the package.
+- `mkdocstrings` is configured for Google-style docstrings, which is what the
+  package actually uses. Under the previous `numpy` setting no `Args:` or
+  `Returns:` section was parsed anywhere in the API reference.
+- The documentation navigation lists every page. Five API reference entries all
+  pointed at the same directory, and the `gen-files` script duplicated the
+  hand-written reference pages while `literate-nav` looked for a `SUMMARY.md`
+  that was never generated.
+
+### Fixed
+
+- `heavytails benchmark` raised `ZeroDivisionError` on platforms with a
+  low-resolution wall clock, because a sub-millisecond timing measured exactly
+  zero seconds. Timings now use `time.perf_counter()`.
+- The same defect in the performance tests, which failed intermittently on
+  Windows.
+- Removed an invalid PyPI classifier (`Topic :: Scientific/Engineering ::
+  Statistics`) that would have been rejected on upload.
+- `scripts/pyproject_updater.py` depends on `tomlkit` and `packaging`, which
+  were never declared and only happened to be installed transitively.
+- Pinned Poetry 2.2.1 in every workflow. The previous 1.8.3 pin cannot read the
+  version 2.1 lock file this repository uses.
+- Removed a `preferred-citation` entry from `CITATION.cff` that pointed at an
+  unpublished paper with a placeholder DOI, which citation tooling would have
+  emitted as a real reference.
+- `YuleSimon.pmf` raised `OverflowError` for k of about 170 and above, because
+  it multiplied gamma functions that overflow individually even though their
+  ratio is small. Since sampling called it in a loop, drawing from the tail
+  crashed. It is now evaluated with `lgamma`.
+- Nineteen documentation links pointed at pages that did not exist. The
+  documentation job now builds with `--strict`, so a broken link fails CI.
+- `convergence_validation` took a `_max_iter` parameter that was never used and
+  documented it under a different name.
+- Removed a stale `xfail` marker on the Student-t PPF convergence test. It was
+  recording precision loss that the new incomplete beta inverse eliminates.
+
+### Removed
+
+- `tox.ini`, which ran the test suite against `scripts/` instead of the package
+  and duplicated the CI matrix.
+- `IMPROVEMENT_PLAN.md` from the repository root. It described gaps that have
+  since been closed; forward-looking plans live in
+  [ROADMAP.md](https://github.com/DiogoRibeiro7/heavytails/blob/main/ROADMAP.md).
+- The `isort` development dependency and its configuration, superseded by
+  Ruff's `I` rules.
+
+## [0.1.0] - 2025-10-25
+
+### Added
+
+- Continuous heavy-tailed distributions implemented from first principles:
+  Pareto, Cauchy, Student-t, Log-Normal, Weibull, Fréchet and GEV (ξ > 0).
+- Additional continuous families: Generalized Pareto, Burr XII, Log-Logistic
+  (Fisk), Inverse-Gamma and Beta-Prime.
+- Discrete heavy-tailed distributions: Zipf, Yule–Simon and Discrete Pareto.
+- Tail index estimators: Hill, Pickands and moment.
+- Diagnostic plotting helpers for log–log tail and QQ plots.
+- Deterministic RNG wrapper for reproducible sampling.
+- Custom incomplete-gamma and incomplete-beta implementations, and a
+  safeguarded-Newton numeric PPF solver for families without a closed form.
+- `heavytails` command-line interface.
+- Documentation site built with MkDocs Material.
+
+[Unreleased]: https://github.com/DiogoRibeiro7/heavytails/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/DiogoRibeiro7/heavytails/releases/tag/v0.1.0

heavytails-0.1.0/CITATION.cff

@@ -0,0 +1,68 @@
+cff-version: 1.2.0
+title: "heavytails: A Pure-Python Library for Heavy-Tailed Probability Distributions"
+message: "If you use this library, please cite as below."
+type: software
+authors:
+  - family-names: Ribeiro
+    given-names: Diogo
+    orcid: "https://orcid.org/0009-0001-2022-7072"
+    affiliation: "ESMAD - Escola Superior de Média Arte e Design; Mysense.ai"
+    email: dfr@esmad.ipp.pt
+repository-code: "https://github.com/DiogoRibeiro7/heavytails"
+url: "https://diogoribeiro7.github.io/heavytails"
+abstract: >
+  heavytails is a pure-Python library implementing heavy-tailed probability
+  distributions, built from first principles without third-party dependencies.
+  The library provides comprehensive support for continuous and discrete
+  heavy-tailed distributions, tail index estimation methods, and diagnostic
+  utilities for extreme value analysis, risk management, and financial modeling.
+keywords:
+  - heavy tails
+  - heavy-tailed distributions
+  - probability distributions
+  - statistics
+  - data science
+  - machine learning
+  - extreme value theory
+  - tail index estimation
+  - risk management
+  - finance
+  - tail risk
+  - python
+  - simulation
+  - teaching
+license: MIT
+version: 0.1.0
+date-released: 2025-10-25
+references:
+  - type: book
+    title: "Extreme Value Theory: An Introduction"
+    authors:
+      - family-names: de Haan
+        given-names: Laurens
+      - family-names: Ferreira
+        given-names: Ana
+    publisher: "Springer"
+    year: 2006
+    isbn: "978-0-387-23946-0"
+  - type: book
+    title: "Heavy-Tailed Distributions in Finance"
+    authors:
+      - family-names: Rachev
+        given-names: Svetlozar T.
+      - family-names: Mittnik
+        given-names: Stefan
+    publisher: "Academic Press"
+    year: 2000
+    isbn: "978-0-12-574340-4"
+  - type: article
+    title: "A Simple General Approach to Inference About the Tail of a Distribution"
+    authors:
+      - family-names: Hill
+        given-names: Bruce M.
+    journal: "The Annals of Statistics"
+    year: 1975
+    volume: 3
+    issue: 5
+    pages: "1163-1174"
+    doi: "10.1214/aos/1176343247"

heavytails-0.1.0/LICENSE

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

heavytails-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: heavytails
+Version: 0.1.0
+Summary: Pure-Python heavy-tailed probability distributions for research, teaching, and simulation.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: heavy-tailed,statistics,probability,extreme-values,distributions,finance,risk-management,tail-risk,extreme-value-theory
+Author: Diogo Ribeiro
+Author-email: dfr@esmad.ipp.pt
+Maintainer: Diogo Ribeiro
+Maintainer-email: dfr@esmad.ipp.pt
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+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 :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Provides-Extra: cli
+Requires-Dist: rich (>=14.0,<15.0) ; extra == "cli"
+Requires-Dist: typer (>=0.20,<1.0) ; extra == "cli"
+Project-URL: Changelog, https://github.com/DiogoRibeiro7/heavytails/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://diogoribeiro7.github.io/heavytails
+Project-URL: Discussions, https://github.com/DiogoRibeiro7/heavytails/discussions
+Project-URL: Homepage, https://github.com/DiogoRibeiro7/heavytails
+Project-URL: Issues, https://github.com/DiogoRibeiro7/heavytails/issues
+Project-URL: Repository, https://github.com/DiogoRibeiro7/heavytails
+Description-Content-Type: text/markdown
+
+# heavytails
+
+**A pure-Python library of heavy-tailed probability distributions**
+
+[![CI](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/DiogoRibeiro7/heavytails/branch/main/graph/badge.svg)](https://codecov.io/gh/DiogoRibeiro7/heavytails)
+[![PyPI](https://img.shields.io/pypi/v/heavytails.svg)](https://pypi.org/project/heavytails/)
+[![Python versions](https://img.shields.io/pypi/pyversions/heavytails.svg)](https://pypi.org/project/heavytails/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://diogoribeiro7.github.io/heavytails)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)
+
+`heavytails` implements continuous and discrete heavy-tailed distributions, tail
+index estimators, and diagnostic utilities — **using only the Python standard
+library**. Every density, quantile and sampler is derived from first principles,
+so the implementation can be read, checked and taught rather than taken on faith.
+
+It targets research, teaching and simulation work in risk, finance, insurance and
+extreme-value analysis.
+
+---
+
+## Features
+
+- **No runtime dependencies.** The library imports nothing outside `math`,
+  `random` and friends, so it installs anywhere Python does.
+- **Complete distribution interface.** PDF/PMF, CDF, survival function, quantile
+  function and random sampling for every family, with survival functions computed
+  directly so they stay accurate far into the tail where `1 - cdf(x)` has lost
+  every significant digit.
+- **Reproducible sampling** through a deterministic RNG wrapper.
+- **Special functions from scratch** — incomplete gamma and incomplete beta —
+  plus a safeguarded-Newton numeric PPF for families with no closed form.
+- **Tail index estimation** with the Hill, Pickands and moment estimators.
+- **Parameter fitting** by maximum likelihood and method of moments, with
+  AIC/BIC model comparison.
+- **Diagnostics** for log–log tail plots and QQ plots.
+- **A command-line interface** for sampling, fitting, comparison and
+  benchmarking.
+- **Typed throughout**, with a `py.typed` marker so downstream type checkers see
+  the annotations.
+
+---
+
+## Installation
+
+```bash
+pip install heavytails
+```
+
+The command-line interface needs two extra packages; install it with the `cli`
+extra:
+
+```bash
+pip install "heavytails[cli]"
+```
+
+To work on the library itself:
+
+```bash
+git clone https://github.com/DiogoRibeiro7/heavytails.git
+cd heavytails
+poetry install --with dev,docs
+```
+
+Requires Python 3.10 or newer.
+
+---
+
+## Quick start
+
+```python
+from heavytails import BurrXII, Pareto, hill_estimator
+
+pareto = Pareto(alpha=1.5, xm=1.0)
+
+pareto.pdf(2.0)        # density
+pareto.cdf(2.0)        # distribution function
+pareto.sf(10.0)        # survival function: P(X > 10)
+pareto.ppf(0.99)       # 99th percentile
+samples = pareto.rvs(10_000, seed=42)
+
+# Recover the tail index from the sample. The estimators return the
+# extreme-value index gamma = 1 / alpha, so invert it to read alpha back.
+gamma = hill_estimator(samples, k=100)   # ≈ 0.65
+alpha = 1 / gamma                        # ≈ 1.53, against a true 1.5
+
+burr = BurrXII(c=1.2, k=2.5, s=3.0)
+burr.ppf(0.95)
+```
+
+### Command line
+
+```bash
+heavytails list-distributions
+heavytails sample pareto --params '{"alpha": 2.0, "xm": 1.0}' -n 1000 -o samples.txt
+heavytails estimate-tail samples.txt --method hill
+heavytails compare samples.txt
+```
+
+Run `heavytails --help` for the full command list.
+
+---
+
+## Available distributions
+
+### Continuous
+
+| Distribution            | Module                   | Heavy-tail regime |
+| ----------------------- | ------------------------ | ----------------- |
+| Pareto                  | `heavy_tails`            | always            |
+| Cauchy                  | `heavy_tails`            | always            |
+| Student-t               | `heavy_tails`            | small ν           |
+| Log-Normal              | `heavy_tails`            | always            |
+| Weibull                 | `heavy_tails`            | k < 1             |
+| Fréchet                 | `heavy_tails`            | always            |
+| GEV (Fréchet branch)    | `heavy_tails`            | ξ > 0             |
+| Generalized Pareto      | `extra_distributions`    | ξ > 0             |
+| Burr XII                | `extra_distributions`    | always            |
+| Log-Logistic (Fisk)     | `extra_distributions`    | always            |
+| Inverse-Gamma           | `extra_distributions`    | always            |
+| Beta-Prime              | `extra_distributions`    | always            |
+
+### Discrete
+
+| Distribution     | Module     | Heavy-tail regime |
+| ---------------- | ---------- | ----------------- |
+| Zipf             | `discrete` | always            |
+| Yule–Simon       | `discrete` | always            |
+| Discrete Pareto  | `discrete` | always            |
+
+Every continuous family provides `pdf`, `cdf`, `sf`, `ppf` and `rvs`; every
+discrete family provides `pmf`, `cdf`, `ppf` and `rvs`.
+
+### Estimation and diagnostics
+
+| Module       | Contents                                              |
+| ------------ | ----------------------------------------------------- |
+| `tail_index` | Hill, Pickands and moment tail index estimators        |
+| `plotting`   | Log–log tail plots and QQ plots                        |
+| `utilities`  | Data I/O, automatic fitting and model comparison       |
+| `validation` | Mathematical and numerical validation of the families  |
+| `cli`        | Command-line entry point                               |
+
+---
+
+## Documentation
+
+Full documentation, including the mathematical background, is at
+**<https://diogoribeiro7.github.io/heavytails>**.
+
+To build it locally:
+
+```bash
+make docs-serve
+```
+
+---
+
+## Development
+
+```bash
+make install-dev   # install every dependency group
+make hooks         # install the pre-commit hooks
+make check         # everything CI runs: lint, format, types, tests, security
+```
+
+Individual targets are listed by `make help`. Contributions are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for the branch flow, commit conventions and
+review process, and [ROADMAP.md](ROADMAP.md) for what is planned next.
+
+Notable changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT License © 2025 Diogo Ribeiro. See [LICENSE](LICENSE).
+
+---
+
+## Citation
+
+If you use this package in research or teaching, please cite it. GitHub's
+"Cite this repository" button reads [CITATION.cff](CITATION.cff), or use:
+
+> Ribeiro, D. (2025). *heavytails: A Pure-Python Library for Heavy-Tailed Probability Distributions*.
+> <https://github.com/DiogoRibeiro7/heavytails>
+
+Shared citation metadata is maintained in `CITATION.cff`; Zenodo-specific
+archive metadata is maintained in `.zenodo.json`. The DOI will be added after
+the first archived GitHub release.
+

heavytails-0.1.0/README.md

@@ -0,0 +1,193 @@
+# heavytails
+
+**A pure-Python library of heavy-tailed probability distributions**
+
+[![CI](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DiogoRibeiro7/heavytails/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/DiogoRibeiro7/heavytails/branch/main/graph/badge.svg)](https://codecov.io/gh/DiogoRibeiro7/heavytails)
+[![PyPI](https://img.shields.io/pypi/v/heavytails.svg)](https://pypi.org/project/heavytails/)
+[![Python versions](https://img.shields.io/pypi/pyversions/heavytails.svg)](https://pypi.org/project/heavytails/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://diogoribeiro7.github.io/heavytails)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)
+
+`heavytails` implements continuous and discrete heavy-tailed distributions, tail
+index estimators, and diagnostic utilities — **using only the Python standard
+library**. Every density, quantile and sampler is derived from first principles,
+so the implementation can be read, checked and taught rather than taken on faith.
+
+It targets research, teaching and simulation work in risk, finance, insurance and
+extreme-value analysis.
+
+---
+
+## Features
+
+- **No runtime dependencies.** The library imports nothing outside `math`,
+  `random` and friends, so it installs anywhere Python does.
+- **Complete distribution interface.** PDF/PMF, CDF, survival function, quantile
+  function and random sampling for every family, with survival functions computed
+  directly so they stay accurate far into the tail where `1 - cdf(x)` has lost
+  every significant digit.
+- **Reproducible sampling** through a deterministic RNG wrapper.
+- **Special functions from scratch** — incomplete gamma and incomplete beta —
+  plus a safeguarded-Newton numeric PPF for families with no closed form.
+- **Tail index estimation** with the Hill, Pickands and moment estimators.
+- **Parameter fitting** by maximum likelihood and method of moments, with
+  AIC/BIC model comparison.
+- **Diagnostics** for log–log tail plots and QQ plots.
+- **A command-line interface** for sampling, fitting, comparison and
+  benchmarking.
+- **Typed throughout**, with a `py.typed` marker so downstream type checkers see
+  the annotations.
+
+---
+
+## Installation
+
+```bash
+pip install heavytails
+```
+
+The command-line interface needs two extra packages; install it with the `cli`
+extra:
+
+```bash
+pip install "heavytails[cli]"
+```
+
+To work on the library itself:
+
+```bash
+git clone https://github.com/DiogoRibeiro7/heavytails.git
+cd heavytails
+poetry install --with dev,docs
+```
+
+Requires Python 3.10 or newer.
+
+---
+
+## Quick start
+
+```python
+from heavytails import BurrXII, Pareto, hill_estimator
+
+pareto = Pareto(alpha=1.5, xm=1.0)
+
+pareto.pdf(2.0)        # density
+pareto.cdf(2.0)        # distribution function
+pareto.sf(10.0)        # survival function: P(X > 10)
+pareto.ppf(0.99)       # 99th percentile
+samples = pareto.rvs(10_000, seed=42)
+
+# Recover the tail index from the sample. The estimators return the
+# extreme-value index gamma = 1 / alpha, so invert it to read alpha back.
+gamma = hill_estimator(samples, k=100)   # ≈ 0.65
+alpha = 1 / gamma                        # ≈ 1.53, against a true 1.5
+
+burr = BurrXII(c=1.2, k=2.5, s=3.0)
+burr.ppf(0.95)
+```
+
+### Command line
+
+```bash
+heavytails list-distributions
+heavytails sample pareto --params '{"alpha": 2.0, "xm": 1.0}' -n 1000 -o samples.txt
+heavytails estimate-tail samples.txt --method hill
+heavytails compare samples.txt
+```
+
+Run `heavytails --help` for the full command list.
+
+---
+
+## Available distributions
+
+### Continuous
+
+| Distribution            | Module                   | Heavy-tail regime |
+| ----------------------- | ------------------------ | ----------------- |
+| Pareto                  | `heavy_tails`            | always            |
+| Cauchy                  | `heavy_tails`            | always            |
+| Student-t               | `heavy_tails`            | small ν           |
+| Log-Normal              | `heavy_tails`            | always            |
+| Weibull                 | `heavy_tails`            | k < 1             |
+| Fréchet                 | `heavy_tails`            | always            |
+| GEV (Fréchet branch)    | `heavy_tails`            | ξ > 0             |
+| Generalized Pareto      | `extra_distributions`    | ξ > 0             |
+| Burr XII                | `extra_distributions`    | always            |
+| Log-Logistic (Fisk)     | `extra_distributions`    | always            |
+| Inverse-Gamma           | `extra_distributions`    | always            |
+| Beta-Prime              | `extra_distributions`    | always            |
+
+### Discrete
+
+| Distribution     | Module     | Heavy-tail regime |
+| ---------------- | ---------- | ----------------- |
+| Zipf             | `discrete` | always            |
+| Yule–Simon       | `discrete` | always            |
+| Discrete Pareto  | `discrete` | always            |
+
+Every continuous family provides `pdf`, `cdf`, `sf`, `ppf` and `rvs`; every
+discrete family provides `pmf`, `cdf`, `ppf` and `rvs`.
+
+### Estimation and diagnostics
+
+| Module       | Contents                                              |
+| ------------ | ----------------------------------------------------- |
+| `tail_index` | Hill, Pickands and moment tail index estimators        |
+| `plotting`   | Log–log tail plots and QQ plots                        |
+| `utilities`  | Data I/O, automatic fitting and model comparison       |
+| `validation` | Mathematical and numerical validation of the families  |
+| `cli`        | Command-line entry point                               |
+
+---
+
+## Documentation
+
+Full documentation, including the mathematical background, is at
+**<https://diogoribeiro7.github.io/heavytails>**.
+
+To build it locally:
+
+```bash
+make docs-serve
+```
+
+---
+
+## Development
+
+```bash
+make install-dev   # install every dependency group
+make hooks         # install the pre-commit hooks
+make check         # everything CI runs: lint, format, types, tests, security
+```
+
+Individual targets are listed by `make help`. Contributions are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for the branch flow, commit conventions and
+review process, and [ROADMAP.md](ROADMAP.md) for what is planned next.
+
+Notable changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## License
+
+MIT License © 2025 Diogo Ribeiro. See [LICENSE](LICENSE).
+
+---
+
+## Citation
+
+If you use this package in research or teaching, please cite it. GitHub's
+"Cite this repository" button reads [CITATION.cff](CITATION.cff), or use:
+
+> Ribeiro, D. (2025). *heavytails: A Pure-Python Library for Heavy-Tailed Probability Distributions*.
+> <https://github.com/DiogoRibeiro7/heavytails>
+
+Shared citation metadata is maintained in `CITATION.cff`; Zenodo-specific
+archive metadata is maintained in `.zenodo.json`. The DOI will be added after
+the first archived GitHub release.