uchi-python 0.1.0__py3-none-any.whl

uchi/hoeffding.py

@@ -0,0 +1,225 @@
+import math
+from typing import Any
+import random
+
+def norm_pdf(x: float, mu: float, sigma: float) -> float:
+    if sigma < 1e-6:
+        sigma = 1e-6
+    return (1.0 / (math.sqrt(2 * math.pi) * sigma)) * math.exp(-0.5 * ((x - mu) / sigma) ** 2)
+
+def norm_cdf(x: float, mu: float, sigma: float) -> float:
+    if sigma < 1e-6:
+        return 1.0 if x >= mu else 0.0
+    return 0.5 * (1 + math.erf((x - mu) / (sigma * math.sqrt(2))))
+
+class HoeffdingNode:
+    """
+    A node in the Hoeffding Online Decision Tree.
+    Tracks Gaussian statistics for Information Gain and Naive Bayes prediction.
+    """
+    def __init__(self, n_features: int, is_leaf: bool = True):
+        self.is_leaf = is_leaf
+        self.n_features = n_features
+        
+        # If leaf, track Gaussian statistics
+        self.n_obs = 0
+        self.class_counts = {}
+        # feature_idx -> class_label -> {'sum': sum_x, 'sq_sum': sum_x2}
+        self.feature_stats = {i: {} for i in range(n_features)}
+        
+        # If internal node, track split condition
+        self.split_feature = None
+        self.split_threshold = None
+        self.left = None
+        self.right = None
+
+    def observe(self, row: list, label: Any):
+        if not self.is_leaf:
+            val = float(row[self.split_feature])
+            if val <= self.split_threshold:
+                self.left.observe(row, label)
+            else:
+                self.right.observe(row, label)
+            return
+
+        self.n_obs += 1
+        self.class_counts[label] = self.class_counts.get(label, 0) + 1
+        
+        for f_idx, f_val in enumerate(row):
+            v = float(f_val)
+            if label not in self.feature_stats[f_idx]:
+                self.feature_stats[f_idx][label] = {'sum': 0.0, 'sq_sum': 0.0}
+            self.feature_stats[f_idx][label]['sum'] += v
+            self.feature_stats[f_idx][label]['sq_sum'] += v * v
+
+    def predict(self, row: list) -> dict:
+        if not self.is_leaf:
+            val = float(row[self.split_feature])
+            if val <= self.split_threshold:
+                return self.left.predict(row)
+            else:
+                return self.right.predict(row)
+                
+        if not self.class_counts:
+            return {}
+            
+        # Gaussian Naive Bayes Prediction
+        log_probs = {}
+        for c, count in self.class_counts.items():
+            # Log Prior P(c)
+            log_p = math.log(count / self.n_obs)
+            
+            # Log Likelihoods
+            for f_idx, f_val in enumerate(row):
+                v = float(f_val)
+                stats = self.feature_stats[f_idx].get(c, {'sum': 0.0, 'sq_sum': 0.0})
+                n_c = self.class_counts.get(c, 0)
+                
+                if n_c > 1:
+                    mu = stats['sum'] / n_c
+                    var = (stats['sq_sum'] - (stats['sum'] ** 2) / n_c) / (n_c - 1)
+                    sigma = math.sqrt(max(var, 1e-6))
+                else:
+                    mu = v
+                    sigma = 1e-6
+                    
+                pdf = norm_pdf(v, mu, sigma)
+                log_p += math.log(max(pdf, 1e-12))
+            
+            log_probs[c] = log_p
+            
+        # Convert log probs to normalized probabilities
+        max_lp = max(log_probs.values())
+        probs = {c: math.exp(lp - max_lp) for c, lp in log_probs.items()}
+        total = sum(probs.values())
+        return {c: p / total for c, p in probs.items()}
+
+class HoeffdingPredictor:
+    """
+    Online Decision Tree using Hoeffding Bounds.
+    Uses Gaussian Naive Bayes at the leaves and Continuous Threshold Splitting.
+    """
+    def __init__(
+        self,
+        n_features: int,
+        delta: float = 1e-1,
+        grace_period: int = 10,
+        tie_threshold: float = 0.05
+    ):
+        self.n_features = n_features
+        self.delta = delta
+        self.grace_period = grace_period
+        self.tie_threshold = tie_threshold
+        self.root = HoeffdingNode(n_features)
+        
+    def _entropy(self, counts: dict) -> float:
+        total = sum(counts.values())
+        if total == 0:
+            return 0.0
+        ent = 0.0
+        for c in counts.values():
+            p = c / total
+            if p > 0:
+                ent -= p * math.log2(p)
+        return ent
+
+    def _evaluate_threshold(self, leaf: HoeffdingNode, f_idx: int, threshold: float) -> float:
+        left_counts = {}
+        right_counts = {}
+        
+        for c, count in leaf.class_counts.items():
+            stats = leaf.feature_stats[f_idx].get(c, {'sum': 0.0, 'sq_sum': 0.0})
+            if count > 1:
+                mu = stats['sum'] / count
+                var = (stats['sq_sum'] - (stats['sum'] ** 2) / count) / (count - 1)
+                sigma = math.sqrt(max(var, 1e-6))
+            else:
+                mu = stats['sum'] / count if count > 0 else 0
+                sigma = 1e-6
+                
+            p_left = norm_cdf(threshold, mu, sigma)
+            left_counts[c] = count * p_left
+            right_counts[c] = count * (1.0 - p_left)
+            
+        n_left = sum(left_counts.values())
+        n_right = sum(right_counts.values())
+        total = n_left + n_right
+        
+        if total == 0:
+            return 0.0
+            
+        e_left = self._entropy(left_counts)
+        e_right = self._entropy(right_counts)
+        
+        return (n_left / total) * e_left + (n_right / total) * e_right
+
+    def _info_gain(self, leaf: HoeffdingNode, f_idx: int) -> tuple[float, float]:
+        base_entropy = self._entropy(leaf.class_counts)
+        
+        # Collect candidate thresholds (class means for this feature)
+        candidates = []
+        for c, count in leaf.class_counts.items():
+            stats = leaf.feature_stats[f_idx].get(c)
+            if stats and count > 0:
+                candidates.append(stats['sum'] / count)
+                
+        if not candidates:
+            return 0.0, 0.0
+            
+        best_gain = -1.0
+        best_thresh = 0.0
+        
+        for thresh in set(candidates):
+            exp_entropy = self._evaluate_threshold(leaf, f_idx, thresh)
+            gain = base_entropy - exp_entropy
+            if gain > best_gain:
+                best_gain = gain
+                best_thresh = thresh
+                
+        return best_gain, best_thresh
+
+    def _attempt_split(self, leaf: HoeffdingNode) -> None:
+        if leaf.n_obs < self.grace_period:
+            return
+            
+        # Calculate Information Gain for all features
+        gains = []
+        for i in range(self.n_features):
+            gain, thresh = self._info_gain(leaf, i)
+            gains.append((gain, thresh, i))
+            
+        gains.sort(reverse=True, key=lambda x: x[0])
+        best_gain, best_thresh, best_idx = gains[0]
+        second_gain = gains[1][0] if len(gains) > 1 else 0.0
+        
+        # Hoeffding Bound epsilon
+        R = math.log2(len(leaf.class_counts)) if len(leaf.class_counts) > 0 else 1.0
+        epsilon = math.sqrt((R**2 * math.log(1 / self.delta)) / (2 * leaf.n_obs))
+        
+        if (best_gain - second_gain > epsilon) or (epsilon < self.tie_threshold and best_gain > 0):
+            # Split!
+            leaf.is_leaf = False
+            leaf.split_feature = best_idx
+            leaf.split_threshold = best_thresh
+            
+            leaf.left = HoeffdingNode(self.n_features)
+            leaf.right = HoeffdingNode(self.n_features)
+            
+            # Free memory
+            leaf.feature_stats = None
+            leaf.class_counts = None
+
+    def _traverse_and_split(self, node: HoeffdingNode):
+        if node.is_leaf:
+            if node.n_obs % self.grace_period == 0:
+                self._attempt_split(node)
+        else:
+            self._traverse_and_split(node.left)
+            self._traverse_and_split(node.right)
+
+    def partial_fit(self, row: list, label: Any) -> None:
+        self.root.observe(row, label)
+        self._traverse_and_split(self.root)
+        
+    def predict_proba(self, row: list) -> dict:
+        return self.root.predict(row)

