uchi-python 0.1.0__py3-none-any.whl

uchi/__init__.py

@@ -0,0 +1,57 @@
+"""
+uchi
+===============
+Online credibility-weighted sequence predictor for tabular, time series,
+and generative machine learning tasks.
+
+Quick start
+-----------
+    from uchi import TabularPredictor, TabularRegressor
+    from uchi import MultivariateTSPredictor, TimeSeriesClassifier
+    from uchi import AnomalyDetector
+    from uchi import UniversalPredictor, PredictorForest
+
+All classes are sklearn-compatible (Pipeline, GridSearchCV, cross_val_score).
+TabularPredictor / TabularRegressor / TimeSeriesClassifier all support
+partial_fit() for online / incremental learning.
+"""
+
+from .predictor  import UniversalPredictor
+from .forest     import PredictorForest
+from .discretize import FeatureDiscretizer, LabelEncoder
+from .tabular    import TabularPredictor, TabularRegressor
+from .timeseries import MultivariateTSPredictor, TimeSeriesClassifier, AnomalyDetector
+from .generative import SequenceGenerator, TabularGenerator, TimeSeriesGenerator
+
+# Generative services fixes
+from .long_term_store   import LongTermStore
+from .dual_predictor    import DualPredictor
+from .online_tokenizer  import OnlineTokenizer
+from .node_compressor   import NodeCompressor
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core engine
+    "UniversalPredictor",
+    "PredictorForest",
+    # Feature engineering
+    "FeatureDiscretizer",
+    "LabelEncoder",
+    # Tabular ML
+    "TabularPredictor",
+    "TabularRegressor",
+    # Time series
+    "MultivariateTSPredictor",
+    "TimeSeriesClassifier",
+    "AnomalyDetector",
+    # Generative
+    "SequenceGenerator",
+    "TabularGenerator",
+    "TimeSeriesGenerator",
+    # Generative services fixes
+    "LongTermStore",
+    "DualPredictor",
+    "OnlineTokenizer",
+    "NodeCompressor",
+]

uchi/discretize.py

