tsetly 0.0.1__tar.gz

tsetly-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The tsetly authors
+
+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.

tsetly-0.0.1/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: tsetly
+Version: 0.0.1
+Summary: A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: interpretable machine learning,learning automata,propositional logic,tsetlin machine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Description-Content-Type: text/markdown
+
+# tsetly
+
+A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read.
+
+```
+      forget ◀────────────────┼────────────────▶ remember
+             1   2   3  …  N  │  N+1  …  2N
+```
+
+A Tsetlin Machine learns AND-rules over bits, like `x0 ∧ ¬x1`. Every rule is a
+team of Tsetlin automata, one per bit and one per negated bit. Each automaton
+walks along its states as the data rewards or penalises it, and once it crosses
+the middle, its bit joins the rule. Rules vote for or against each class, and
+the class with the most votes wins. That is the whole machine
+([Granmo, 2018](https://arxiv.org/abs/1804.01508)).
+
+## Install
+
+```
+pip install tsetly
+```
+
+## Learn XOR through noise
+
+Twelve random bits, of which only the first two matter, and a fifth of the
+training labels flipped:
+
+```python
+import numpy as np
+from tsetly import TsetlinMachine
+
+rng = np.random.default_rng(0)
+X = rng.integers(0, 2, size=(5000, 12))
+y = X[:, 0] ^ X[:, 1]
+noisy = np.where(rng.random(5000) < 0.2, 1 - y, y)
+
+tm = TsetlinMachine(clauses=8, T=15, s=3.9, seed=1)
+tm.fit(X[:4000], noisy[:4000], epochs=20)
+
+print(tm.score(X[4000:], y[4000:]))  # 1.0
+print(tm)
+```
+
+```
+class 0
+   +2  ¬x0 ∧ ¬x1
+   +2  x0 ∧ x1
+   -2  x0 ∧ ¬x1
+   -2  ¬x0 ∧ x1
+class 1
+   +3  ¬x0 ∧ x1
+   +1  x0 ∧ ¬x1
+   -3  ¬x0 ∧ ¬x1
+   -1  x0 ∧ x1
+```
+
+It found XOR, ignored the ten distracting bits, and can tell you so.
+
+## API
+
+| | |
+|---|---|
+| `TsetlinMachine(clauses=20, T=15, s=3.9, states=100, seed=None)` | `clauses` per class (half vote for, half against), the vote target `T`, the specificity `s`, the states per action |
+| `fit(X, y, epochs=10)` | learn from bits `X` (samples × features, 0/1) and labels `y` of any kind |
+| `predict(X)` | the class with the most votes |
+| `votes(X)` | every class's vote total, samples × classes |
+| `score(X, y)` | accuracy |
+| `rules(label, names=None)` | a class's rules and their votes, optionally with your feature names |
+| `print(tm)` | every rule the machine learned |
+
+## License
+
+MIT

tsetly-0.0.1/README.md

@@ -0,0 +1,73 @@
+# tsetly
+
+A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read.
+
+```
+      forget ◀────────────────┼────────────────▶ remember
+             1   2   3  …  N  │  N+1  …  2N
+```
+
+A Tsetlin Machine learns AND-rules over bits, like `x0 ∧ ¬x1`. Every rule is a
+team of Tsetlin automata, one per bit and one per negated bit. Each automaton
+walks along its states as the data rewards or penalises it, and once it crosses
+the middle, its bit joins the rule. Rules vote for or against each class, and
+the class with the most votes wins. That is the whole machine
+([Granmo, 2018](https://arxiv.org/abs/1804.01508)).
+
+## Install
+
+```
+pip install tsetly
+```
+
+## Learn XOR through noise
+
+Twelve random bits, of which only the first two matter, and a fifth of the
+training labels flipped:
+
+```python
+import numpy as np
+from tsetly import TsetlinMachine
+
+rng = np.random.default_rng(0)
+X = rng.integers(0, 2, size=(5000, 12))
+y = X[:, 0] ^ X[:, 1]
+noisy = np.where(rng.random(5000) < 0.2, 1 - y, y)
+
+tm = TsetlinMachine(clauses=8, T=15, s=3.9, seed=1)
+tm.fit(X[:4000], noisy[:4000], epochs=20)
+
+print(tm.score(X[4000:], y[4000:]))  # 1.0
+print(tm)
+```
+
+```
+class 0
+   +2  ¬x0 ∧ ¬x1
+   +2  x0 ∧ x1
+   -2  x0 ∧ ¬x1
+   -2  ¬x0 ∧ x1
+class 1
+   +3  ¬x0 ∧ x1
+   +1  x0 ∧ ¬x1
+   -3  ¬x0 ∧ ¬x1
+   -1  x0 ∧ x1
+```
+
+It found XOR, ignored the ten distracting bits, and can tell you so.
+
+## API
+
+| | |
+|---|---|
+| `TsetlinMachine(clauses=20, T=15, s=3.9, states=100, seed=None)` | `clauses` per class (half vote for, half against), the vote target `T`, the specificity `s`, the states per action |
+| `fit(X, y, epochs=10)` | learn from bits `X` (samples × features, 0/1) and labels `y` of any kind |
+| `predict(X)` | the class with the most votes |
+| `votes(X)` | every class's vote total, samples × classes |
+| `score(X, y)` | accuracy |
+| `rules(label, names=None)` | a class's rules and their votes, optionally with your feature names |
+| `print(tm)` | every rule the machine learned |
+
+## License
+
+MIT

tsetly-0.0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tsetly"
+version = "0.0.1"
+description = "A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.21"]
+keywords = ["tsetlin machine", "interpretable machine learning", "propositional logic", "learning automata"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]

tsetly-0.0.1/src/tsetly/__init__.py

@@ -0,0 +1,220 @@
+"""A tiny Tsetlin Machine in NumPy.
+
+A Tsetlin Machine learns rules you can read: AND-clauses over input bits and
+their negations, such as ``x0 ∧ ¬x1``. Each clause is a team of Tsetlin
+automata, one per literal, and each automaton decides whether its literal
+belongs in the clause. Clauses vote for or against each class, and the class
+with the most votes wins. This is the vanilla multiclass Tsetlin Machine of
+Granmo (2018), https://arxiv.org/abs/1804.01508.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any, Sequence
+
+import numpy as np
+
+__all__ = ["TsetlinMachine"]
+__version__ = "0.0.1"
+
+
+class TsetlinMachine:
+    """A multiclass Tsetlin Machine.
+
+    Parameters
+    ----------
+    clauses : int
+        Clauses per class, an even number: half vote for the class, half against it.
+    T : int
+        The vote total each class aims for. Larger values let more clauses
+        learn each pattern.
+    s : float
+        Specificity, above 1. Larger values learn longer, more specific rules.
+    states : int
+        States per action. An automaton includes its literal once its state
+        is above ``states``.
+    seed : int, optional
+        Seed for reproducible training.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from tsetly import TsetlinMachine
+    >>> X = np.array([[0, 0], [0, 1], [1, 0], [1, 1]] * 25)
+    >>> y = X[:, 0] ^ X[:, 1]
+    >>> tm = TsetlinMachine(clauses=4, T=3, s=3.0, seed=0).fit(X, y, epochs=10)
+    >>> tm.score(X, y)
+    1.0
+    """
+
+    def __init__(
+        self, clauses: int = 20, T: int = 15, s: float = 3.9, states: int = 100, seed: int | None = None
+    ) -> None:
+        if clauses < 2 or clauses % 2:
+            raise ValueError(f"clauses must be an even number of at least 2, got {clauses}")
+        if T < 1:
+            raise ValueError(f"T must be at least 1, got {T}")
+        if s <= 1:
+            raise ValueError(f"s must be above 1, got {s}")
+        if states < 1:
+            raise ValueError(f"states must be at least 1, got {states}")
+        self.clauses = clauses
+        self.T = T
+        self.s = s
+        self.states = states
+        self.seed = seed
+        self.classes_: np.ndarray | None = None
+        self.automata_: np.ndarray | None = None  # classes × clauses × literals, states 1 … 2·states
+        self._polarity = np.where(np.arange(clauses) % 2 == 0, 1, -1)  # even clauses vote for, odd against
+
+    def fit(self, X: Any, y: Any, epochs: int = 10) -> TsetlinMachine:
+        """Learn from scratch.
+
+        Parameters
+        ----------
+        X : array_like
+            Samples × features of bits (0/1 or False/True).
+        y : array_like
+            One label per sample, of any kind numpy can sort.
+        epochs : int
+            Passes over the data, each in a fresh random order.
+
+        Returns
+        -------
+        TsetlinMachine
+            The machine itself, trained.
+        """
+        X = _bits(X)
+        y = np.asarray(y)
+        if y.shape != (len(X),):
+            raise ValueError(f"y must hold one label per sample ({len(X)}), got shape {y.shape}")
+        self.classes_, targets = np.unique(y, return_inverse=True)
+        if len(self.classes_) < 2:
+            raise ValueError("y must hold at least two classes")
+        # Every automaton starts on the fence: one step short of including its literal.
+        shape = (len(self.classes_), self.clauses, 2 * X.shape[1])
+        self.automata_ = np.full(shape, self.states, dtype=np.int32)
+        rng = np.random.default_rng(self.seed)
+        for _ in range(epochs):
+            for i in rng.permutation(len(X)):
+                self._learn(X[i], int(targets[i]), rng)
+        return self
+
+    def votes(self, X: Any) -> np.ndarray:
+        """Each class's vote total for each sample, samples × classes."""
+        X = self._check(X)
+        literals = np.hstack([X, ~X])
+        include = self.automata_ > self.states
+        classes, clauses, width = include.shape
+        flat = include.reshape(-1, width).astype(np.int32)
+        misses = flat @ (~literals).T.astype(np.int32)  # included literals that are 0, per clause and sample
+        fires = (misses == 0) & flat.any(axis=1, keepdims=True)  # empty clauses stay silent when predicting
+        return np.einsum("cjn,j->nc", fires.reshape(classes, clauses, -1).astype(np.int32), self._polarity)
+
+    def predict(self, X: Any) -> np.ndarray:
+        """The class with the most votes, for each sample."""
+        return self.classes_[np.argmax(self.votes(X), axis=1)]
+
+    def score(self, X: Any, y: Any) -> float:
+        """The fraction of samples predicted correctly."""
+        return float(np.mean(self.predict(X) == np.asarray(y)))
+
+    def rules(self, label: Any, names: Sequence[str] | None = None) -> list[tuple[str, int]]:
+        """The rules one class learned, with their votes.
+
+        Clauses that learned the same rule are merged, so ``("x0 ∧ ¬x1", 3)``
+        means three clauses vote for the class whenever ``x0 ∧ ¬x1`` holds.
+        Negative votes are against it. Rules that never fire are left out.
+
+        Parameters
+        ----------
+        label
+            A class seen in training.
+        names : sequence of str, optional
+            One name per feature; ``x0``, ``x1``, … by default.
+
+        Returns
+        -------
+        list of (str, int)
+            Rules and their votes: those for the class, then those against it,
+            the strongest first in each.
+        """
+        self._check_fitted()
+        found = np.flatnonzero(self.classes_ == label)
+        if not len(found):
+            raise ValueError(f"no class {label!r}; the classes are {list(self.classes_)}")
+        features = self.automata_.shape[2] // 2
+        names = list(names) if names is not None else [f"x{i}" for i in range(features)]
+        if len(names) != features:
+            raise ValueError(f"names must hold one name per feature ({features}), got {len(names)}")
+        literals = names + [f"¬{name}" for name in names]
+        tally: Counter[str] = Counter()
+        for clause, polarity in zip(self.automata_[found[0]] > self.states, self._polarity):
+            if not clause.any() or (clause[:features] & clause[features:]).any():
+                continue  # empty, or a contradiction such as x0 ∧ ¬x0
+            chosen = sorted(np.flatnonzero(clause), key=lambda k: (k % features, k))
+            tally[" ∧ ".join(literals[k] for k in chosen)] += int(polarity)
+        ordered = sorted(tally.items(), key=lambda item: (item[1] < 0, -abs(item[1])))
+        return [(rule, votes) for rule, votes in ordered if votes]
+
+    def __repr__(self) -> str:
+        return f"TsetlinMachine(clauses={self.clauses}, T={self.T}, s={self.s}, states={self.states}, seed={self.seed})"
+
+    def __str__(self) -> str:
+        if self.automata_ is None:
+            return f"{self!r}, not trained yet"
+        lines = []
+        for label in self.classes_:
+            lines.append(f"class {label}")
+            lines += [f"  {votes:+3d}  {rule}" for rule, votes in self.rules(label)]
+        return "\n".join(lines)
+
+    def _learn(self, x: np.ndarray, target: int, rng: np.random.Generator) -> None:
+        literals = np.concatenate([x, ~x])
+        other = int(rng.integers(len(self.classes_) - 1))
+        other += other >= target  # a random class other than the target
+        self._feedback(target, literals, +1, rng)
+        self._feedback(other, literals, -1, rng)
+
+    def _feedback(self, label: int, literals: np.ndarray, sign: int, rng: np.random.Generator) -> None:
+        """Nudge one class's clauses so its vote total moves toward ``sign · T``."""
+        automata = self.automata_[label]
+        include = automata > self.states
+        fires = ~np.any(include & ~literals, axis=1)  # empty clauses fire while learning
+        votes = np.clip(self._polarity @ fires, -self.T, self.T)
+        chosen = rng.random(self.clauses) < (self.T - sign * votes) / (2 * self.T)
+        type_i = (chosen & (self._polarity == sign))[:, None]
+        type_ii = (chosen & (self._polarity != sign))[:, None]
+        fired = fires[:, None]
+        remembered = fired & literals  # the 1-literals of firing clauses
+        rare = rng.random(automata.shape) < 1 / self.s  # true with probability 1/s
+        # Type I: firing clauses grow toward the 1-literals they saw; everything else slowly fades.
+        automata += type_i & remembered & ~rare
+        automata -= type_i & ~remembered & rare
+        # Type II: a clause that fired for the wrong answer picks up a 0-literal, so it stops firing.
+        automata += type_ii & fired & ~literals & ~include
+        np.clip(automata, 1, 2 * self.states, out=automata)
+
+    def _check_fitted(self) -> None:
+        if self.automata_ is None:
+            raise RuntimeError("this TsetlinMachine is not trained yet: call fit first")
+
+    def _check(self, X: Any) -> np.ndarray:
+        self._check_fitted()
+        X = _bits(X)
+        features = self.automata_.shape[2] // 2
+        if X.shape[1] != features:
+            raise ValueError(f"X has {X.shape[1]} features, but the machine was trained on {features}")
+        return X
+
+
+def _bits(X: Any) -> np.ndarray:
+    X = np.asarray(X)
+    if X.ndim != 2:
+        raise ValueError(f"X must be 2-D, samples × features, got shape {X.shape}")
+    if X.dtype != bool:
+        if not np.isin(X, (0, 1)).all():
+            raise ValueError("X must hold bits: 0/1 or False/True")
+        X = X.astype(bool)
+    return X

tsetly-0.0.1/tests/test_tsetly.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pytest
+
+from tsetly import TsetlinMachine
+
+
+def noisy_xor(noise=0.2, seed=0):
+    rng = np.random.default_rng(seed)
+    X = rng.integers(0, 2, size=(5000, 12))
+    y = X[:, 0] ^ X[:, 1]
+    return X, y, np.where(rng.random(len(y)) < noise, 1 - y, y)
+
+
+def test_learns_xor_through_noise():
+    X, y, noisy = noisy_xor()
+    tm = TsetlinMachine(clauses=8, T=15, s=3.9, seed=1).fit(X[:4000], noisy[:4000], epochs=20)
+    assert tm.score(X[4000:], y[4000:]) == 1.0
+    assert {rule for rule, votes in tm.rules(1) if votes > 0} == {"x0 ∧ ¬x1", "¬x0 ∧ x1"}
+
+
+def test_same_seed_same_machine():
+    X, _, noisy = noisy_xor()
+    first = TsetlinMachine(seed=7).fit(X[:500], noisy[:500], epochs=2)
+    second = TsetlinMachine(seed=7).fit(X[:500], noisy[:500], epochs=2)
+    assert np.array_equal(first.automata_, second.automata_)
+
+
+def test_any_labels_and_feature_names():
+    X = np.array([[0, 0], [0, 1], [1, 0], [1, 1]] * 25, dtype=bool)
+    y = np.where(X[:, 0] & X[:, 1], "both", "not both")
+    tm = TsetlinMachine(clauses=4, T=3, s=3.0, seed=0).fit(X, y, epochs=10)
+    assert list(tm.predict(X[:4])) == ["not both", "not both", "not both", "both"]
+    assert tm.votes(X).shape == (100, 2)
+    assert ("rain ∧ wind", 2) in tm.rules("both", names=["rain", "wind"])
+    assert str(tm).startswith("class both")
+
+
+def test_friendly_errors():
+    with pytest.raises(ValueError, match="even"):
+        TsetlinMachine(clauses=3)
+    with pytest.raises(RuntimeError, match="not trained"):
+        TsetlinMachine().predict([[0, 1]])
+    with pytest.raises(ValueError, match="bits"):
+        TsetlinMachine().fit([[0, 2]], [0])
+    with pytest.raises(ValueError, match="two classes"):
+        TsetlinMachine().fit([[0, 1], [1, 0]], [5, 5])
+    tm = TsetlinMachine(seed=0).fit([[0, 1], [1, 0]], [0, 1], epochs=1)
+    with pytest.raises(ValueError, match="features"):
+        tm.predict([[0, 1, 1]])
+    with pytest.raises(ValueError, match="no class"):
+        tm.rules(9)