smerisk 0.1.0__tar.gz

smerisk-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# Secrets and local configuration (API tokens, dataset key)
+.env
+.env.*
+*.pem
+*.key
+
+# Generated files
+openapi.json
+*.log
+
+# Editors and operating systems
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+

smerisk-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/). Changing the random-number generator is a major-version change.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-25
+
+First release.
+
+### Added
+
+- Repository scaffold: `smerisk` library, `smerisk-service`, and continuous integration.
+- `simulate_aggregate`: Monte Carlo aggregate simulation, rank correlations using a Gaussian copula, and variance contributions.
+  Each ungrouped component and each correlation group has its own random stream.
+- `risk_measures`: VaR, Expected Shortfall, and CFaR for a sample.
+- `pert_estimate`: classical PERT three-point estimate, total effort at confidence levels, and contingency.
+- `fixed_price_completion`: Monte Carlo final cost, margin, budget and deadline probabilities, and task and risk
+  variance contributions, with one random stream per task and risk.
+- `utilization_forecast`: Monte Carlo team utilization, bench days, per-consultant bench probability, and
+  unstaffed deal days, with month-by-month staffing of won deals.
+- `credibility`: Bühlmann-Straub credibility in `estimate` and `reference` modes.
+- `beta_binomial`: conjugate Beta-Binomial rate with prior, equal-tailed credible interval, and prior weight.
+- `kaplan_meier`: Kaplan-Meier survival with Greenwood variance, log-log confidence limits, small-group
+  suppression, and the log-rank test.
+- `markov_payments`: absorbing Markov chain of receivables with smoothed transitions, monthly projection, and
+  default probabilities and payment delays by ageing state.
+- `expected_loss`: expected credit loss by segment and concentration, with optional Monte Carlo loss quantiles
+  and expected shortfall under independent defaults.
+- `benford`: first-digit and first-two-digit Benford tests with Nigrini's MAD bands, z statistics, chi-square, and
+  flagged labels.
+- `newsvendor`: optimal perishable order quantity with expected sales, leftovers, shortage, and profit.
+- `erlang_c`: M/M/c waiting probability, mean wait, service level, recommended team size, and staffing table.
+- `brier`: Brier score, skill score against climatology or a given rate, and calibration bins.
+- `kupiec`: proportion-of-failures likelihood-ratio test with verdict.
+- Raw data contracts (`smerisk.contracts`): Pydantic models for payroll, accounting, consulting, retail, and
+  forecast-log records; `parse_records` sets invalid records aside with their reason; `read_fec` reads FEC files
+  (tab, `|`, or `;`, UTF-8 or Windows-1252, `Debit`/`Credit` or `Montant`/`Sens`) and drops labels.
+- Parameter preparation (`smerisk.prepare`): monthly series to distributions (outliers, seasonality, trend,
+  distribution choice), shrunk Spearman correlations, renewal, stage, and on-time payment rates, receivables
+  transitions and invoices rebuilt from a lettered FEC, employment durations, arrivals and product demand, team
+  daily cost, the data quality report, and traced overrides.
+- Common foundation: response envelope, errors, warning codes, PCG64 seed management, nine probability distributions,
+  and correlation-matrix adjustment.
+- Business use cases (`smerisk.usecases`): `payroll_at_risk`, `cash_at_risk`, `rate_credibility`,
+  `receivables_risk`, `attrition`, `ledger_audit`, `fixed_price_risk`, `utilization_forecast`, `fresh_orders`,
+  `counter_staffing`, and `forecast_reliability`. Each takes raw records and settings, prepares the parameters, calls
+  the formulas, and returns the envelope with `derived_parameters` and `data_quality`; overrides apply by path.
+- HTTP service (`smerisk-service`, run from a clone of the repository; only the library goes to PyPI): the 15 formula routes and 11 use case routes under `/v1`, generated from the
+  library's input models; bearer tokens, one per calling application; jobs for simulations (`GET /v1/jobs/{id}`,
+  results kept 24 hours); reusable datasets encrypted in memory (`/v1/datasets`, FEC upload in multipart); errors
+  422, 409, 413, 429, and 500 with a trace identifier; request size limit; OpenAPI contract written by the CI. Datasets can be sent in numbered pages
+  (`PUT /v1/datasets/{id}/pages/{n}`, safe to retry, any order) with the number of pages given at creation or with
+  `complete`; a use case answers 409 `DATASET_INCOMPLETE` while a page is missing. Requests can be compressed with gzip, with a limit on
+  the decompressed size. Structured logs (JSON or text): one event per request, job, and dataset operation, with an
+  `X-Request-ID` that is also the trace id of a 500; no body, record, token, or exception message is ever logged.
+- `simulate_aggregate`: optional `persistent` components and groups (one draw for the whole horizon) and
+  `orientation` (`lower_is_better` measures the risk of a cost overrun). Results of existing inputs are unchanged.
+
+### Changed
+
+- Translated package source comments, docstrings, validation messages, and project documentation into English.
+- Added English formula documentation for all contracts in the API specification.