@@ -0,0 +1,307 @@
+"""
+discretize.py
+=============
+Feature discretization for the Universal Sequence Predictor.
+
+Converts continuous and categorical features into discrete symbol tokens
+compatible with UniversalPredictor / PredictorForest.
+
+  FeatureDiscretizer   — fits bins per-column, transforms rows to token lists
+  LabelEncoder         — encodes classification targets to/from integers
+"""
+
+import math
+from typing import Any
+
+
+# ── sentinel for missing / unseen values ─────────────────────────────────────
+
+MISSING = object()      # unique identity; cannot equal any real feature value
+MISSING_STR = '__MISSING__'
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# FeatureDiscretizer
+# ══════════════════════════════════════════════════════════════════════════════
+
+class FeatureDiscretizer:
+    """
+    Transforms a feature matrix into sequences of (feature_index, bin) tokens.
+
+    Column types detected automatically:
+      • numeric  → equal-frequency (quantile) bins, labelled 0..n_bins-1
+      • other    → ordinal integer encoding of unique values seen at fit time
+
+    Missing values (None, NaN, empty string) map to MISSING_STR so they form
+    their own trie branch rather than crashing or biasing bin counts.
+
+    Parameters
+    ----------
+    n_bins : int
+        Number of quantile bins for numeric columns.
+    feature_names : list[str] | None
+        Optional column names, used only for repr/debugging.
+
+    Usage
+    -----
+    disc = FeatureDiscretizer(n_bins=10)
+    token_rows = disc.fit_transform(X_train)   # list of [(col, bin), ...]
+    test_rows  = disc.transform(X_test)
+    """
+
+    def __init__(self, n_bins: int = 10, feature_names: list | None = None):
+        self.n_bins        = n_bins
+        self.feature_names = feature_names
+        self._n_features:  int  = 0
+        self._types:       list = []   # 'numeric' | 'categorical' per column
+        self._edges:       dict = {}   # col → sorted list of quantile cut-points
+        self._cat_maps:    dict = {}   # col → {value: int}
+        self._bin_centers: dict = {}   # col → list of float centers (numeric only)
+        
+        # Reservoir sampling state for dynamic online splitting
+        self._reservoirs:  dict = {}   # col -> list of sampled float values
+        self._reservoir_max: int = 2000
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def fit(self, X) -> 'FeatureDiscretizer':
+        X = _to_rows(X)
+        if not X:
+            return self
+        self._n_features = len(X[0])
+        self._types = []
+        self._edges = {}
+        self._cat_maps = {}
+        self._bin_centers = {}
+
+        for j in range(self._n_features):
+            col = [row[j] for row in X]
+            if _is_numeric_col(col):
+                self._types.append('numeric')
+                self._reservoirs[j] = [float(v) for v in col if not _is_missing(v) and not (isinstance(v, float) and math.isnan(v))]
+                edges, centers = _quantile_edges(col, self.n_bins)
+                self._edges[j]       = edges
+                self._bin_centers[j] = centers
+            else:
+                self._types.append('categorical')
+                unique = sorted(
+                    {_safe_str(v) for v in col if not _is_missing(v)})
+                self._cat_maps[j] = {v: i for i, v in enumerate(unique)}
+        self._total_seen = len(X)
+        return self
+
+    def partial_fit(self, X) -> 'FeatureDiscretizer':
+        """
+        Online dynamic splitting: Update the reservoir sample of numeric columns
+        and re-calculate quantile bins if enough new data has arrived.
+        """
+        if self._n_features == 0:
+            return self.fit(X)
+            
+        rows = _to_rows(X)
+        if not rows:
+            return self
+            
+        import random
+        for row in rows:
+            self._total_seen += 1
+            for j in range(self._n_features):
+                v = row[j]
+                if self._types[j] == 'numeric':
+                    if _is_missing(v):
+                        continue
+                    v = float(v)
+                    # Reservoir sampling
+                    if len(self._reservoirs[j]) < self._reservoir_max:
+                        self._reservoirs[j].append(v)
+                    else:
+                        idx = random.randint(0, self._total_seen - 1)
+                        if idx < self._reservoir_max:
+                            self._reservoirs[j][idx] = v
+                else:
+                    # Categorical: dynamically add unseen categories
+                    if not _is_missing(v):
+                        s = _safe_str(v)
+                        if s not in self._cat_maps[j]:
+                            self._cat_maps[j][s] = len(self._cat_maps[j])
+                            
+        # Re-compute bins periodically (e.g., every time we process a batch)
+        for j in range(self._n_features):
+            if self._types[j] == 'numeric' and self._reservoirs[j]:
+                edges, centers = _quantile_edges(self._reservoirs[j], self.n_bins)
+                self._edges[j] = edges
+                self._bin_centers[j] = centers
+                
+        return self
+
+    def transform(self, X) -> list:
+        """Return list-of-lists of (col_idx, bin_or_code) tokens."""
+        rows = _to_rows(X)
+        return [self._encode_row(row) for row in rows]
+
+    def fit_transform(self, X) -> list:
+        return self.fit(X).transform(X)
+
+    def bin_center(self, col: int, bin_idx: int) -> float:
+        """Inverse of numeric binning: approximate value at bin centre."""
+        centers = self._bin_centers.get(col, [])
+        if not centers:
+            return 0.0
+        return centers[min(bin_idx, len(centers) - 1)]
+
+    @property
+    def n_features(self) -> int:
+        return self._n_features
+
+    # ── internal ──────────────────────────────────────────────────────────────
+
+    def _encode_row(self, row: list) -> list:
+        tokens = []
+        for j, v in enumerate(row):
+            tokens.append((j, self._encode_val(j, v)))
+        return tokens
+
+    def _encode_val(self, j: int, v) -> Any:
+        if _is_missing(v):
+            return MISSING_STR
+        if self._types[j] == 'numeric':
+            return _bin_search(float(v), self._edges[j])
+        else:
+            return self._cat_maps[j].get(_safe_str(v), MISSING_STR)
+
+    def __repr__(self) -> str:
+        return (f'FeatureDiscretizer(n_bins={self.n_bins}, '
+                f'n_features={self._n_features})')
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# LabelEncoder
+# ══════════════════════════════════════════════════════════════════════════════
+
+class LabelEncoder:
+    """
+    Bi-directional map between raw class labels and integer codes.
+    New labels seen during partial_fit are assigned the next integer.
+    """
+
+    def __init__(self):
+        self._enc: dict = {}   # label → int
+        self._dec: dict = {}   # int   → label
+        self.classes_: list = []
+
+    def fit(self, y) -> 'LabelEncoder':
+        for label in y:
+            self._add(label)
+        return self
+
+    def partial_fit(self, y) -> 'LabelEncoder':
+        return self.fit(y)
+
+    def encode(self, label) -> int:
+        if label not in self._enc:
+            self._add(label)
+        return self._enc[label]
+
+    def decode(self, code: int):
+        return self._dec[code]
+
+    def __len__(self) -> int:
+        return len(self._enc)
+
+    def _add(self, label):
+        if label not in self._enc:
+            code = len(self._enc)
+            self._enc[label] = code
+            self._dec[code]  = label
+            self.classes_.append(label)
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Helpers
+# ══════════════════════════════════════════════════════════════════════════════
+
+def _to_rows(X) -> list:
+    """Accept numpy array, pandas DataFrame, or list-of-lists."""
+    try:
+        import numpy as np
+        if isinstance(X, np.ndarray):
+            return X.tolist()
+    except ImportError:
+        pass
+    try:
+        import pandas as pd
+        if isinstance(X, (pd.DataFrame, pd.Series)):
+            return X.values.tolist()
+    except ImportError:
+        pass
+    # Already a list; wrap scalars (1-D input → single-column matrix)
+    out = list(X)
+    if out and not isinstance(out[0], (list, tuple)):
+        out = [[v] for v in out]
+    return out
+
+
+def _is_missing(v) -> bool:
+    if v is None or v is MISSING:
+        return True
+    if isinstance(v, float) and math.isnan(v):
+        return True
+    if isinstance(v, str) and v.strip() == '':
+        return True
+    return False
+
+
+def _is_numeric_col(col: list) -> bool:
+    """True if any non-missing value is a float/int (non-bool)."""
+    for v in col:
+        if _is_missing(v):
+            continue
+        if isinstance(v, bool):
+            return False
+        if isinstance(v, (int, float)):
+            return True
+        return False
+    return False
+
+
+def _safe_str(v) -> str:
+    return str(v)
+
+
+def _quantile_edges(col: list, n_bins: int) -> tuple:
+    """
+    Compute (n_bins-1) quantile cut-points and n_bins bin centres.
+    Values beyond edges map to the first or last bin (clamped).
+    """
+    valid = sorted(float(v) for v in col if not _is_missing(v)
+                   and not (isinstance(v, float) and math.isnan(v)))
+    if not valid:
+        return [], [0.0]
+
+    n = len(valid)
+    edges = []
+    for i in range(1, n_bins):
+        idx = int(i * n / n_bins)
+        edges.append(valid[min(idx, n - 1)])
+    # Deduplicate while keeping order
+    edges = sorted(set(edges))
+
+    # Bin centres: midpoint between consecutive edges
+    boundaries = [valid[0] - 1e-9] + edges + [valid[-1] + 1e-9]
+    centers = [
+        (boundaries[i] + boundaries[i + 1]) / 2.0
+        for i in range(len(boundaries) - 1)
+    ]
+    return edges, centers
+
+
+def _bin_search(v: float, edges: list) -> int:
+    """Binary-search bin index for value v given sorted cut-points."""
+    lo, hi = 0, len(edges)
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if v <= edges[mid]:
+            hi = mid
+        else:
+            lo = mid + 1
+    return lo

