fuzzytool 0.1.0__tar.gz → 0.3.0__tar.gz

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/CHANGELOG.md

@@ -6,12 +6,68 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-27
+
+### Added
+
+- **Ecosystem integrations** under `fuzzytool.integrations.*` — each behind its
+  own extra and importing its dependency only on use, so the core stays pure
+  NumPy:
+  - **pandas** (`[pandas]`): `predict_df`, `rules_dataframe`,
+    `memberships_dataframe`, `components_dataframe`.
+  - **scikit-learn** (`[sklearn]`): `Fuzzifier` transformer (crisp →
+    membership-degree features), `WangMendelRegressor`, `FuzzySystemRegressor`.
+  - **PyTorch** (`[torch]`): `FuzzyLayer`, a differentiable first-order TSK
+    `nn.Module` trainable by autograd and composable into a network.
+  - **SciPy** (`[scipy]`): `tune`, fitting a system's membership-function
+    parameters to data via `scipy.optimize.least_squares`.
+  - **Optuna** (`[optuna]`): `suggest_inference_spec`, `suggest_anfis`, and a
+    ready-made `tune_anfis` study.
+  - **Joblib / Dask** (`[parallel]`, `[dask]`): `parallel_predict`,
+    `multi_start_cmeans`, `dask_predict`.
+  - **LLM agents** (`[agents]`): `explain` (crisp output + fired rules) and
+    `inference_tool` (a LangChain `StructuredTool`).
+- Tutorials section (investment-risk advisor, ANFIS, Fuzzy TOPSIS, clustering)
+  and an Integrations guide page; rendered plots and computed results embedded
+  throughout the docs.
+
+## [0.2.0] - 2026-06-24
+
+### Added
+
+- **Fuzzy numbers & MCDM**: `fuzzytool.fuzzynum` (triangular/trapezoidal numbers
+  with arithmetic, alpha-cuts, centroid, distance, ranking) and `fuzzytool.mcdm`
+  (`fuzzy_topsis`, `fuzzy_ahp`).
+- **Rule learning**: `wang_mendel` generates a Mamdani rule base from data.
+- **Tsukamoto** inference (`fuzzytool.inference.Tsukamoto`) with monotonic
+  consequents; added invertible `ramp_up` / `ramp_down` membership functions and
+  an `inverse` on `sigmoid`.
+- **Batch inference**: `Mamdani.predict` / `TSK.predict` evaluate array-valued
+  inputs in a vectorized pass.
+- **Serialization**: `fz.save` / `fz.load` (JSON) for Mamdani/TSK systems, plus
+  `to_dict`/`from_dict` on membership functions and variables.
+- **scikit-learn compatibility**: `ANFIS.get_params` / `set_params`.
+
+## [0.1.0] - 2026-06-24
+
 ### Added
 
+- Core membership functions: triangular, trapezoidal, gaussian, generalized
+  bell, sigmoid (`fuzzytool.membership`).
+- T-norms and s-norms (min/prod/Łukasiewicz, max/probor/Łukasiewicz), resolved
+  by name (`fuzzytool.norms`).
+- `Variable` (linguistic variable) with auto-generated or explicit terms, and an
+  operator-based rule-antecedent expression tree (`&`, `|`, `~`).
+- **Mamdani** inference with configurable implication/aggregation and
+  defuzzification (centroid, bisector, MOM/SOM/LOM).
+- **Takagi-Sugeno (TSK)** inference (zero- and first-order, plus callable
+  consequents).
+- `fuzzytool.viz`: membership-function plots and 2-input control surfaces.
+- `fuzzytool.datasets.credit_risk`: the flagship example system.
 - Example notebooks (`notebooks/`): quickstart, interval type-2, clustering, and
   ANFIS/F-transform — committed executed.