smerisk-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

smerisk-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: smerisk
+Version: 0.1.0
+Summary: Probabilistic and statistical calculations for managing small and medium-sized businesses: cash at risk, fixed-price projects, credibility, survival, unpaid receivables, Benford, newsvendor, Erlang C.
+Project-URL: Homepage, https://github.com/OussamaELGUERRAOUI/smerisk
+Project-URL: Source, https://github.com/OussamaELGUERRAOUI/smerisk
+Project-URL: Documentation, https://github.com/OussamaELGUERRAOUI/smerisk/tree/main/docs
+Project-URL: Changelog, https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/OussamaELGUERRAOUI/smerisk/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: scipy>=1.13
+Description-Content-Type: text/markdown
+
+# smerisk
+
+Probability and statistical calculations for small and medium-sized businesses: cash-flow and payroll risk,
+fixed-price projects, utilization, rate estimation with sparse data, survival, receivables, accounting anomalies,
+perishable goods, service staffing, and forecast reliability.
+
+Two ways to use it:
+
+- **Python library** (`pip install smerisk`): pure functions with no database or network access.
+- **HTTP service** (FastAPI): clone this repository and run the service to call the same functions under `/v1/...`
+  from any language; see [Running the HTTP service](#running-the-http-service).
+
+Documentation of each formula and use case is in [`docs/`](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/docs/README.md).
+
+> **Status:** first release (`0.1.0`, alpha). All the functions of the specification are implemented: the formulas,
+> the raw data contracts, parameter preparation, the eleven business use cases, and the HTTP service. The API may
+> still change before 1.0; see the [changelog](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/CHANGELOG.md).
+
+## Installation
+
+```bash
+pip install smerisk
+```
+
+## Example
+
+```python
+from smerisk import risk_measures
+
+result = risk_measures(
+    samples=[float(value) for value in range(1, 101)],
+    confidence=0.95,
+)
+
+print(round(result.result.quantile, 2))  # 5.95
+print(round(result.result.var, 2))  # 44.55
+print(result.result.expected_shortfall)  # 3.0
+print(result.assumptions)
+```
+
+## Running the HTTP service
+
+### Prerequisites
+
+- **Python 3.11 or newer** (`python --version`) and **Git**.
+- Nothing else to install by hand: `pip install ./ ./service` installs the library and the service with all their
+  dependencies (FastAPI, Uvicorn, Pydantic, NumPy, SciPy, cryptography, python-multipart).
+
+### 1. Get the code and install it
+
+Linux and macOS:
+
+```bash
+git clone https://github.com/OussamaELGUERRAOUI/smerisk.git
+cd smerisk
+python3 -m venv .venv
+.venv/bin/python -m pip install ./ ./service
+```
+
+Windows (PowerShell):
+
+```powershell
+git clone https://github.com/OussamaELGUERRAOUI/smerisk.git
+cd smerisk
+python -m venv .venv
+.venv\Scripts\python -m pip install ./ ./service
+```
+
+The commands call the Python of `.venv` directly, so there is no environment to activate.
+
+### 2. Choose a token and start the service
+
+Each application that calls the service uses a token: a secret string that you choose. To create one:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+Linux and macOS:
+
+```bash
+export SMERISK_API_TOKENS="paste-the-token-here"
+.venv/bin/python -m uvicorn smerisk_service.main:app --host 127.0.0.1 --port 8000 --workers 1
+```
+
+Windows (PowerShell):
+
+```powershell
+$env:SMERISK_API_TOKENS = "paste-the-token-here"
+.venv\Scripts\python -m uvicorn smerisk_service.main:app --host 127.0.0.1 --port 8000 --workers 1
+```
+
+Several applications: separate their tokens with commas. `127.0.0.1` keeps the service on your machine; on a server,
+use `--host 0.0.0.0` behind a reverse proxy that serves HTTPS. Keep `--workers 1`. Stop the service with `Ctrl+C`.
+
+### 3. Check that it works
+
+- `http://127.0.0.1:8000/health` answers `{"status": "ok", ...}`.
+- `http://127.0.0.1:8000/docs` shows every route; the **Authorize** button takes the token.
+- A first calculation:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/pert/estimate \
+  -H "Authorization: Bearer paste-the-token-here" -H "Content-Type: application/json" \
+  -d '{"tasks": [{"id": "design", "optimistic": 2, "most_likely": 4, "pessimistic": 9}]}'
+```
+
+```powershell
+$body = '{"tasks": [{"id": "design", "optimistic": 2, "most_likely": 4, "pessimistic": 9}]}'
+Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/v1/pert/estimate `
+  -Headers @{ Authorization = "Bearer paste-the-token-here" } -ContentType "application/json" -Body $body
+```
+
+The answer contains `"expected": 4.5` in `result.total`.
+
+To update: `git pull`, then run the install command of step 1 again. With Docker instead of Python:
+`docker build -f service/Dockerfile -t smerisk-service .` then
+`docker run -p 8000:8000 -e SMERISK_API_TOKENS=paste-the-token-here smerisk-service`.
+
+The full guide (configuration, use cases, jobs, large datasets, errors, logs) is
+[docs/service.md](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/docs/service.md).
+
+## License
+
+Apache 2.0; see [LICENSE](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/LICENSE).

smerisk-0.1.0/README.md

@@ -0,0 +1,125 @@
+# smerisk
+
+Probability and statistical calculations for small and medium-sized businesses: cash-flow and payroll risk,
+fixed-price projects, utilization, rate estimation with sparse data, survival, receivables, accounting anomalies,
+perishable goods, service staffing, and forecast reliability.
+
+Two ways to use it:
+
+- **Python library** (`pip install smerisk`): pure functions with no database or network access.
+- **HTTP service** (FastAPI): clone this repository and run the service to call the same functions under `/v1/...`
+  from any language; see [Running the HTTP service](#running-the-http-service).
+
+Documentation of each formula and use case is in [`docs/`](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/docs/README.md).
+
+> **Status:** first release (`0.1.0`, alpha). All the functions of the specification are implemented: the formulas,
+> the raw data contracts, parameter preparation, the eleven business use cases, and the HTTP service. The API may
+> still change before 1.0; see the [changelog](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/CHANGELOG.md).
+
+## Installation
+
+```bash
+pip install smerisk
+```
+
+## Example
+
+```python
+from smerisk import risk_measures
+
+result = risk_measures(
+    samples=[float(value) for value in range(1, 101)],
+    confidence=0.95,
+)
+
+print(round(result.result.quantile, 2))  # 5.95
+print(round(result.result.var, 2))  # 44.55
+print(result.result.expected_shortfall)  # 3.0
+print(result.assumptions)
+```
+
+## Running the HTTP service
+
+### Prerequisites
+
+- **Python 3.11 or newer** (`python --version`) and **Git**.
+- Nothing else to install by hand: `pip install ./ ./service` installs the library and the service with all their
+  dependencies (FastAPI, Uvicorn, Pydantic, NumPy, SciPy, cryptography, python-multipart).
+
+### 1. Get the code and install it
+
+Linux and macOS:
+
+```bash
+git clone https://github.com/OussamaELGUERRAOUI/smerisk.git
+cd smerisk
+python3 -m venv .venv
+.venv/bin/python -m pip install ./ ./service
+```
+
+Windows (PowerShell):
+
+```powershell
+git clone https://github.com/OussamaELGUERRAOUI/smerisk.git
+cd smerisk
+python -m venv .venv
+.venv\Scripts\python -m pip install ./ ./service
+```
+
+The commands call the Python of `.venv` directly, so there is no environment to activate.
+
+### 2. Choose a token and start the service
+
+Each application that calls the service uses a token: a secret string that you choose. To create one:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+Linux and macOS:
+
+```bash
+export SMERISK_API_TOKENS="paste-the-token-here"
+.venv/bin/python -m uvicorn smerisk_service.main:app --host 127.0.0.1 --port 8000 --workers 1
+```
+
+Windows (PowerShell):
+
+```powershell
+$env:SMERISK_API_TOKENS = "paste-the-token-here"
+.venv\Scripts\python -m uvicorn smerisk_service.main:app --host 127.0.0.1 --port 8000 --workers 1
+```
+
+Several applications: separate their tokens with commas. `127.0.0.1` keeps the service on your machine; on a server,
+use `--host 0.0.0.0` behind a reverse proxy that serves HTTPS. Keep `--workers 1`. Stop the service with `Ctrl+C`.
+
+### 3. Check that it works
+
+- `http://127.0.0.1:8000/health` answers `{"status": "ok", ...}`.
+- `http://127.0.0.1:8000/docs` shows every route; the **Authorize** button takes the token.
+- A first calculation:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/pert/estimate \
+  -H "Authorization: Bearer paste-the-token-here" -H "Content-Type: application/json" \
+  -d '{"tasks": [{"id": "design", "optimistic": 2, "most_likely": 4, "pessimistic": 9}]}'
+```
+
+```powershell
+$body = '{"tasks": [{"id": "design", "optimistic": 2, "most_likely": 4, "pessimistic": 9}]}'
+Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/v1/pert/estimate `
+  -Headers @{ Authorization = "Bearer paste-the-token-here" } -ContentType "application/json" -Body $body
+```
+
+The answer contains `"expected": 4.5` in `result.total`.
+
+To update: `git pull`, then run the install command of step 1 again. With Docker instead of Python:
+`docker build -f service/Dockerfile -t smerisk-service .` then
+`docker run -p 8000:8000 -e SMERISK_API_TOKENS=paste-the-token-here smerisk-service`.
+
+The full guide (configuration, use cases, jobs, large datasets, errors, logs) is
+[docs/service.md](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/docs/service.md).
+
+## License
+
+Apache 2.0; see [LICENSE](https://github.com/OussamaELGUERRAOUI/smerisk/blob/main/LICENSE).

smerisk-0.1.0/docs/README.md

@@ -0,0 +1,62 @@
+# smerisk documentation
+
+There is one page per formula and per use case. Each page describes its purpose, input and output contracts,
+calculation, warnings, errors, and limitations. The contracts are based on the specification (§3–§12). The specification is currently
+kept outside this repository and remains the source of truth.
+
+**Implementation status:** all fifteen formulas and eleven use cases are implemented in the Python package and served
+by the HTTP service under the endpoints below; see [HTTP service](service.md).
+
+## Formula reference
+
+| Domain | Function | Endpoint | Documentation | Status |
+| --- | --- | --- | --- | --- |
+| Simulation | `simulate_aggregate` | `POST /v1/simulation/aggregate` | [simulate_aggregate](formulas/simulate_aggregate.md) | Implemented |
+| Simulation | `risk_measures` | `POST /v1/risk/measures` | [risk_measures](formulas/risk_measures.md) | Implemented |
+| Projects | `pert_estimate` | `POST /v1/pert/estimate` | [pert_estimate](formulas/pert_estimate.md) | Implemented |
+| Projects | `fixed_price_completion` | `POST /v1/projects/fixed-price-completion` | [fixed_price_completion](formulas/fixed_price_completion.md) | Implemented |
+| Projects | `utilization_forecast` | `POST /v1/utilization/forecast` | [utilization_forecast](formulas/utilization_forecast.md) | Implemented |
+| Rates | `credibility` | `POST /v1/bayes/credibility` | [credibility](formulas/credibility.md) | Implemented |
+| Rates | `beta_binomial` | `POST /v1/bayes/beta-binomial` | [beta_binomial](formulas/beta_binomial.md) | Implemented |
+| Durations | `kaplan_meier` | `POST /v1/survival/kaplan-meier` | [kaplan_meier](formulas/kaplan_meier.md) | Implemented |
+| Receivables | `markov_payments` | `POST /v1/credit/markov-payments` | [markov_payments](formulas/markov_payments.md) | Implemented |
+| Receivables | `expected_loss` | `POST /v1/credit/expected-loss` | [expected_loss](formulas/expected_loss.md) | Implemented |
+| Audit | `benford` | `POST /v1/audit/benford` | [benford](formulas/benford.md) | Implemented |
+| Operations | `newsvendor` | `POST /v1/operations/newsvendor` | [newsvendor](formulas/newsvendor.md) | Implemented |
+| Operations | `erlang_c` | `POST /v1/operations/erlang-c` | [erlang_c](formulas/erlang_c.md) | Implemented |
+| Forecast reliability | `brier` | `POST /v1/validation/brier` | [brier](formulas/brier.md) | Implemented |
+| Forecast reliability | `kupiec` | `POST /v1/validation/kupiec` | [kupiec](formulas/kupiec.md) | Implemented |
+
+## Use cases
+
+The use cases (specification §12) take raw data, prepare the parameters, call the formulas, and return the usual
+envelope with `derived_parameters` (each parameter used, with its source) and `data_quality`. They are implemented in
+`smerisk.usecases` and served under `/v1/usecases/…`.
+
+| Function | Endpoint | Answers | Documentation |
+| --- | --- | --- | --- |
+| `payroll_at_risk` | `POST /v1/usecases/payroll-at-risk` | payroll cost of the coming months, variable parts and hires | [payroll_at_risk](usecases/payroll_at_risk.md) |
+| `cash_at_risk` | `POST /v1/usecases/cash-at-risk` | weekly bank balance and probability of running short | [cash_at_risk](usecases/cash_at_risk.md) |
+| `rate_credibility` | `POST /v1/usecases/rate-credibility` | credible absenteeism or turnover rate per group | [rate_credibility](usecases/rate_credibility.md) |
+| `receivables_risk` | `POST /v1/usecases/receivables-risk` | ageing of receivables and expected loss | [receivables_risk](usecases/receivables_risk.md) |
+| `attrition` | `POST /v1/usecases/attrition` | retention curves of employees | [attrition](usecases/attrition.md) |
+| `ledger_audit` | `POST /v1/usecases/ledger-audit` | Benford's test on ledger amounts | [ledger_audit](usecases/ledger_audit.md) |
+| `fixed_price_risk` | `POST /v1/usecases/fixed-price-risk` | final cost, margin, and deadline of fixed-price projects | [fixed_price_risk](usecases/fixed_price_risk.md) |
+| `utilization_forecast` | `POST /v1/usecases/utilization-forecast` | billable utilization and bench of a consulting team | [utilization_forecast](usecases/utilization_forecast.md) |
+| `fresh_orders` | `POST /v1/usecases/fresh-orders` | quantities of perishable products to prepare | [fresh_orders](usecases/fresh_orders.md) |
+| `counter_staffing` | `POST /v1/usecases/counter-staffing` | agents needed at the counter by hour | [counter_staffing](usecases/counter_staffing.md) |
+| `forecast_reliability` | `POST /v1/usecases/forecast-reliability` | reliability of past probabilities and intervals | [forecast_reliability](usecases/forecast_reliability.md) |
+
+## Raw data and service
+
+The use cases (specification §12) take the records a business application already stores rather than parameters.
+[Raw data contracts](data-contracts.md) describes them, the handling of invalid records, and how a FEC file is read.
+[Parameter preparation](parameter-preparation.md) describes how the parameters of the formulas are estimated from
+them, the data quality report, and overrides. [HTTP service](service.md) describes how to run the service, its
+tokens, jobs, datasets, and errors.
+
+## Shared conventions
+
+The specified response envelope contains `result`, `assumptions`, `warnings`, and `meta`. Randomized calculations
+record their seed in `assumptions`. Shared error and warning contracts are described in the external API
+specification (§2.1–§2.6).