uchi/distributional.py

@@ -0,0 +1,105 @@
+import math
+from typing import Any
+
+def js_divergence(p: dict, q: dict) -> float:
+    """Calculate Jensen-Shannon Divergence between two probability dicts."""
+    vocab = set(p.keys()) | set(q.keys())
+    if not vocab:
+        return 0.0
+        
+    def kld(dist1, dist2):
+        res = 0.0
+        for k in vocab:
+            v1 = dist1.get(k, 0.0)
+            if v1 > 0:
+                v2 = dist2.get(k, 0.0)
+                if v2 == 0:
+                    return float('inf')
+                res += v1 * math.log2(v1 / v2)
+        return res
+
+    m = {}
+    for k in vocab:
+        m[k] = 0.5 * (p.get(k, 0.0) + q.get(k, 0.0))
+        
+    return 0.5 * kld(p, m) + 0.5 * kld(q, m)
+
+
+class DistributionalTokenizer:
+    """
+    Online semantic clustering via Jensen-Shannon divergence.
+    Replaces NLTK WordNet with pure mathematical distributions.
+    If two tokens are followed by similar distributions, they are merged.
+    """
+    def __init__(self, merge_threshold_jsd: float = 0.1, min_obs: int = 50):
+        self.merge_threshold = merge_threshold_jsd
+        self.min_obs = min_obs
+        
+        self.successor_counts = {}  # token -> dict of next_token -> count
+        self.token_totals = {}      # token -> int
+        
+        self.clusters = {}          # token -> cluster_id
+        self.next_cluster_id = 0
+        
+        self._last_token = None
+
+    def _normalize(self, token: Any) -> dict:
+        counts = self.successor_counts.get(token, {})
+        total = self.token_totals.get(token, 0)
+        if total == 0:
+            return {}
+        return {k: v / total for k, v in counts.items()}
+
+    def observe(self, token: Any) -> None:
+        if self._last_token is not None:
+            prev = self._last_token
+            if prev not in self.successor_counts:
+                self.successor_counts[prev] = {}
+                self.token_totals[prev] = 0
+                
+            self.successor_counts[prev][token] = self.successor_counts[prev].get(token, 0) + 1
+            self.token_totals[prev] += 1
+            
+            # Periodically attempt clustering
+            if self.token_totals[prev] % 100 == 0 and self.token_totals[prev] >= self.min_obs:
+                self._attempt_cluster(prev)
+                
+        self._last_token = token
+
+    def _attempt_cluster(self, target_token: Any):
+        if target_token in self.clusters:
+            return
+            
+        target_dist = self._normalize(target_token)
+        
+        best_candidate = None
+        lowest_jsd = float('inf')
+        
+        for candidate, total in self.token_totals.items():
+            if candidate == target_token or total < self.min_obs:
+                continue
+                
+            candidate_dist = self._normalize(candidate)
+            jsd = js_divergence(target_dist, candidate_dist)
+            
+            if jsd < lowest_jsd:
+                lowest_jsd = jsd
+                best_candidate = candidate
+                
+        if lowest_jsd < self.merge_threshold and best_candidate is not None:
+            # Merge!
+            if best_candidate in self.clusters:
+                c_id = self.clusters[best_candidate]
+            else:
+                c_id = f"__CLUSTER_{self.next_cluster_id}__"
+                self.clusters[best_candidate] = c_id
+                self.next_cluster_id += 1
+                
+            self.clusters[target_token] = c_id
+
+    def tokenize(self, token: Any) -> Any:
+        """Tokenize a single token and update distributions online."""
+        self.observe(token)
+        if token in self.clusters:
+            return self.clusters[token]
+        return token