-- Documentation: a comparison page vs scikit-fuzzy and a citing/releasing page;
-  `.zenodo.json` for DOI archival; `notebooks` optional dependency group.
+- Documentation (MkDocs Material), CI, a comparison page vs scikit-fuzzy, a
+  citing/releasing page, and `.zenodo.json` for DOI archival.
 - **ANFIS** (`fuzzytool.anfis.ANFIS`): a trainable first-order Sugeno system over
   a grid partition, fit with Jang's hybrid scheme (least-squares consequents +
   gradient-descent premises). `fit` / `predict` / `history_`.
@@ -32,21 +88,4 @@ All notable changes to this project are documented here. The format is based on
   - `IT2Mamdani` (center-of-sets type reduction) and `IT2TSK` engines.
   - Karnik-Mendel type reduction: `km_endpoint`, `karnik_mendel`, `centroid_it2`.
   - `viz.plot_it2_variable` (shaded FOU); `datasets.credit_risk_it2`.
-
-## [0.1.0] - 2026-06-24
-
-### Added
-
-- Core membership functions: triangular, trapezoidal, gaussian, generalized
-  bell, sigmoid (`fuzzytool.membership`).
-- T-norms and s-norms (min/prod/Łukasiewicz, max/probor/Łukasiewicz), resolved
-  by name (`fuzzytool.norms`).
-- `Variable` (linguistic variable) with auto-generated or explicit terms, and an
-  operator-based rule-antecedent expression tree (`&`, `|`, `~`).
-- **Mamdani** inference with configurable implication/aggregation and
-  defuzzification (centroid, bisector, MOM/SOM/LOM).
-- **Takagi-Sugeno (TSK)** inference (zero- and first-order, plus callable
-  consequents).
-- `fuzzytool.viz`: membership-function plots and 2-input control surfaces.
-- `fuzzytool.datasets.tipper`: the classic example system.
-- Test suite, MkDocs Material documentation, and CI.
+- Test suite covering every module.

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/CITATION.cff

@@ -5,8 +5,9 @@ type: software
 authors:
   - family-names: Salmeron
     given-names: Jose L.
-version: 0.1.0
-date-released: 2026-06-24
+version: 0.3.0
+date-released: 2026-06-27
+doi: 10.5281/zenodo.20836712
 license: MIT
 repository-code: "https://github.com/fuzzytool/fuzzytool.github.io"
 url: "https://fuzzytool.github.io"

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fuzzytool
-Version: 0.1.0
+Version: 0.3.0
 Summary: A clean, extensible fuzzy-logic toolkit in pure Python + NumPy
 Project-URL: Homepage, https://fuzzytool.github.io
 Project-URL: Documentation, https://fuzzytool.github.io
@@ -18,10 +18,20 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.9
 Requires-Dist: numpy>=1.21
+Provides-Extra: agents
+Requires-Dist: langchain-core>=0.1; extra == 'agents'
+Provides-Extra: dask
+Requires-Dist: dask>=2022.0; extra == 'dask'
 Provides-Extra: dev
+Requires-Dist: joblib>=1.0; extra == 'dev'
+Requires-Dist: langchain-core>=0.1; extra == 'dev'
+Requires-Dist: optuna>=3.0; extra == 'dev'
+Requires-Dist: pandas>=1.3; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scikit-learn>=1.0; extra == 'dev'
+Requires-Dist: scipy>=1.7; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
@@ -31,6 +41,18 @@ Requires-Dist: jupyter; extra == 'notebooks'
 Requires-Dist: matplotlib>=3.4; extra == 'notebooks'
 Requires-Dist: nbconvert; extra == 'notebooks'
 Requires-Dist: nbformat; extra == 'notebooks'
+Provides-Extra: optuna
+Requires-Dist: optuna>=3.0; extra == 'optuna'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Provides-Extra: parallel
+Requires-Dist: joblib>=1.0; extra == 'parallel'
+Provides-Extra: scipy
+Requires-Dist: scipy>=1.7; extra == 'scipy'
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.0; extra == 'sklearn'
+Provides-Extra: torch
+Requires-Dist: torch>=1.12; extra == 'torch'
 Provides-Extra: viz
 Requires-Dist: matplotlib>=3.4; extra == 'viz'
 Description-Content-Type: text/markdown
