cortexm 0.3.0__py3-none-any.whl

cortexm/text/dissim.py

@@ -0,0 +1,252 @@
+"""DisSim v1 — rule-based discourse-aware text simplification.
+
+Recursive syntactic splitting on subordinate-clause markers, relative
+clauses, coordination, and appositions. Each split produces simpler
+core sentences linked by discourse relations (TEMPORAL_WHEN, CAUSAL,
+CONCESSION, RELATIVE_CLAUSE, etc).
+
+arxiv research: Niklaus, Cetto, Niklaus — DisSim (ACL 2019 workshop),
+arXiv:2308.00425 (2023). Pure-Python port of the rule-based v1
+algorithm — no T5-small dependency, no LLM call, μ=0 safe.
+
+Why this matters: the deterministic μ=0 extractor in bridge/extractor.py
+relies on regex pattern packs; complex compound sentences defeat every
+pattern. Splitting "Although Alice works at Google, she quit yesterday"
+into three simpler sentences lets each one match its own pattern.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable
+
+
+@dataclass
+class SimplifiedClause:
+    """A simplified core sentence + its discourse relation to parent."""
+    text: str
+    parent_id: int | None = None       # index of parent clause in split list
+    relation: str = "ROOT"             # discourse relation type
+    marker: str = ""                  # the connective word/phrase
+    depth: int = 0
+
+
+# Rule table: (regex_marker, relation_type, order)
+#   order = "before" → main clause comes before marker
+#   order = "after"  → main clause comes after marker
+#   order = "wrap"   → both sides are clauses, mark the second as the child
+RULES = [
+    (r"\bwhen\b",       "TEMPORAL_WHEN",    "before"),
+    (r"\bwhile\b",      "TEMPORAL_WHILE",   "before"),
+    (r"\bsince\b",      "TEMPORAL_SINCE",   "before"),
+    (r"\buntil\b",      "TEMPORAL_UNTIL",   "before"),
+    (r"\bafter\b",      "TEMPORAL_AFTER",   "before"),
+    (r"\bbefore\b",     "TEMPORAL_BEFORE",  "before"),
+    (r"\bbecause\b",    "CAUSAL",           "after"),
+    (r"\bsince\b",      "CAUSAL_SINCE",     "after"),  # ambiguous with temporal
+    (r"\bso that\b",    "PURPOSE",          "before"),
+    (r"\bso\b",         "RESULT",           "after"),
+    (r"\balthough\b",   "CONCESSION",       "before"),
+    (r"\beven though\b","CONCESSION",       "before"),
+    (r"\bthough\b",     "CONCESSION",       "before"),
+    (r"\bbut\b",        "CONTRAST",         "before"),
+    (r"\bhowever\b",    "CONTRAST",         "before"),
+    (r"\bwhich\b",      "RELATIVE_CLAUSE",  "wrap"),
+    (r"\bwho\b",        "RELATIVE_CLAUSE",  "wrap"),
+    (r"\bthat\b",       "RELATIVE_CLAUSE",  "wrap"),   # only when post-noun
+    (r"\bif\b",         "CONDITION",        "before"),
+    (r"\bunless\b",     "CONDITION",        "before"),
+    (r"\bwhereas\b",    "CONTRAST",         "before"),
+    (r"\bwhere\b",      "LOCATION",         "wrap"),
+]
+
+
+class DisSimSplitter:
+    """Recursive syntactic splitter — pure-Python DisSim v1."""
+
+    def __init__(self, max_depth: int = 3, min_clause_len: int = 3) -> None:
+        self.max_depth = max_depth
+        self.min_clause_len = min_clause_len
+        self.rules = [(re.compile(p, re.IGNORECASE), rel, order)
+                      for p, rel, order in RULES]
+
+    def split(self, sentence: str, depth: int = 0,
+              parent_id: int | None = None) -> list[SimplifiedClause]:
+        """Recursively simplify a sentence into core clauses.
+
+        Preserves trailing sentence-ending punctuation (. ! ?). The
+        downstream μ=0 pattern library in bridge/patterns.py uses
+        lookaheads like ``(?=[,.!?]|...|$)`` to anchor value capture;
+        stripping the trailing period silently broke role/role_as/
+        role_my patterns on clauses emitted here (the "Tier-4 unmess
+        trailing-punct" bug). We capture the terminator up-front and
+        re-attach it to the LAST clause produced, so downstream
+        patterns still see ``"I work as an engineer."`` instead of
+        ``"I work as an engineer"``.
+        """
+        # Capture trailing sentence terminator before splitting.
+        s = sentence.strip()
+        terminator = ""
+        if s and s[-1] in ".!?":
+            terminator = s[-1]
+            s = s[:-1].rstrip()
+        sentence = s
+        if depth >= self.max_depth or not sentence:
+            text = sentence + terminator if sentence else terminator
+            return [SimplifiedClause(text=text, parent_id=parent_id,
+                                     depth=depth)]
+
+        # find first matching rule
+        for pat, rel, order in self.rules:
+            m = pat.search(sentence)
+            if not m:
+                continue
+            marker = m.group(0).lower()
+            before = sentence[:m.start()].strip()
+            after = sentence[m.end():].strip()
+
+            clauses: list[SimplifiedClause] = []
+
+            # Handle the case where the marker is at position 0 (before is empty).
+            # For subordinate-clause markers (when, although, etc.), the
+            # dependent clause comes first, ending at the next comma or
+            # sentence boundary. The main clause follows.
+            if order == "before" and not before:
+                # dependent clause is from marker to next comma (or sentence end)
+                # main clause is the rest
+                comma_pos = after.find(",")
+                if comma_pos > 0:
+                    dependent = after[:comma_pos].strip()
+                    main = after[comma_pos + 1:].strip()
+                else:
+                    # no comma — treat entire after as the dependent clause
+                    dependent = after
+                    main = ""
+                if dependent and len(dependent.split()) >= self.min_clause_len:
+                    clauses.append(SimplifiedClause(
+                        text=dependent, parent_id=parent_id,
+                        relation=rel, marker=marker, depth=depth))
+                    dep_idx = len(clauses) - 1
+                    if main:
+                        clauses.extend(self.split(main, depth + 1, dep_idx))
+                        for c in clauses:
+                            if (c.parent_id == dep_idx
+                                and c.relation == "ROOT"):
+                                c.relation = "MAIN"
+                                break
+                else:
+                    continue
+            elif order == "before" and before and after:
+                # main clause first, then dependent
+                if (len(before.split()) >= self.min_clause_len
+                    or len(after.split()) >= self.min_clause_len):
+                    clauses.append(SimplifiedClause(
+                        text=before, parent_id=parent_id,
+                        relation="ROOT" if depth == 0 else "PARENT",
+                        marker=marker, depth=depth))
+                    main_idx = len(clauses) - 1
+                    clauses.extend(self.split(after, depth + 1, main_idx))
+                    for c in clauses:
+                        if (c.parent_id == main_idx
+                            and c.relation == "ROOT"):
+                            c.relation = rel
+                            c.marker = marker
+                            break
+                else:
+                    continue
+            elif order == "after" and before and after:
+                # dependent (cause) first, main (effect) after
+                if (len(before.split()) >= self.min_clause_len
+                    or len(after.split()) >= self.min_clause_len):
+                    clauses.append(SimplifiedClause(
+                        text=before, parent_id=parent_id,
+                        relation=rel, marker=marker, depth=depth))
+                    cause_idx = len(clauses) - 1
+                    clauses.extend(self.split(after, depth + 1, cause_idx))
+                    for c in clauses:
+                        if (c.parent_id == cause_idx
+                            and c.relation == "ROOT"):
+                            c.relation = "EFFECT"
+                            break
+                else:
+                    continue
+            elif order == "wrap" and before and after:
+                # relative clause: split into main + relative
+                clauses.append(SimplifiedClause(
+                    text=before, parent_id=parent_id,
+                    relation="ROOT" if depth == 0 else "PARENT",
+                    marker=marker, depth=depth))
+                main_idx = len(clauses) - 1
+                clauses.extend(self.split(after, depth + 1, main_idx))
+                for c in clauses:
+                    if c.parent_id == main_idx and c.relation == "ROOT":
+                        c.relation = rel
+                        c.marker = marker
+                        break
+            else:
+                # not enough content on both sides — try next rule
+                continue
+
+            if clauses:
+                # try to recursively split each clause further
+                expanded: list[SimplifiedClause] = []
+                for c in clauses:
+                    if c.depth >= self.max_depth:
+                        expanded.append(c)
+                    else:
+                        sub = self.split(c.text, c.depth + 1, c.parent_id)
+                        if len(sub) > 1:
+                            for sc in sub:
+                                if sc.parent_id == c.parent_id:
+                                    sc.relation = c.relation
+                                    sc.marker = c.marker
+                            expanded.extend(sub)
+                        else:
+                            expanded.append(c)
+                # de-duplicate by text
+                seen: set[str] = set()
+                out: list[SimplifiedClause] = []
+                for c in expanded:
+                    if c.text and c.text not in seen:
+                        seen.add(c.text)
+                        out.append(c)
+                if not out:
+                    out = [SimplifiedClause(text=sentence, parent_id=parent_id,
+                                            depth=depth)]
+                # re-attach the trailing terminator to the LAST clause
+                # so downstream μ=0 patterns that anchor on [.!?] still
+                # match (Tier-4 unmess trailing-punct bug fix).
+                if terminator and out:
+                    last = out[-1]
+                    if not (last.text and last.text[-1] in ".!?"):
+                        last.text = last.text + terminator
+                return out
+
+        # no rule matched — re-attach the terminator
+        return [SimplifiedClause(text=sentence + terminator,
+                                 parent_id=parent_id, depth=depth)]
+
+    def simplify_text(self, text: str) -> list[SimplifiedClause]:
+        """Split a multi-sentence text into simplified clauses."""
+        out: list[SimplifiedClause] = []
+        for sent in _split_sentences(text):
+            out.extend(self.split(sent))
+        return out
+
+
+def _split_sentences(text: str) -> list[str]:
+    """Simple sentence splitter — respects ., !, ? but preserves common
+    abbreviations (Dr., Mr., Inc., etc.)."""
+    if not text:
+        return []
+    # protect common abbreviations
+    protected = text
+    for abbr in ("Mr.", "Mrs.", "Dr.", "Ms.", "Jr.", "Sr.", "Inc.",
+                 "Ltd.", "Corp.", "vs.", "etc.", "i.e.", "e.g."):
+        protected = protected.replace(abbr, abbr.replace(".", "<DOT>"))
+    parts = re.split(r"(?<=[.!?])\s+", protected)
+    return [p.replace("<DOT>", ".").strip() for p in parts if p.strip()]
+
+
+__all__ = ["DisSimSplitter", "SimplifiedClause"]

cortexm/text/embedder.py

@@ -0,0 +1,155 @@
+"""Deterministic feature-hashing embedder (μ=0 even at the embedding layer).
+
+No external model, no API call, fully reproducible from a seed. Produces
+L2-normalized float32 vectors of ``dims`` dimensions from token unigrams,
+token bigrams and character n-grams via signed feature hashing
+(Weinberger et al., 2009). A ``EmbeddingProvider`` protocol allows
+swapping in a local transformer (e.g. ONNX MiniLM) or an API-backed
+model in production without touching the rest of the fabric.
+
+With ``labse_enabled=True`` (Config.labse_enabled), text whose non-ASCII
+ratio exceeds 30% is delegated to ``PolyglotEncoder`` — a LaBSE-inspired
+Unicode n-gram hasher that handles CJK / Devanagari / Arabic / Cyrillic
+scripts (which the regex tokenizer drops entirely, producing a constant
+embedding and zero retrieval recall — see docs/BENCHMARKS.md Tier-1).
+English text stays on the existing fast path. See
+``context_m/text/labse.py`` for the polyglot algorithm.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Protocol
+
+import numpy as np
+
+from cortexm.text.labse import PolyglotEncoder
+from cortexm.text.tokenizer import STOPWORDS, words
+from cortexm.util import h64 as _h64
+
+
+class EmbeddingProvider(Protocol):
+    dims: int
+
+    def embed(self, text: str) -> np.ndarray: ...
+
+    def embed_many(self, texts: list[str]) -> np.ndarray: ...
+
+
+def _h64(feature: str, seed: int) -> int:
+    import hashlib
+    return int.from_bytes(
+        hashlib.blake2b(feature.encode("utf-8"), digest_size=8,
+                        key=seed.to_bytes(8, "little")).digest(), "little")
+
+
+class HashingEmbedder:
+    """Signed feature hashing over token/bigram/char-ngram features.
+
+    With ``labse_enabled=True``, non-English text (>30% non-ASCII chars)
+    is delegated to ``PolyglotEncoder`` — a LaBSE-inspired Unicode
+    n-gram encoder that handles scripts the regex tokenizer drops
+    (CJK, Devanagari, Arabic, Cyrillic, Thai, Hangul, Kana). English
+    text stays on the existing fast path. Default OFF so existing
+    behavior is unchanged; opt in via ``Config.labse_enabled`` or the
+    ``CONTEXT_M_LABSE`` env var.
+    """
+
+    def __init__(self, dims: int = 768, seed: int = 0x0C0FFEE,
+                 char_ngrams: tuple[int, ...] = (3, 4, 5),
+                 use_bigrams: bool = True,
+                 labse_enabled: bool = False) -> None:
+        self.dims = dims
+        self.seed = seed & 0xFFFFFFFFFFFFFFFF
+        self.char_ngrams = char_ngrams
+        self.use_bigrams = use_bigrams
+        self.labse_enabled = labse_enabled
+        self._feat_cache: dict[str, tuple[int, int, float]] = {}
+        # Lazy-initialized polyglot encoder — only built when first needed
+        # so the labse.py module import cost is paid only by users who
+        # actually ingest non-English text.
+        self._polyglot: PolyglotEncoder | None = None
+
+    @property
+    def polyglot(self) -> PolyglotEncoder:
+        """Lazily-constructed PolyglotEncoder (dims/seed-matched)."""
+        if self._polyglot is None:
+            self._polyglot = PolyglotEncoder(
+                dims=self.dims, seed=self.seed)
+        return self._polyglot
+
+    @staticmethod
+    def _non_ascii_ratio(text: str) -> float:
+        """Fraction of non-ASCII chars in text. 0.0 for empty input."""
+        if not text:
+            return 0.0
+        non_ascii = sum(1 for c in text if ord(c) > 127)
+        return non_ascii / len(text)
+
+    # -- feature extraction -------------------------------------------------
+
+    def _feature(self, token: str) -> tuple[int, int, float]:
+        hit = self._feat_cache.get(token)
+        if hit is not None:
+            return hit
+        h = _h64(token, self.seed)
+        idx = h % self.dims
+        sign = 1 if (h >> 63) & 1 else -1
+        base = 0.35 if token in STOPWORDS else 1.0
+        out = (idx, sign, base)
+        if len(self._feat_cache) < 500_000:
+            self._feat_cache[token] = out
+        return out
+
+    def _char_features(self, token: str) -> list[tuple[int, int, float]]:
+        padded = f"^{token}$"
+        feats = []
+        for n in self.char_ngrams:
+            if len(padded) < n:
+                feats.append((padded, 0.5))
+                continue
+            for i in range(len(padded) - n + 1):
+                feats.append((padded[i:i + n], 0.5))
+        out = []
+        for gram, w in feats:
+            h = _h64(gram, self.seed ^ 0xA5A5)
+            out.append((h % self.dims, 1 if (h >> 63) & 1 else -1, w))
+        return out
+
+    # -- API ------------------------------------------------------------------
+
+    def embed(self, text: str) -> np.ndarray:
+        # Polyglot fallback for non-English text — the regex tokenizer
+        # in words() drops non-ASCII letters entirely, so without this
+        # delegation, every non-English sentence embeds to the constant
+        # [1, 0, 0, ...] vector (Tier-1 non-English recall = 0.000).
+        if self.labse_enabled and self._non_ascii_ratio(text) > 0.30:
+            return self.polyglot.encode(text)
+        vec = np.zeros(self.dims, dtype=np.float32)
+        toks = words(text)
+        if not toks:
+            vec[0] = 1.0
+            return vec
+        counts: dict[str, float] = {}
+        for t in toks:
+            counts[t] = counts.get(t, 0.0) + 1.0
+        for tok, tf in counts.items():
+            idx, sign, base = self._feature(tok)
+            vec[idx] += sign * base * (1.0 + math.log(tf))
+            for cidx, csign, cw in self._char_features(tok):
+                vec[cidx] += csign * cw * (1.0 + math.log(tf)) * 0.35
+        if self.use_bigrams:
+            for a, b in zip(toks, toks[1:]):
+                if a in STOPWORDS and b in STOPWORDS:
+                    continue
+                idx, sign, base = self._feature(f"{a}_{b}")
+                vec[idx] += sign * base * 0.7
+        n = float(np.linalg.norm(vec))
+        if n > 0:
+            vec /= n
+        return vec
+
+    def embed_many(self, texts: list[str]) -> np.ndarray:
+        if not texts:
+            return np.zeros((0, self.dims), dtype=np.float32)
+        return np.stack([self.embed(t) for t in texts])

cortexm/text/fuzzy.py

@@ -0,0 +1,218 @@
+"""Bitap + Levenshtein + n-gram approximate string matching.
+
+Wu-Manber k-error Bitap (Baeza-Yates-Gonnet 1992; Wu-Manber 1994) for
+patterns <= 63 chars — single-word packed, O(n*k) for k errors. Falls
+back to early-exit Levenshtein DP for longer patterns. Used to:
+
+  * replace util.levenshtein() inner loop on short strings (5-20x faster)
+  * power spelling-tolerant pattern triggers in bridge/patterns.py
+  * surface "close enough" candidates in normalization (idiolect.py)
+
+arxiv research note: Bitap is the bitwise-baseline for fuzzy matching;
+Myers' bit-parallel DP has the same asymptotic but worse constants on
+small alphabets. For Context-M's typical pattern lengths (<32) and
+small edit budgets (k<=3), Bitap wins.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+
+def bitap_levenshtein(text: str, pattern: str, max_edits: int = 3) -> int | None:
+    """Wu-Manber k-error Bitap (substring matching with errors).
+
+    Returns the smallest edit distance within max_edits if the pattern
+    appears as a substring of text (allowing up to max_edits insertions,
+    deletions, substitutions), else None.
+
+    Pattern length must be <= 63 for single uint64 packing; longer
+    patterns fall back to DP. If pattern is longer than text + max_edits,
+    no match is possible and we return None early.
+    """
+    m = len(pattern)
+    if m == 0:
+        return 0
+    # early-exit: substring match impossible if pattern too long for text+errors
+    if m > len(text) + max_edits:
+        return None
+    if m > 63:
+        return _levenshtein_substring(text, pattern, max_edits)
+    # build per-char bitmask
+    R: dict[str, int] = {}
+    for i, ch in enumerate(pattern):
+        R[ch] = R.get(ch, 0) | (1 << i)
+    mask = (1 << m) - 1
+    match_bit = 1 << (m - 1)
+    # Wu-Manber initial states:
+    #   T[0] = mask with bit 0 cleared (no chars consumed yet)
+    #   T[e] = T[e-1] << 1 (allow e leading insertions = e leading chars of
+    #          pattern can be "matched" via insertion without consuming text)
+    states = [0] * (max_edits + 1)
+    states[0] = mask ^ 1   # bit 0 cleared
+    for e in range(1, max_edits + 1):
+        # T[e] = T[e-1] shifted left by 1 (each leading insertion advances
+        # the pattern position by 1)
+        states[e] = ((states[e - 1] << 1) | 1) & mask
+    best = None
+    for ch in text:
+        rc = R.get(ch, 0)
+        prev = states[0]
+        new_states = list(states)
+        new_states[0] = ((states[0] << 1) | 1) & rc & mask
+        for e in range(1, max_edits + 1):
+            # match: T[e] advances if char matches
+            # substitution: T[e-1] advances (use 1 error)
+            # deletion in text: T[e-1] (use 1 error, skip text char)
+            # insertion in text: T[e] advances (use 1 error, skip pattern char)
+            cur = ((states[e] << 1) | 1) & rc
+            cur |= prev | (prev << 1) | (states[e] << 1)
+            cur &= mask
+            prev = states[e]   # save OLD states[e] before overwrite
+            new_states[e] = cur
+        states = new_states
+        # check for a match at any error budget
+        for e in range(max_edits + 1):
+            if states[e] & match_bit:
+                if best is None or e < best:
+                    best = e
+                break  # lower e wins
+    return best
+
+
+def _levenshtein_substring(text: str, pattern: str, max_edits: int) -> int | None:
+    """Sliding-window DP for patterns > 63 chars. O(n*m) but rare path."""
+    n, m = len(text), len(pattern)
+    if m == 0:
+        return 0
+    if abs(n - m) > max_edits and n < m:
+        return None
+    best = None
+    # slide a window of [m-max_edits, m+max_edits] over text
+    lo = max(0, m - max_edits)
+    hi = min(n, m + max_edits)
+    for start in range(0, n - lo + 1):
+        sub = text[start:start + hi]
+        if not sub:
+            continue
+        d = _levenshtein_full(sub, pattern)
+        if d <= max_edits and (best is None or d < best):
+            best = d
+            if best == 0:
+                return 0
+    return best
+
+
+def _levenshtein_full(a: str, b: str) -> int:
+    """Classic 2-row DP — used only as fallback for long patterns."""
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, 1):
+        cur = [i] + [0] * len(b)
+        for j, cb in enumerate(b, 1):
+            ins = cur[j - 1] + 1
+            dele = prev[j] + 1
+            sub = prev[j - 1] + (0 if ca == cb else 1)
+            cur[j] = min(ins, dele, sub)
+        prev = cur
+    return prev[-1]
+
+
+def levenshtein(a: str, b: str, cutoff: float | None = None) -> int:
+    """Full edit distance (not substring-distance). Uses DP.
+
+    This is the right metric for word-level similarity. Bitap is for
+    substring matching inside longer text — different semantic.
+    """
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    # Early-exit: if length diff exceeds cutoff, bail
+    if cutoff is not None and abs(len(a) - len(b)) > cutoff * max(len(a), len(b)):
+        return max(len(a), len(b))
+    return _levenshtein_full(a, b)
+
+
+def similarity(a: str, b: str) -> float:
+    """1 - normalized Levenshtein. Bitap-fast on short strings."""
+    if not a and not b:
+        return 1.0
+    d = levenshtein(a, b)
+    return max(0.0, 1.0 - d / max(len(a), len(b)))
+
+
+def ngram_jaccard(a: str, b: str, n: int = 3) -> float:
+    """Character n-gram Jaccard — for fuzzy lexicon lookup.
+
+    Faster than full Levenshtein for similarity thresholding on
+    short tokens. Complements Bitap (which is good for substring
+    matching) by being good at "are these two tokens plausibly the
+    same word" judgments.
+    """
+    if not a or not b:
+        return 0.0
+    ga = {a[i:i + n] for i in range(len(a) - n + 1)} or {a}
+    gb = {b[i:i + n] for i in range(len(b) - n + 1)} or {b}
+    inter = len(ga & gb)
+    union = len(ga | gb)
+    return inter / union if union else 0.0
+
+
+def best_match(query: str, candidates: Iterable[str],
+              max_edits: int = 2, min_sim: float = 0.7) -> str | None:
+    """Find the best fuzzy match for query among candidates.
+
+    Uses Levenshtein similarity (1 - dist/max_len) as the primary metric
+    and n-gram Jaccard as tiebreaker. Returns None if no candidate
+    crosses min_sim.
+    """
+    if not query:
+        return None
+    cand_list = list(candidates)
+    if not cand_list:
+        return None
+    best, best_score = None, 0.0
+    q = query.lower()
+    for c in cand_list:
+        cl = c.lower()
+        if q == cl:
+            return c
+        # primary: normalized Levenshtein similarity
+        d = _levenshtein_full(q, cl)
+        sim = 1.0 - d / max(len(q), len(cl))
+        # boost with n-gram Jaccard (catches character-level similarity)
+        j = ngram_jaccard(q, cl)
+        score = 0.7 * sim + 0.3 * j
+        if score > best_score:
+            best_score, best = score, c
+    return best if best_score >= min_sim else None
+
+
+def fuzzy_contains(haystack: str, needle: str, max_edits: int = 2) -> bool:
+    """True if needle appears in haystack within max_edits (Bitap)."""
+    if not needle:
+        return True
+    if len(needle) <= 63:
+        return bitap_levenshtein(haystack, needle, max_edits) is not None
+    # fallback: regex with whitespace tolerance
+    pattern = re.escape(needle)
+    return bool(re.search(pattern, haystack, re.IGNORECASE))
+
+
+__all__ = [
+    "bitap_levenshtein",
+    "levenshtein",
+    "similarity",
+    "ngram_jaccard",
+    "best_match",
+    "fuzzy_contains",
+]