uchi/dual_predictor.py

@@ -0,0 +1,172 @@
+"""
+DualPredictor
+=============
+Solves Problem 7 — Stationary/drift tradeoff.
+
+Two UniversalPredictors run in parallel:
+  stable  — high cred_max, high lambda_power: best on stationary data
+  drift   — low  cred_max, low  lambda_power: fastest drift recovery
+
+Their output distributions are blended by a weight that tracks the recent
+error rate on a rolling window.  When the error rate is high (something
+changed), weight shifts toward the drift predictor.  When low and stable,
+weight shifts toward the stability predictor.
+
+The routing is fully automatic and requires no configuration beyond the
+window size.
+
+API
+---
+dp = DualPredictor(context_length=4)
+dp.observe(token)
+pred, conf = dp.predict()
+dp.feedback(actual)
+dp.error_rate          # current rolling error rate
+dp.active_predictor    # 'stable' | 'drift' | 'blend'
+"""
+
+from collections import deque
+from .predictor import UniversalPredictor
+
+
+class DualPredictor:
+    """
+    Parameters
+    ----------
+    context_length : int
+    window : int
+        Rolling window size for error rate tracking (default 50).
+    drift_threshold : float
+        Error rate above which the drift predictor dominates (default 0.4).
+    stable_threshold : float
+        Error rate below which the stability predictor dominates (default 0.15).
+    stable_cred_max, stable_lambda_power : float
+        Hyperparameters for the stability-tuned predictor.
+    drift_cred_max, drift_lambda_power : float
+        Hyperparameters for the drift-tuned predictor.
+    learning_rate : float
+        Shared learning rate for both predictors.
+    """
+
+    def __init__(
+        self,
+        context_length: int,
+        window: int = 50,
+        drift_threshold: float = 0.4,
+        stable_threshold: float = 0.15,
+        stable_cred_max: float = 8.0,
+        stable_lambda_power: float = 0.8,
+        drift_cred_max: float = 3.0,
+        drift_lambda_power: float = 0.4,
+        learning_rate: float = 0.08,
+        **kwargs,
+    ):
+        self._stable = UniversalPredictor(
+            context_length,
+            learning_rate=learning_rate,
+            cred_max=stable_cred_max,
+            lambda_power=stable_lambda_power,
+            **kwargs,
+        )
+        self._drift = UniversalPredictor(
+            context_length,
+            learning_rate=learning_rate,
+            cred_max=drift_cred_max,
+            lambda_power=drift_lambda_power,
+            **kwargs,
+        )
+        self._window = deque(maxlen=window)
+        self._drift_threshold = drift_threshold
+        self._stable_threshold = stable_threshold
+        self._error_rate: float = 0.5
+        self._last_pred = None
+        self._last_dist: dict = {}
+        self._history: list[dict] = []  # per-step routing log
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def observe(self, token) -> 'DualPredictor':
+        self._stable.observe(token)
+        self._drift.observe(token)
+        return self
+
+    def predict(self):
+        """
+        Blend stable and drift distributions based on current error rate.
+        Returns (predicted_token, confidence).
+        """
+        self._stable.predict()
+        self._drift.predict()
+        p_s = self._stable._last_distribution
+        p_d = self._drift._last_distribution
+
+        w_drift, w_stable = self._routing_weights()
+
+        all_keys = set(p_s) | set(p_d)
+        if not all_keys:
+            self._last_pred = None
+            self._last_dist = {}
+            return None, 0.0
+
+        blended = {
+            k: w_stable * p_s.get(k, 0.0) + w_drift * p_d.get(k, 0.0)
+            for k in all_keys
+        }
+        total = sum(blended.values()) or 1.0
+        self._last_dist = {k: v / total for k, v in blended.items()}
+        self._last_pred = max(self._last_dist, key=self._last_dist.get)
+        return self._last_pred, self._last_dist[self._last_pred]
+
+    def feedback(self, actual) -> None:
+        """Update error rate and both predictors."""
+        wrong = (self._last_pred != actual)
+        self._window.append(1 if wrong else 0)
+        self._error_rate = sum(self._window) / len(self._window) if self._window else 0.5
+        self._stable.feedback(actual)
+        self._drift.feedback(actual)
+
+    # ── diagnostics ───────────────────────────────────────────────────────────
+
+    @property
+    def error_rate(self) -> float:
+        return self._error_rate
+
+    @property
+    def active_predictor(self) -> str:
+        w_d, w_s = self._routing_weights()
+        if w_s > 0.8:
+            return 'stable'
+        if w_d > 0.8:
+            return 'drift'
+        return 'blend'
+
+    @property
+    def _last_distribution(self) -> dict:
+        return self._last_dist
+
+    @property
+    def _vocab(self) -> set:
+        return self._stable._vocab
+
+    @property
+    def history(self) -> list:
+        return self._stable.history
+
+    # ── internal ──────────────────────────────────────────────────────────────
+
+    def _routing_weights(self) -> tuple[float, float]:
+        """
+        Returns (w_drift, w_stable).
+        Linear interpolation between thresholds:
+          error_rate >= drift_threshold  → (1.0, 0.0)
+          error_rate <= stable_threshold → (0.0, 1.0)
+          in between                     → smooth blend
+        """
+        e = self._error_rate
+        if e >= self._drift_threshold:
+            return 1.0, 0.0
+        if e <= self._stable_threshold:
+            return 0.0, 1.0
+        span = self._drift_threshold - self._stable_threshold
+        w_d = (e - self._stable_threshold) / span
+        return w_d, 1.0 - w_d