@@ -41,6 +63,7 @@ Description-Content-Type: text/markdown
   <a href="https://fuzzytool.github.io/"><img src="https://img.shields.io/badge/docs-fuzzytool.github.io-3f51b5" alt="Docs"></a>
   <img src="https://img.shields.io/pypi/pyversions/fuzzytool?logo=python&logoColor=white" alt="Python versions">
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT">
+  <a href="https://doi.org/10.5281/zenodo.20836712"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20836712.svg" alt="DOI"></a>
 </p>
 
 # fuzzytool
@@ -85,12 +108,32 @@ s-norm, `~` the complement.
 
 | Phase | Content | Status |
 |------|-----------|--------|
-| 1 | Core: membership functions, t-/s-norms, `Variable`, operator rules, **Mamdani** + defuzzification, tipper example, tests | ✅ |
+| 1 | Core: membership functions, t-/s-norms, `Variable`, operator rules, **Mamdani** + defuzzification, fraud-alert example, tests | ✅ |
 | 2 | **Takagi-Sugeno (TSK)** inference + `viz` (membership plots, control surface) | ✅ (TSK + viz) |
 | 3 | **Type-2 / interval type-2** sets (footprint of uncertainty) + Karnik-Mendel type reduction | ✅ |
 | 4 | **Fuzzy clustering**: fuzzy c-means, Gustafson-Kessel, possibilistic | ✅ |
 | 5 | **ANFIS** (trainable TSK) + **F-transform** (direct/inverse) | ✅ |
-| 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ⏳ |
+| 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
+| 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, Optuna, Joblib/Dask, LLM agents | ✅ |
+
+### v0.3.0
+
+- **Integrations** (`fuzzytool.integrations.*`, each behind its own extra):
+  **pandas** (DataFrame I/O), **scikit-learn** (`Fuzzifier`, regressors),
+  **PyTorch** (differentiable `FuzzyLayer`), **SciPy** (MF tuning), **Optuna**
+  (hyperparameter search), **Joblib/Dask** (parallel inference) and
+  **LLM agents** (explainable `inference_tool`).
+- **Tutorials** and an **Integrations** guide page, with rendered plots and
+  computed outputs throughout the docs.
+
+### v0.2.0
+
+- **Fuzzy numbers & MCDM:** triangular/trapezoidal fuzzy-number arithmetic,
+  **Fuzzy TOPSIS** and **Fuzzy AHP**.
+- **Rule learning:** **Wang-Mendel** rule-base generation from data; **Tsukamoto**
+  inference (monotonic consequents).
+- **Engineering:** vectorized **batch inference** (`predict`), JSON
+  **save/load**, and a **scikit-learn** estimator interface for ANFIS.
 
 See [`ROADMAP.md`](ROADMAP.md).
 
@@ -107,7 +150,7 @@ From source, for development:
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev,viz,docs]"
 pytest -q
