fuzzytool 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -6,6 +6,31 @@ 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

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

@@ -5,8 +5,8 @@ type: software
 authors:
   - family-names: Salmeron
     given-names: Jose L.
-version: 0.2.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"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fuzzytool
-Version: 0.2.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
@@ -86,12 +108,23 @@ 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 | ✅ |
+| 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
 
@@ -117,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.2.0 → fuzzytool-0.3.0}/README.md

@@ -49,12 +49,23 @@ 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 | ✅ |
+| 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
 
@@ -80,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.2.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
 
@@ -51,6 +51,25 @@ self-contained, testable increment.
 - [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).

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

@@ -78,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.2.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.2.0 → fuzzytool-0.3.0}/docs/guide/batch-and-io.md

@@ -14,7 +14,7 @@ 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 of premiums, one per sample
+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

{fuzzytool-0.2.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.2.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.2.0 → fuzzytool-0.3.0}/docs/guide/mcdm.md

@@ -39,8 +39,8 @@ matrix = [
 ]
 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   # closeness coefficient per alternative
-res.ranking     # alternative indices, best first
+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)
@@ -53,8 +53,8 @@ from fuzzytool.mcdm import fuzzy_ahp
 
 one = tfn(1, 1, 1)
 matrix = [
-    [one,                  tfn(2, 3, 4)],
-    [tfn(1/4, 1/3, 1/2),   one],
+    [one,                tfn(1, 2, 3)],
+    [tfn(1/3, 1/2, 1),   one],
 ]
-fuzzy_ahp(matrix)   # normalized weights, e.g. [0.74, 0.26]
+fuzzy_ahp(matrix)   # -> array([0.69, 0.31]), normalized crisp weights
 ```

{fuzzytool-0.2.0 → fuzzytool-0.3.0}/docs/guide/rule-learning.md

@@ -1,4 +1,4 @@
-# Rule learning & Tsukamoto
+# Rule learning
 
 ## Learning a rule base from data (Wang-Mendel)
 
@@ -18,7 +18,7 @@ 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)
+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
@@ -39,7 +39,7 @@ 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)
+sys(x=7)    # -> 21.0
 ```
 
 Use [`ramp_up`][fuzzytool.membership.ramp_up],

{fuzzytool-0.2.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

{fuzzytool-0.2.0 → fuzzytool-0.3.0}/docs/guide/type2.md

@@ -49,7 +49,7 @@ premium["high"] = fz.it2_gauss_uncertain_mean(9.5, 10.5, 1.5)
 sys = fz.IT2Mamdani()
 sys.rule(score["good"], premium["low"])
 sys.rule(score["poor"], premium["high"])
-sys(score=780)
+sys(score=780)    # -> 2.29  (midpoint of the type-reduced interval)
 ```
 
 A ready-made example is [`fuzzytool.datasets.credit_risk_it2`][fuzzytool.datasets].
@@ -62,6 +62,15 @@ reusable primitive ([`fuzzytool.type2.reduction`][fuzzytool.type2.reduction]):
 `km_endpoint` finds one endpoint, `karnik_mendel` returns both, and
 `centroid_it2` applies it to compute an IT2 set's centroid interval.
 
+```python
+import numpy as np
+from fuzzytool.type2.reduction import centroid_it2
+
+good = fz.it2_gauss_uncertain_mean(740, 780, 50)
+universe = np.linspace(300, 850, 400)
+centroid_it2(good, universe)   # -> (738.05, 772.07), the [y_l, y_r] centroid interval
+```
+
 ## Visualization
 
 ```python
@@ -71,3 +80,5 @@ from fuzzytool import viz
 viz.plot_it2_variable(score)   # draws each term's LMF/UMF with a shaded FOU
 plt.show()
 ```
+
+![IT2 score variable: each term's LMF and UMF with a shaded footprint of uncertainty](../images/it2_score.png)

{fuzzytool-0.2.0 → fuzzytool-0.3.0}/docs/guide/visualization.md

@@ -14,6 +14,8 @@ viz.plot_variable(premium)
 plt.show()
 ```
 
+![Membership functions of the premium variable: low, medium and high terms](../images/premium_terms.png)
+
 ## Control surface
 
 For a single-output system over two inputs:
@@ -25,3 +27,5 @@ sys, score, dti, premium = datasets.credit_risk()
 viz.control_surface(sys, score, dti)
 plt.show()
 ```
+
+![Control surface of the credit-risk system: premium as a function of score and dti](../images/credit_control_surface.png)

{fuzzytool-0.2.0 → fuzzytool-0.3.0}/docs/index.md

@@ -33,4 +33,10 @@ sys(score=800, dti=10)   # -> a crisp risk premium
 
 - [Installation](installation.md)
 - [Getting started](getting-started.md)
+- [Tutorials](tutorials/risk-advisor.md) — end-to-end walkthroughs
 - [The guide](guide/membership.md)
+
+## Author
+
+Created and maintained by **Jose L. Salmeron**. If you use fuzzytool in academic
+work, please [cite it](citing.md).