uchi/long_term_store.py

@@ -0,0 +1,345 @@
+"""
+LongTermStore
+=============
+Persistent cross-sequence memory for the Universal Sequence Predictor.
+
+Solves
+------
+  Problem 3 — Cold start         : warm prior available before token 1
+  Problem 5 — Cross-seq memory   : patterns persist and strengthen across runs
+  Problem 8 — Zero mass fallback : richer second layer before unigram floor
+
+Consequence reasoning
+---------------------
+Stores P(t+n | ctx) for configurable n alongside the standard P(t+1 | ctx).
+After replay, you can query what tends to happen 2 or 3 steps downstream
+from any context the store has seen — useful for planning and lookahead.
+
+Observability
+-------------
+Every replay call returns a stats dict and appends to run_history().
+Watch accuracy climb across runs as the store warms up.
+
+Persistence
+-----------
+Serialised with pickle (handles any token type) then gzip-compressed.
+Portable: a single .lts file; load it anywhere with LongTermStore(path=...).
+"""
+
+import gzip
+import os
+import pickle
+from collections import defaultdict
+from typing import Any, Optional
+
+
+class LongTermStore:
+    """
+    Persistent, slowly-updating trie that accumulates evidence across sequences.
+
+    Parameters
+    ----------
+    path : str | None
+        File path for persistence.  If the file exists it is loaded
+        automatically on construction.  Saved after every replay().
+    lr : float
+        Learning rate for replay updates (default 0.01 — much slower than
+        the short-term predictor's 0.08).
+    replay_min_cred_ratio : float
+        Only replay nodes whose credibility is at least this fraction of
+        cred_max.  Filters out low-confidence short-term patterns.
+    consequence_depth : int
+        How many steps ahead to store consequence distributions.
+        0 = disabled; 2 = store P(t+2|ctx) and P(t+3|ctx).
+    """
+
+    def __init__(
+        self,
+        path: Optional[str] = None,
+        lr: float = 0.01,
+        replay_min_cred_ratio: float = 0.6,
+        consequence_depth: int = 2,
+    ):
+        self.path = path
+        self.lr = lr
+        self.replay_min_cred_ratio = replay_min_cred_ratio
+        self.consequence_depth = consequence_depth
+
+        # context_tuple → {token: accumulated_weight}
+        self._dist: dict[tuple, dict] = {}
+        # context_tuple → {offset: {token: weight}}
+        self._conseq: dict[tuple, dict] = {}
+        # running unigram across all replayed tokens
+        self._unigram: dict[Any, float] = {}
+        self._unigram_total: float = 0.0
+
+        self._n_updates: int = 0
+        self._run_history: list[dict] = []
+
+        if path and os.path.exists(path):
+            self.load(path)
+
+    # ── prediction ────────────────────────────────────────────────────────────
+
+    def predict(self, context: tuple) -> dict:
+        """Normalised distribution for this exact context, or {} if unseen."""
+        raw = self._dist.get(context)
+        if not raw:
+            return {}
+        total = sum(raw.values()) or 1.0
+        return {k: v / total for k, v in raw.items()}
+
+    def predict_consequence(self, context: tuple, offset: int = 2) -> dict:
+        """
+        Distribution over what tends to happen `offset` steps after context.
+        Returns {} if the store has no consequence data for this context/offset.
+        """
+        node = self._conseq.get(context)
+        if not node:
+            return {}
+        raw = node.get(offset, {})
+        if not raw:
+            return {}
+        total = sum(raw.values()) or 1.0
+        return {k: v / total for k, v in raw.items()}
+
+    def unigram(self) -> dict:
+        """Normalised unigram distribution across all replayed tokens."""
+        if not self._unigram_total:
+            return {}
+        return {k: v / self._unigram_total for k, v in self._unigram.items()}
+
+    # ── blending ──────────────────────────────────────────────────────────────
+
+    def blend(self, p_short: dict, context: tuple, vocab: set) -> dict:
+        """
+        Blend short-term distribution with long-term prior.
+
+        λ_short → 1 when the short-term is confident (high max prob vs uniform).
+        λ_short → 0 at cold start (short-term near-uniform).
+        Falls through to unigram when the long-term store has no match either.
+        """
+        p_long = self.predict(context)
+
+        # Estimate short-term confidence: how far above uniform is its peak?
+        V = len(vocab) if vocab else 1
+        uniform = 1.0 / V
+        max_short = max(p_short.values()) if p_short else 0.0
+        # Normalise to [0, 1]: 0 = completely random, 1 = completely certain
+        lambda_s = min(1.0, max(0.0, (max_short - uniform) / max(1.0 - uniform, 1e-9)))
+
+        if not p_long:
+            # Fall back to unigram if long-term has nothing
+            p_long = self.unigram()
+        if not p_long:
+            return p_short  # nothing to blend with
+
+        lambda_l = 1.0 - lambda_s
+        all_keys = set(p_short) | set(p_long)
+        blended = {
+            k: lambda_s * p_short.get(k, 0.0) + lambda_l * p_long.get(k, 0.0)
+            for k in all_keys
+        }
+        total = sum(blended.values()) or 1.0
+        return {k: v / total for k, v in blended.items()}
+
+    # ── replay ────────────────────────────────────────────────────────────────
+
+    def replay(self, short_predictor, sequence: list) -> dict:
+        """
+        Incorporate a completed sequence into the long-term store.
+
+        Walks the short-term predictor's trie.  For each context node whose
+        credibility exceeds replay_min_cred_ratio × cred_max, the observed
+        token is replayed into the long-term store with weight proportional
+        to how confident the short-term predictor was.
+
+        Also records consequence chains (what happened offset steps later).
+
+        Returns a stats dict and appends it to run_history().
+
+        Parameters
+        ----------
+        short_predictor : UniversalPredictor
+            The just-completed short-term predictor (before reset).
+        sequence : list
+            The complete token sequence that was just processed.
+        """
+        k = short_predictor.k
+        cred_max = short_predictor._cred_max_base
+        threshold = self.replay_min_cred_ratio * cred_max
+
+        n_replayed = 0
+        n_correct = 0
+
+        for i in range(1, len(sequence)):
+            actual = sequence[i]
+
+            # Update unigram
+            self._unigram[actual] = self._unigram.get(actual, 0.0) + 1.0
+            self._unigram_total += 1.0
+
+            for d in range(1, min(k, i) + 1):
+                ctx = tuple(sequence[i - d:i])
+                node = short_predictor._walk(ctx)
+                if node is None or not node.succ_cred:
+                    continue
+                if node.node_cred < threshold:
+                    continue
+
+                # Weight = lr × how confident the node was (normalised)
+                cred_ratio = min(1.0, node.node_cred / cred_max)
+                weight = self.lr * cred_ratio
+
+                # Update next-step distribution
+                if ctx not in self._dist:
+                    self._dist[ctx] = {}
+                self._dist[ctx][actual] = self._dist[ctx].get(actual, 0.0) + weight
+                n_replayed += 1
+
+                # Track whether this node's top prediction was correct
+                top = max(node.succ_cred, key=node.succ_cred.get)
+                if top == actual:
+                    n_correct += 1
+
+                # Consequence chains
+                if self.consequence_depth > 0:
+                    if ctx not in self._conseq:
+                        self._conseq[ctx] = {}
+                    for offset in range(2, self.consequence_depth + 2):
+                        future_idx = i + offset
+                        if future_idx >= len(sequence):
+                            break
+                        future = sequence[future_idx]
+                        decay = 0.7 ** (offset - 1)
+                        if offset not in self._conseq[ctx]:
+                            self._conseq[ctx][offset] = {}
+                        self._conseq[ctx][offset][future] = (
+                            self._conseq[ctx][offset].get(future, 0.0) + weight * decay
+                        )
+
+        self._n_updates += 1
+        acc = n_correct / max(n_replayed, 1)
+        stats = {
+            'run': self._n_updates,
+            'sequence_length': len(sequence),
+            'n_replayed': n_replayed,
+            'replay_accuracy': round(acc, 4),
+            'total_contexts': len(self._dist),
+            'unigram_vocab': len(self._unigram),
+        }
+        self._run_history.append(stats)
+
+        if self.path:
+            self.save()
+
+        return stats
+
+    # ── observability ─────────────────────────────────────────────────────────
+
+    def run_history(self) -> list[dict]:
+        """Per-run stats showing how the store has learned over time."""
+        return list(self._run_history)
+
+    def stats(self) -> dict:
+        return {
+            'total_contexts': len(self._dist),
+            'total_runs': self._n_updates,
+            'unigram_vocab': len(self._unigram),
+            'consequence_contexts': len(self._conseq),
+        }
+
+    def learning_curve(self) -> list[float]:
+        """Per-run replay accuracy as a plottable list. Watch it climb."""
+        return [r['replay_accuracy'] for r in self._run_history]
+
+    def top_consequences(self, context: tuple, offset: int = 2, n: int = 5) -> list[tuple]:
+        """
+        Most likely downstream outcomes `offset` steps after context.
+
+        Returns list of (token, probability) sorted by probability descending.
+        Useful for planning and lookahead: "what tends to happen 2 steps
+        after seeing this context?"
+        """
+        dist = self.predict_consequence(context, offset)
+        if not dist:
+            return []
+        items = sorted(dist.items(), key=lambda x: x[1], reverse=True)
+        return items[:n]
+
+    def coverage_report(self, sequence: list, k: int) -> dict:
+        """
+        Detailed breakdown of which contexts in sequence the store has seen.
+
+        Returns
+        -------
+        dict with keys:
+          coverage : float (fraction of k-grams matched)
+          matched  : int   (number of k-grams with store data)
+          total    : int   (total k-grams in sequence)
+          novel    : list[tuple]  (first 10 unmatched contexts)
+        """
+        if len(sequence) < k + 1:
+            return {'coverage': 0.0, 'matched': 0, 'total': 0, 'novel': []}
+        matched = 0
+        total_kgrams = 0
+        novel = []
+        for i in range(k, len(sequence)):
+            ctx = tuple(sequence[i - k:i])
+            total_kgrams += 1
+            if ctx in self._dist:
+                matched += 1
+            elif len(novel) < 10:
+                novel.append(ctx)
+        return {
+            'coverage': matched / total_kgrams if total_kgrams > 0 else 0.0,
+            'matched': matched,
+            'total': total_kgrams,
+            'novel': novel,
+        }
+
+    def context_coverage(self, sequence: list, k: int) -> float:
+        """Fraction of k-grams in sequence that the store has seen."""
+        if len(sequence) < k + 1:
+            return 0.0
+        hits = sum(
+            1 for i in range(k, len(sequence))
+            if tuple(sequence[i - k:i]) in self._dist
+        )
+        return hits / (len(sequence) - k)
+
+    # ── persistence ───────────────────────────────────────────────────────────
+
+    def save(self, path: Optional[str] = None) -> None:
+        """Gzip-pickle the store to disk."""
+        p = path or self.path
+        if not p:
+            return
+        data = {
+            'dist': self._dist,
+            'conseq': self._conseq,
+            'unigram': self._unigram,
+            'unigram_total': self._unigram_total,
+            'n_updates': self._n_updates,
+            'run_history': self._run_history,
+            'lr': self.lr,
+            'replay_min_cred_ratio': self.replay_min_cred_ratio,
+            'consequence_depth': self.consequence_depth,
+        }
+        raw = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)
+        with open(p, 'wb') as f:
+            f.write(gzip.compress(raw, compresslevel=6))
+
+    def load(self, path: str) -> None:
+        """Load a previously saved store from disk."""
+        with open(path, 'rb') as f:
+            data = pickle.loads(gzip.decompress(f.read()))
+        self._dist = data['dist']
+        self._conseq = data.get('conseq', {})
+        self._unigram = data.get('unigram', {})
+        self._unigram_total = data.get('unigram_total', 0.0)
+        self._n_updates = data.get('n_updates', 0)
+        self._run_history = data.get('run_history', [])
+        self.lr = data.get('lr', self.lr)
+        self.replay_min_cred_ratio = data.get('replay_min_cred_ratio', self.replay_min_cred_ratio)
+        self.consequence_depth = data.get('consequence_depth', self.consequence_depth)