-python examples/tipper.py
+python examples/fraud_alert.py
 ```
 
 ## Documentation

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/README.md

@@ -4,6 +4,7 @@
   <a href="https://fuzzytool.github.io/"><img src="https://img.shields.io/badge/docs-fuzzytool.github.io-3f51b5" alt="Docs"></a>
   <img src="https://img.shields.io/pypi/pyversions/fuzzytool?logo=python&logoColor=white" alt="Python versions">
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT">
+  <a href="https://doi.org/10.5281/zenodo.20836712"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20836712.svg" alt="DOI"></a>
 </p>
 
 # fuzzytool
@@ -48,12 +49,32 @@ s-norm, `~` the complement.
 
 | Phase | Content | Status |
 |------|-----------|--------|
-| 1 | Core: membership functions, t-/s-norms, `Variable`, operator rules, **Mamdani** + defuzzification, tipper example, tests | ✅ |
+| 1 | Core: membership functions, t-/s-norms, `Variable`, operator rules, **Mamdani** + defuzzification, fraud-alert example, tests | ✅ |
 | 2 | **Takagi-Sugeno (TSK)** inference + `viz` (membership plots, control surface) | ✅ (TSK + viz) |
 | 3 | **Type-2 / interval type-2** sets (footprint of uncertainty) + Karnik-Mendel type reduction | ✅ |
 | 4 | **Fuzzy clustering**: fuzzy c-means, Gustafson-Kessel, possibilistic | ✅ |
 | 5 | **ANFIS** (trainable TSK) + **F-transform** (direct/inverse) | ✅ |
-| 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ⏳ |
+| 6 | Notebooks, JOSS `paper.md`, Zenodo DOI, PyPI release | ✅ |
+| 7 | **Ecosystem integrations**: pandas, scikit-learn, PyTorch, SciPy, Optuna, Joblib/Dask, LLM agents | ✅ |
+
+### v0.3.0
+
+- **Integrations** (`fuzzytool.integrations.*`, each behind its own extra):
+  **pandas** (DataFrame I/O), **scikit-learn** (`Fuzzifier`, regressors),
+  **PyTorch** (differentiable `FuzzyLayer`), **SciPy** (MF tuning), **Optuna**
+  (hyperparameter search), **Joblib/Dask** (parallel inference) and
+  **LLM agents** (explainable `inference_tool`).
+- **Tutorials** and an **Integrations** guide page, with rendered plots and
+  computed outputs throughout the docs.
+
+### v0.2.0
+
+- **Fuzzy numbers & MCDM:** triangular/trapezoidal fuzzy-number arithmetic,
+  **Fuzzy TOPSIS** and **Fuzzy AHP**.
+- **Rule learning:** **Wang-Mendel** rule-base generation from data; **Tsukamoto**
+  inference (monotonic consequents).
+- **Engineering:** vectorized **batch inference** (`predict`), JSON
+  **save/load**, and a **scikit-learn** estimator interface for ANFIS.
 
 See [`ROADMAP.md`](ROADMAP.md).
 
@@ -70,7 +91,7 @@ From source, for development:
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev,viz,docs]"
 pytest -q
-python examples/tipper.py
+python examples/fraud_alert.py
 ```
 
 ## Documentation

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/ROADMAP.md

@@ -10,13 +10,13 @@ self-contained, testable increment.
 - [x] T-norms / s-norms resolved by name; standard complement.
 - [x] `Variable` + operator-based antecedent tree (`&`, `|`, `~`).
 - [x] Mamdani inference + defuzzification (centroid, bisector, MOM/SOM/LOM).
-- [x] Tipper example, test suite, packaging, docs, CI.
+- [x] Fraud-alert example, test suite, packaging, docs, CI.
 
 ## ✅ Phase 2 — TSK + visualization
 
 - [x] Takagi-Sugeno inference (zero/first-order + callable consequents).
 - [x] `viz`: membership plots, 2-input control surface.
-- [ ] Example notebooks (tipper, TSK, comparison).
+- [ ] Example notebooks (fraud-alert, TSK).
 
 ## ✅ Phase 3 — Type-2 / interval type-2
 
@@ -42,7 +42,41 @@ self-contained, testable increment.
 - [x] F-transform: direct and inverse over a triangular fuzzy partition
       (partition of unity), with smoothing/denoising.
 
