fuzzytool

A clean, extensible fuzzy-logic toolkit in pure Python + NumPy. Its design priorities are a composable API, algorithm comparison, visualization and code clarity — a modern alternative to the verbose control API of scikit-fuzzy.

import fuzzytool as fz

# Credit-risk premium: a lender turns a credit score + debt-to-income ratio
# into the risk points it adds on top of its base interest rate.
score   = fz.Variable("score", (300, 850), terms=["poor", "fair", "good", "excellent"])
dti     = fz.Variable("dti", (0, 50), terms=["low", "moderate", "high"])
premium = fz.Variable("premium", (0, 12), terms=["low", "medium", "high"])

sys = fz.Mamdani(defuzz="centroid")
sys.rule(score["poor"] | dti["high"], premium["high"])        # |=OR  &=AND  ~=NOT
sys.rule(score["fair"] & dti["moderate"], premium["medium"])
sys.rule(score["good"] | score["excellent"], premium["low"])

print(sys(score=800, dti=10))    # the system is just callable -> a low premium

The design idea (extensibility)

The inference loop knows nothing about any concrete variant. Everything that changes lives behind small Python Protocols:

• MembershipFunction (fuzzytool/membership.py) — a callable x -> degree. A new shape = a new callable.
• Norm (fuzzytool/norms.py) — t-norms (AND), s-norms (OR) and complements (NOT), resolved by name. A new connective = one registered function.
• defuzzifiers (fuzzytool/defuzz.py) — centroid, bisector, MOM/SOM/LOM, weighted average, COA, resolved by name.

Rules read like logic thanks to operator overloading: & is the t-norm, | the s-norm, ~ the complement. They can also be written the way a policy document writes them:

sys.rule_from_text("IF score IS poor OR dti IS high THEN premium IS high",
                   [score, dti, premium])

Every model explains and audits itself

A fuzzy system is supposed to be readable — but nothing stops a rule base from contradicting itself or leaving regions where no rule fires, and neither is visible at the call site. So every engine answers why, and the whole rule base can be checked:

sys.explain(score=520, dti=42)      # the output + which rules produced it
print(audit(sys))                   # contradictions, dead rules, coverage holes

audit: 3 rules, coverage 91.7%
  unused terms (1):
    dti[low]
  uncovered inputs (10):
    {'score': 630.0, 'dti': 0.0}
    ...

What it includes / roadmap

v0.7.0

• Fuzzy classification: FuzzyClassifier (class-label consequents with certainty factors, predict_proba, an explicit reject option) and the chi learning algorithm, plus scikit-learn estimators.
• Rule-base auditing: audit finds contradictions, duplicates, dead rules, unused and indistinguishable terms, and coverage holes; prune removes what carries no information; interpretability reports readability metrics.
• Rules as text: rule_from_text / parse_rule — the syntax a policy document (or an LLM) writes.
• explain / summary / firing on every engine, promoted from the agents integration into the core.
• Fuzzy relations and measures: the compositional rule of inference, six implication operators, composition, transitive closure; distances, similarity, subsethood, entropy.
• Faster: antecedent evaluation is memoized per call (~8× on a 125-rule system), predict chunks large batches, and eiasc type reduction is 6-12× faster than Karnik-Mendel with identical results.
• Scatter partitions: subtractive_clustering, chiu_tsk, cmeans_tsk, and ANFIS(partition="cluster") — 42× faster with 24× fewer rules on a 5-input problem.
• More shapes and connectives: smf, zmf, pimf, gauss2, singleton; Einstein/Hamacher/drastic/nilpotent norms and the Yager, Dombi and Frank families; a pluggable complement; wtaver and coa defuzzifiers.

v0.5.0

• General type-2 (GT2) fuzzy sets via the zSlices / alpha-plane representation: GeneralType2MF, the gt2_* constructors, GeneralType2Mamdani inference and centroid_gt2 type reduction — reusing the existing interval type-2 / Karnik-Mendel machinery.

v0.4.0

• turboswarm integration: gradient-free, global tuning of a fuzzy system's membership functions with Particle Swarm Optimization (integrations.turboswarm.tune) — the metaheuristic sibling of the SciPy tuner.

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.

Install

pip install fuzzytool            # core (NumPy only)
pip install fuzzytool[viz]       # + matplotlib visualization

From source, for development:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,viz,docs]"
pytest -q
python examples/fraud_alert.py
python examples/loan_decision.py     # classification + explanation + audit
python benchmarks/benchmark.py       # reproducible timings

Documentation

A documentation portal (narrative guide + API reference from docstrings) is built with MkDocs Material and published to GitHub Pages: https://fuzzytool.github.io/.

pip install -e ".[docs]"
mkdocs serve        # live portal at http://127.0.0.1:8000

License

MIT. See LICENSE.