-## ⏳ Phase 6 — Release
+## ✅ v0.2.0 — Decision-making, rule learning, engineering
+
+- [x] Fuzzy numbers (triangular/trapezoidal) + arithmetic; fuzzy MCDM
+      (`fuzzy_topsis`, `fuzzy_ahp`).
+- [x] Rule learning from data (`wang_mendel`); Tsukamoto inference with
+      invertible ramp/sigmoid MFs.
+- [x] Vectorized batch inference (`Mamdani.predict` / `TSK.predict`);
+      JSON serialization (`save`/`load`); scikit-learn estimator interface on ANFIS.
+
+## 🔌 Ecosystem integrations (`fuzzytool.integrations.*`)
+
+Each pulls its dependency in only on import, behind its own extra.
+
+- [x] **pandas** (`[pandas]`): `predict_df`, `rules_dataframe`,
+      `memberships_dataframe`, `components_dataframe`.
+- [x] **scikit-learn** (`[sklearn]`): `Fuzzifier` transformer,
+      `WangMendelRegressor`, `FuzzySystemRegressor` (ANFIS already compatible).
+- [x] **PyTorch** (`[torch]`): `FuzzyLayer`, a differentiable first-order TSK
+      `nn.Module` trainable by autograd and composable into a network.
+- [x] **SciPy** (`[scipy]`): `tune` MF parameters to data via
+      `scipy.optimize.least_squares` (returns the `OptimizeResult`).
+- [x] **Optuna** (`[optuna]`): `suggest_inference_spec`, `suggest_anfis` and a
+      ready-made `tune_anfis` study.
+- [x] **Joblib / Dask** (`[parallel]`, `[dask]`): `parallel_predict`,
+      `multi_start_cmeans`, `dask_predict`.
+- [x] **Agents (LangChain/LangGraph)** (`[agents]`): `explain` plus an
+      `inference_tool` LangChain tool that reports which rules fired.
+
+## Ideas for later
+
+- Fuzzy cognitive maps (+ grey FCM).
+- General (non-interval) type-2; more defuzzifiers.
+- FIS tuning via metaheuristics (e.g. PSO).
+
+## ⏳ Phase 6 — Release (v0.1.0)
 
 - [x] Example notebooks (`notebooks/`) and a comparison page vs scikit-fuzzy.
 - [x] JOSS `paper.md`; Zenodo metadata (`.zenodo.json`) and a citing/releasing page.

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/api/python.md

@@ -30,6 +30,26 @@ Generated from docstrings with `mkdocstrings`.
 
 ::: fuzzytool.inference.tsk
 
+## Inference — Tsukamoto
+
+::: fuzzytool.inference.tsukamoto
+
+## Rule learning (Wang-Mendel)
+
+::: fuzzytool.learn
+
+## Fuzzy numbers
+
+::: fuzzytool.fuzzynum
+
+## Fuzzy MCDM
+
+::: fuzzytool.mcdm
+
+## Serialization
+
+::: fuzzytool.serialize
+
 ## Interval type-2 — sets
 
 ::: fuzzytool.type2.sets
@@ -58,6 +78,30 @@ Generated from docstrings with `mkdocstrings`.
 
 ::: fuzzytool.viz
 
+## Integrations — pandas
+
+::: fuzzytool.integrations.pandas
+
+## Integrations — scikit-learn
+
+::: fuzzytool.integrations.sklearn
+
+## Integrations — SciPy
+
+::: fuzzytool.integrations.scipy
+
+## Integrations — Optuna
+
+::: fuzzytool.integrations.optuna
+
+## Integrations — Joblib / Dask
+
+::: fuzzytool.integrations.parallel
+
+## Integrations — LLM agents
+
+::: fuzzytool.integrations.agents
+
 ## Datasets
 
 ::: fuzzytool.datasets

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/citing.md

@@ -2,9 +2,10 @@
 
 ## Citing
 
-If you use fuzzytool in academic work, please cite it. Repository metadata lives
-in [`CITATION.cff`](https://github.com/fuzzytool/fuzzytool.github.io/blob/main/CITATION.cff);
-once a release is archived on Zenodo, cite the versioned DOI it mints.
+If you use fuzzytool in academic work, please cite it. The archival DOI (all
+versions) is [10.5281/zenodo.20836712](https://doi.org/10.5281/zenodo.20836712);
+each release also mints its own versioned DOI. Repository citation metadata lives
+in [`CITATION.cff`](https://github.com/fuzzytool/fuzzytool.github.io/blob/main/CITATION.cff).
 
 ## Releasing (maintainers)
 

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/getting-started.md

@@ -41,8 +41,8 @@ sys.rule(score["good"] | score["excellent"], premium["low"])
 The system is **callable**. Pass crisp inputs by variable name:
 
 ```python
-sys(score=800, dti=10)    # strong borrower -> low premium
-sys(score=520, dti=42)    # weak borrower  -> high premium
+sys(score=800, dti=10)    # strong borrower -> 2.45 pts (low premium)
+sys(score=520, dti=42)    # weak borrower   -> 9.93 pts (high premium)
 ```
 
 ## 4. Visualize (optional)
@@ -55,3 +55,7 @@ viz.plot_variable(score)
 viz.control_surface(sys, score, dti)
 plt.show()
 ```
+
+![Membership functions of the score variable: poor, fair, good and excellent terms](images/gs_score_terms.png)
+
+![Control surface: risk premium as a function of score and dti](images/credit_control_surface.png)

fuzzytool-0.3.0/docs/guide/batch-and-io.md

@@ -0,0 +1,51 @@
+# Batch inference, serialization & scikit-learn
+
+## Batch (vectorized) inference
+
+Calling a system evaluates one sample. `predict(**arrays)` evaluates many at once
+— pass an array per variable and get an array back. Available on `Mamdani` and
+`TSK`.
+
+```python
+import numpy as np
+from fuzzytool import datasets
+
+sys, *_ = datasets.credit_risk()
+scores = np.array([520.0, 660.0, 800.0])
+dtis   = np.array([42.0, 30.0, 10.0])
+
+sys.predict(score=scores, dti=dtis)   # -> array([10.16, 6.  ,  1.91]), one premium per sample
+```
+
+The result matches calling the system once per sample, but the firing, implication
+and aggregation steps run vectorized.
+
+## Saving and loading systems
+
+Serialize a Mamdani or TSK system to JSON and restore it later. Connectives and
+the defuzzifier must be given **by name**, variables must use **built-in**
+membership functions, and TSK consequents must be numbers or coefficient mappings.
+
+```python
+import fuzzytool as fz
+
+fz.save(sys, "credit_risk.json")
+restored = fz.load("credit_risk.json")
+```
+
+`fuzzytool.membership.to_dict`/`from_dict` and `Variable.to_dict`/`from_dict`
+expose the building blocks if you need finer control.
+
+## scikit-learn compatibility
+
+`ANFIS` follows the estimator protocol (`fit` returns `self`, plus `predict`,
+`get_params`, `set_params`), so it drops into a `Pipeline` or `GridSearchCV`
+without importing scikit-learn at all:
+
+```python
+import fuzzytool as fz
+
+model = fz.ANFIS(n_inputs=2, n_mf=3)
+model.get_params()              # {'n_inputs': 2, 'n_mf': 3, 'learning_rate': 0.05}
+clone = fz.ANFIS(**model.get_params())
+```

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/guide/clustering.md

@@ -48,3 +48,5 @@ from fuzzytool import viz
 viz.plot_clusters(X, res)   # 2-D scatter; opacity encodes top membership
 plt.show()
 ```
+
+![Fuzzy c-means on three blobs: points colored by cluster, centers marked, opacity encoding top membership](../images/clusters.png)

fuzzytool-0.3.0/docs/guide/fraud-alert.md

@@ -0,0 +1,65 @@
+# Worked example: fraud-alert score
+
+A complete, runnable Mamdani system that scores card transactions for fraud. A
+payment monitor turns how far a charge deviates from the customer's usual spend
+(**amount anomaly**, in standard deviations, 0–8) and how many card swipes
+happened in the last hour (**velocity**, 0–30) into a **fraud-risk** score
+(0–100).
+
+The full script lives in
+[`examples/fraud_alert.py`](https://github.com/fuzzytool/fuzzytool/blob/main/examples/fraud_alert.py).
+
+## 1. Define the linguistic variables
+
+```python
+import fuzzytool as fz
+
+amount_anomaly = fz.Variable("amount_anomaly", (0, 8))
+amount_anomaly["normal"] = fz.trap(0, 0, 1, 2.5)
+amount_anomaly["elevated"] = fz.tri(2, 3.5, 5)
+amount_anomaly["extreme"] = fz.trap(4.5, 6, 8, 8)
+
+velocity = fz.Variable("velocity", (0, 30))
+velocity["low"] = fz.trap(0, 0, 3, 6)
+velocity["moderate"] = fz.tri(4, 9, 14)
+velocity["burst"] = fz.trap(12, 20, 30, 30)
+
+fraud_risk = fz.Variable("fraud_risk", (0, 100))
+fraud_risk["low"] = fz.tri(0, 12, 35)
+fraud_risk["medium"] = fz.tri(30, 50, 70)
+fraud_risk["high"] = fz.tri(65, 85, 100)
+```
+
+## 2. Write the rule base
+
+`&` is AND (t-norm), `|` is OR (s-norm), `~` is NOT (complement):
+
+```python
+sys = fz.Mamdani(defuzz="centroid")
+sys.rule(amount_anomaly["extreme"] | velocity["burst"], fraud_risk["high"])
+sys.rule(amount_anomaly["elevated"] & velocity["moderate"], fraud_risk["medium"])
+sys.rule(amount_anomaly["normal"] & velocity["low"], fraud_risk["low"])
+```
+
+## 3. Score transactions
+
+```python
+sys(amount_anomaly=0.5, velocity=2)    # routine charge   -> ~16/100
+sys(amount_anomaly=3.5, velocity=9)    # borderline       -> 50/100
+sys(amount_anomaly=6.5, velocity=22)   # likely fraud     -> ~83/100
+```
+
+## 4. Visualize (optional)
+
+```python
+import matplotlib.pyplot as plt
+from fuzzytool import viz
+
+viz.plot_variable(amount_anomaly)
+viz.control_surface(sys, amount_anomaly, velocity)
+plt.show()
+```
+
+![Membership functions of amount_anomaly: normal, elevated and extreme terms](../images/fraud_anomaly_terms.png)
+
+![Control surface: fraud risk as a function of amount anomaly and transaction velocity](../images/fraud_control_surface.png)

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/guide/ftransform.md

@@ -7,7 +7,7 @@ uses a uniform triangular partition whose basis functions sum to 1 everywhere
 
 - the **direct** transform reduces the data to `n_basis` components, each a
   membership-weighted average of the samples under one basis function;
-- the **inverse** transform reconstructs `f̂(x) = Σ_k F_k · A_k(x)`.
+- the **inverse** transform reconstructs $\hat{f}(x) = \sum_k F_k \, A_k(x)$.
 
 Few components → a smoothing/denoising round trip; many components → a close
 approximation.

fuzzytool-0.3.0/docs/guide/mcdm.md

@@ -0,0 +1,60 @@
+# Fuzzy numbers & MCDM
+
+## Fuzzy numbers
+
+[`fuzzytool.fuzzynum`][fuzzytool.fuzzynum] provides triangular (TFN) and
+trapezoidal (TrFN) fuzzy numbers with arithmetic, alpha-cuts, a crisp centroid,
+and a vertex distance.
+
+```python
+from fuzzytool.fuzzynum import tfn, trfn, rank
+
+a, b = tfn(1, 2, 3), tfn(2, 3, 4)
+a + b              # TFN(3, 5, 7)
+a * 2              # TFN(2, 4, 6)
+a.centroid()       # 2.0
+a.alpha_cut(0.5)   # (1.5, 2.5)
+rank([tfn(0,1,2), tfn(5,6,7)])   # [1, 0] (largest first)
+```
+
+`+`/`-` are exact; `*`/`/` use the standard positive-support approximation.
+
+## Fuzzy multi-criteria decision making
+
+[`fuzzytool.mcdm`][fuzzytool.mcdm] offers two classic methods.
+
+### Fuzzy TOPSIS (Chen)
+
+Rank alternatives by closeness to the fuzzy positive-ideal solution. The decision
+matrix and weights are triangular fuzzy numbers; `benefit[j]` says whether
+criterion `j` is maximized.
+
+```python
+from fuzzytool.fuzzynum import tfn
+from fuzzytool.mcdm import fuzzy_topsis
+
+matrix = [
+    [tfn(7, 8, 9), tfn(5, 6, 7)],   # alternative A: ratings per criterion
+    [tfn(3, 4, 5), tfn(8, 9, 9)],   # alternative B
+]
+weights = [tfn(0.4, 0.5, 0.6), tfn(0.3, 0.4, 0.5)]
+res = fuzzy_topsis(matrix, weights, benefit=[True, True])
+res.closeness   # -> array([0.369, 0.316]), closeness coefficient per alternative
+res.ranking     # -> [0, 1], alternative indices, best first
+```
+
+### Fuzzy AHP (Chang's extent analysis)
+
+Derive crisp criterion weights from a fuzzy pairwise-comparison matrix.
+
+```python
+from fuzzytool.fuzzynum import tfn
+from fuzzytool.mcdm import fuzzy_ahp
+
+one = tfn(1, 1, 1)
+matrix = [
+    [one,                tfn(1, 2, 3)],
+    [tfn(1/3, 1/2, 1),   one],
+]
+fuzzy_ahp(matrix)   # -> array([0.69, 0.31]), normalized crisp weights
+```

fuzzytool-0.3.0/docs/guide/rule-learning.md

@@ -0,0 +1,48 @@
+# Rule learning
+
+## Learning a rule base from data (Wang-Mendel)
+
+[`wang_mendel`][fuzzytool.learn.wang_mendel] generates a Mamdani rule base from
+data: each sample becomes one rule (picking the highest-membership term per
+variable), and antecedent conflicts are resolved by rule degree.
+
+```python
+import numpy as np
+import fuzzytool as fz
+
+X = np.random.default_rng(0).uniform(0, 10, size=(300, 2))
+y = (X[:, 0] + X[:, 1]) / 2
+
+a = fz.Variable("a", (0, 10), terms=["lo", "mid", "hi"])
+b = fz.Variable("b", (0, 10), terms=["lo", "mid", "hi"])
+out = fz.Variable("out", (0, 10), terms=["lo", "mid", "hi"])
+
+sys = fz.wang_mendel(X, y, [a, b], out)   # a ready-to-use Mamdani system
+sys(a=8, b=7)    # -> 5.88  (learned system approximates the mean (a + b) / 2)
+```
+
+The input variables supply the partition; the learned system is a plain
+`Mamdani`, so it also supports batch [`predict`](batch-and-io.md) and
+serialization.
+
+## Tsukamoto inference
+
+[`Tsukamoto`][fuzzytool.inference.tsukamoto.Tsukamoto] consequents are
+**monotonic** membership functions; a rule firing with strength `w` outputs the
+value where its consequent reaches `w` (its inverse), and the system returns the
+firing-weighted average — no defuzzification.
+
+```python
+import fuzzytool as fz
+
+x = fz.Variable("x", (0, 10), terms=["lo", "hi"])
+sys = fz.Tsukamoto()
+sys.rule(x["lo"], fz.ramp_down(0, 30))   # monotonic consequents only
+sys.rule(x["hi"], fz.ramp_up(0, 30))
+sys(x=7)    # -> 21.0
+```
+
+Use [`ramp_up`][fuzzytool.membership.ramp_up],
+[`ramp_down`][fuzzytool.membership.ramp_down], or
+[`sigmoid`][fuzzytool.membership.sigmoid] — each exposes the `inverse` Tsukamoto
+needs.

{fuzzytool-0.1.0 → fuzzytool-0.3.0}/docs/guide/tsk.md

@@ -20,7 +20,7 @@ sys.rule(x["small"], 0.0)                       # zero-order
 sys.rule(x["large"], {"const": 1.0, "x": 1.0})  # first-order: 1 + x
 sys.rule(x["small"], lambda x: x**2)            # arbitrary callable
 
-sys(x=10.0)
+sys(x=10.0)    # -> 11.0
 ```
 
 TSK systems are typically faster and differentiable, which makes them the basis