dense-evolution 8.3.0__py3-none-win_amd64.whl

ia_utils/adversarial_vector_attack.py

@@ -0,0 +1,196 @@
+"""
+Gradient-based adversarial stress-testing for enhanced_dense_healing_hybrid's
+Phi-Trigger decision -- a targeted, crafted perturbation instead of the
+random NaN/Inf corruption this healing pipeline is normally tested
+against, adapted from IGME's chained-differentiable-attack idea
+(arXiv:2607.27465, "IGME: Efficient Chained Method Ensemble for
+Transferable Semantic Segmentation Attacks") applied to vector sequences
+instead of image segmentation.
+
+evaluate_phi_trigger (dense_evolution.healing) makes its keep-vs-median-
+replace decision by thresholding |v_dinamic| against NON_STATIC_THRESHOLD_A
+-- a hard step, not differentiable at the boundary. But v_dinamic itself
+(via calculate_phi_ab -> calculate_vettore_dinamico) is built entirely
+from norms, dot products, log, and clip -- all JAX-differentiable. This
+crafts a minimal perturbation to a single vector in the sequence, via
+gradient ascent/descent on |v_dinamic| (projected back into an epsilon
+L2-ball each step, the standard PGD pattern), that flips the trigger's
+decision at that point:
+
+- "flip_to_dynamic": push an originally-static point (would be replaced
+  by the local median) across the threshold so the trigger keeps it
+  as-is instead -- the more security-relevant direction, since it
+  represents a worst-case corruption crafted to *evade* the healer by
+  looking like genuine motion, rather than obvious noise.
+- "flip_to_static": push an originally-dynamic point (would be kept)
+  across the threshold so the trigger discards it as noise instead --
+  the failure mode of genuine signal getting wrongly suppressed.
+
+This does not attack the median-filter fallback itself, only the
+Phi-Trigger's keep-vs-replace decision -- see craft_adversarial_healing_
+perturbation's own docstring for what "success" means precisely.
+"""
+
+from typing import Optional
+
+import numpy as np
+import jax
+import jax.numpy as jnp
+
+from dense_evolution.mitigation.healing import calculate_phi_ab, calculate_vettore_dinamico, GLOBAL_CONSTANTS
+
+__all__ = ['craft_adversarial_healing_perturbation']
+
+
+def _trigger_magnitude(state_B, state_A, ipg_vector):
+    """|v_dinamic| -- the continuous quantity evaluate_phi_trigger
+    thresholds. Differentiable w.r.t. state_B (the vector being attacked);
+    state_A/ipg_vector are treated as fixed context, not attacked."""
+    phi_ab = calculate_phi_ab(state_A, state_B, ipg_vector)
+    E_A = jnp.linalg.norm(state_A)
+    E_B = jnp.linalg.norm(state_B)
+    v_dinamic = calculate_vettore_dinamico(E_A, E_B, phi_ab)
+    return jnp.abs(v_dinamic)
+
+
+_trigger_magnitude_grad = jax.grad(_trigger_magnitude, argnums=0)
+
+
+def craft_adversarial_healing_perturbation(
+    vettori: np.ndarray,
+    target_idx: int,
+    radius_baseline: Optional[int] = None,
+    epsilon: float = 0.1,
+    n_steps: int = 50,
+    step_size: Optional[float] = None,
+    direction: str = "flip_to_dynamic",
+) -> dict:
+    """Crafts a minimal adversarial perturbation to vettori[target_idx],
+    within an L2 epsilon-ball, that flips enhanced_dense_healing_hybrid's
+    Phi-Trigger decision at that index -- a targeted stress test, not
+    random noise.
+
+    Reproduces enhanced_dense_healing_hybrid's own per-step computation
+    at target_idx exactly (same baseline_mean window, same adaptive
+    radius default, same inter-point-gradient vector) so the crafted
+    perturbation is faithful to what the real healing pipeline would
+    actually see, not a simplified stand-in.
+
+    BUG FIX: step_size used to default to 2*epsilon/n_steps -- tying the
+    per-step move size to the epsilon budget. Verified directly this
+    makes LARGER epsilon give WORSE (higher final |v_dinamic|) results,
+    not better: a bigger budget means a bigger step, which overshoots
+    and oscillates around the minimum instead of converging to it,
+    which is the opposite of what a bigger budget should ever do for a
+    correct optimizer. step_size is now independent of epsilon (a small
+    fixed default, tuned to v_dinamic's typical local scale) -- epsilon
+    only bounds where the iterate is allowed to end up (via projection
+    after each step), not how big each step is.
+
+    Args:
+        vettori: array-like, shape (n_steps, dim), the (unperturbed)
+            vector sequence. Not modified in place.
+        target_idx: index to attack; must be >= 2 (the healing loop's
+            own starting point) and < len(vettori).
+        radius_baseline: same meaning as enhanced_dense_healing_hybrid's
+            own parameter; None uses the same adaptive default.
+        epsilon: L2-norm budget for the perturbation (the attack is
+            projected back into this ball after every gradient step).
+        n_steps: number of PGD-style gradient steps.
+        step_size: per-step move size along the normalized gradient;
+            None uses a small fixed default (0.02) independent of
+            epsilon -- see the bug-fix note above for why.
+        direction: "flip_to_dynamic" (evade -- make static-looking
+            input pass through unhealed) or "flip_to_static" (suppress
+            -- make dynamic-looking input get median-replaced instead).
+
+    Returns:
+        dict with:
+            perturbed_vettori: copy of vettori with vettori[target_idx]
+                replaced by the crafted perturbation.
+            success: bool, True only if the trigger decision actually
+                flipped in the requested direction (a small epsilon or
+                too few steps can fail to cross the threshold).
+            original_trigger_active / final_trigger_active: bool, the
+                Phi-Trigger's decision (True = dynamic/kept) before and
+                after the perturbation.
+            original_magnitude / final_magnitude: float, |v_dinamic|
+                before and after.
+            perturbation_norm: float, actual L2 norm of the applied
+                perturbation (<= epsilon).
+    """
+    vettori = np.asarray(vettori, dtype=np.float64)
+    n, hidden_dim = vettori.shape
+    if target_idx < 2 or target_idx >= n:
+        raise ValueError(f"target_idx must be in [2, {n - 1}], got {target_idx} (n={n})")
+    if direction not in ("flip_to_dynamic", "flip_to_static"):
+        raise ValueError(f"direction must be 'flip_to_dynamic' or 'flip_to_static', got {direction!r}")
+    if epsilon <= 0:
+        raise ValueError(f"epsilon must be positive, got {epsilon}")
+
+    if radius_baseline is None:
+        radius_baseline = min(20, max(3, n // 3))
+    lo = max(0, target_idx - radius_baseline)
+
+    state_A = jnp.array(np.mean(vettori[lo:target_idx], axis=0))
+    ipg_raw = vettori[target_idx - 1] - vettori[target_idx - 2]
+    norm_ipg_raw = np.linalg.norm(ipg_raw)
+    ipg_vector = jnp.array(ipg_raw / norm_ipg_raw) if norm_ipg_raw > 1e-9 else jnp.array(ipg_raw)
+
+    original_state_B = jnp.array(vettori[target_idx])
+    threshold = GLOBAL_CONSTANTS['NON_STATIC_THRESHOLD_A']
+    original_magnitude = float(_trigger_magnitude(original_state_B, state_A, ipg_vector))
+    original_trigger_active = original_magnitude > threshold
+
+    sign = 1.0 if direction == "flip_to_dynamic" else -1.0
+    if step_size is None:
+        step_size = 0.02
+
+    # Track the best iterate seen (most favorable to `direction`), not
+    # just the last one -- with a fixed small step size the trajectory
+    # can overshoot past the optimum and drift back worse on later
+    # steps, especially once it's pinned against the epsilon-ball
+    # boundary; keeping the best-so-far makes the result robust to
+    # exactly how many steps were requested.
+    state_B = original_state_B
+    best_state_B = original_state_B
+    best_magnitude = original_magnitude
+    for _ in range(n_steps):
+        grad = _trigger_magnitude_grad(state_B, state_A, ipg_vector)
+        grad_norm = jnp.linalg.norm(grad)
+        step = jnp.where(grad_norm > 1e-12, grad / grad_norm, jnp.zeros_like(grad))
+        state_B = state_B + sign * step_size * step
+        # Project back into the epsilon L2-ball around the original vector.
+        delta = state_B - original_state_B
+        delta_norm = jnp.linalg.norm(delta)
+        state_B = jnp.where(delta_norm > epsilon, original_state_B + delta / delta_norm * epsilon, state_B)
+
+        current_magnitude = float(_trigger_magnitude(state_B, state_A, ipg_vector))
+        is_better = (current_magnitude > best_magnitude) if direction == "flip_to_dynamic" else (current_magnitude < best_magnitude)
+        if is_better:
+            best_magnitude = current_magnitude
+            best_state_B = state_B
+
+    state_B = best_state_B
+    final_magnitude = float(_trigger_magnitude(state_B, state_A, ipg_vector))
+    final_trigger_active = final_magnitude > threshold
+    perturbation_norm = float(jnp.linalg.norm(state_B - original_state_B))
+
+    perturbed_vettori = vettori.copy()
+    perturbed_vettori[target_idx] = np.asarray(state_B)
+
+    flipped = final_trigger_active != original_trigger_active
+    success = flipped and (
+        (direction == "flip_to_dynamic" and final_trigger_active)
+        or (direction == "flip_to_static" and not final_trigger_active)
+    )
+
+    return {
+        "perturbed_vettori": perturbed_vettori,
+        "success": bool(success),
+        "original_trigger_active": bool(original_trigger_active),
+        "final_trigger_active": bool(final_trigger_active),
+        "original_magnitude": original_magnitude,
+        "final_magnitude": final_magnitude,
+        "perturbation_norm": perturbation_norm,
+    }

ia_utils/rag.py

@@ -0,0 +1,288 @@
+"""
+Hybrid two-stage retrieval (sparse TF-IDF UNION dense bi-encoder, pretrained
+cross-encoder rerank) for grounding an agent's output in a local document
+collection, instead of trusting an unverified citation.
+
+Promoted from quantumrag (Desktop/Fullwork/quantumrag), a local RAG tool used
+through Dense-Evolution-Discovery to check physics/chemistry claims against
+real, independently-verified arXiv papers before citing them -- validated
+there across ~30 topic collections (~6300 chunks) before this promotion. Only
+the retrieval mechanism moves here, not quantumrag's own paper corpus or
+built indexes -- those stay local, out of the package.
+
+Stage 1 pools candidates from TF-IDF cosine (exact-term overlap, cheap, whole
+collection) UNION a dense bi-encoder (catches paraphrases/synonyms TF-IDF
+misses on its own -- Karpukhin et al. 2020, "Dense Passage Retrieval for
+Open-Domain Question Answering", arXiv:2004.04906). Stage 2 reranks that pool
+with a pretrained cross-encoder (Nogueira & Cho 2019, "Passage Re-ranking
+with BERT", arXiv:1901.04085) -- a slower model that reads query+chunk
+together instead of comparing two separate vectors, applied only to the
+(small) pooled candidates, never the whole collection.
+
+Needs the optional `rag` extra (scikit-learn + sentence-transformers) --
+same pattern as native_hf.libcint_bridge (pyscf) and qmmm.region (rdkit):
+the whole module is off-limits without it, since even the TF-IDF-only path
+(build_index(compute_embeddings=False), search(rerank=False)) is built on
+scikit-learn's TfidfVectorizer/cosine_similarity. chunk_text (pure Python,
+no vectorizer/model involved) is the one function usable with no extra at
+all -- it doesn't import this module's sklearn/sentence-transformers names.
+"""
+
+from __future__ import annotations
+
+import json
+import pickle
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+CHUNK_SIZE_CHARS = 1200
+CHUNK_OVERLAP_CHARS = 200
+DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+DEFAULT_CROSS_ENCODER_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+DEFAULT_POOL = 20
+
+# Keyed by model name so build_index/search calls with the same default
+# model (the normal case) only ever load it once per process, regardless of
+# how many collections/queries are processed.
+_embedder_cache: dict = {}
+_reranker_cache: dict = {}
+
+_MISSING_RAG_EXTRA = (
+    "needs the optional 'rag' extra (pip install dense-evolution[rag]) -- "
+    "failed to import: {}"
+)
+
+
+def _get_embedder(model_name: str):
+    if model_name not in _embedder_cache:
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as _import_error:  # pragma: no cover -- only reachable without sentence-transformers installed, which CI here always has
+            raise ImportError(_MISSING_RAG_EXTRA.format(_import_error)) from _import_error
+        _embedder_cache[model_name] = SentenceTransformer(model_name)
+    return _embedder_cache[model_name]
+
+
+def _get_reranker(model_name: str):
+    if model_name not in _reranker_cache:
+        try:
+            from sentence_transformers import CrossEncoder
+        except ImportError as _import_error:  # pragma: no cover -- only reachable without sentence-transformers installed, which CI here always has
+            raise ImportError(_MISSING_RAG_EXTRA.format(_import_error)) from _import_error
+        _reranker_cache[model_name] = CrossEncoder(model_name)
+    return _reranker_cache[model_name]
+
+
+def chunk_text(
+    text: str,
+    source: str,
+    chunk_size: int = CHUNK_SIZE_CHARS,
+    overlap: int = CHUNK_OVERLAP_CHARS,
+) -> list:
+    chunks = []
+    start = 0
+    n = len(text)
+    while start < n:
+        end = min(start + chunk_size, n)
+        piece = text[start:end].strip()
+        if piece:
+            chunks.append({"source": source, "text": piece})
+        if end == n:
+            break
+        start = end - overlap
+    return chunks
+
+
+@dataclass
+class RagIndex:
+    chunks: list
+    vectorizer: object  # sklearn.feature_extraction.text.TfidfVectorizer, fitted
+    matrix: object  # scipy.sparse matrix, vectorizer's transform of every chunk's text
+    embeddings: Optional[np.ndarray] = None
+
+
+def build_index(
+    documents,
+    embedding_model: str = DEFAULT_EMBEDDING_MODEL,
+    compute_embeddings: bool = True,
+    chunk_size: int = CHUNK_SIZE_CHARS,
+    overlap: int = CHUNK_OVERLAP_CHARS,
+) -> RagIndex:
+    """
+    documents: iterable of (text, source) pairs, one per already-extracted
+    document (PDF/markdown/plain text parsing happens before this call --
+    this module only chunks and indexes text it's handed). compute_embeddings
+    can be set False to skip the (slower) bi-encoder pass and build a
+    TF-IDF-only index -- still needs the 'rag' extra for scikit-learn, just
+    not sentence-transformers' model download; search() then falls back to
+    plain cosine regardless of `rerank`.
+    """
+    try:
+        from sklearn.feature_extraction.text import TfidfVectorizer
+    except ImportError as _import_error:  # pragma: no cover -- only reachable without scikit-learn installed, which CI here always has
+        raise ImportError(_MISSING_RAG_EXTRA.format(_import_error)) from _import_error
+
+    all_chunks = []
+    for text, source in documents:
+        all_chunks.extend(chunk_text(text, source, chunk_size, overlap))
+    if not all_chunks:
+        raise ValueError("no chunks produced -- 'documents' was empty or every text was blank")
+
+    texts = [c["text"] for c in all_chunks]
+    vectorizer = TfidfVectorizer(stop_words="english", max_features=20000, ngram_range=(1, 2))
+    matrix = vectorizer.fit_transform(texts)
+
+    embeddings = None
+    if compute_embeddings:
+        embeddings = _get_embedder(embedding_model).encode(
+            texts, normalize_embeddings=True, show_progress_bar=False
+        )
+
+    return RagIndex(chunks=all_chunks, vectorizer=vectorizer, matrix=matrix, embeddings=embeddings)
+
+
+def save_index(index: RagIndex, index_dir) -> None:
+    index_dir = Path(index_dir)
+    index_dir.mkdir(parents=True, exist_ok=True)
+    with open(index_dir / "chunks.json", "w", encoding="utf-8") as f:
+        json.dump(index.chunks, f, ensure_ascii=False, indent=2)
+    with open(index_dir / "vectorizer.pkl", "wb") as f:
+        pickle.dump(index.vectorizer, f)
+    with open(index_dir / "matrix.pkl", "wb") as f:
+        pickle.dump(index.matrix, f)
+    if index.embeddings is not None:
+        np.save(index_dir / "embeddings.npy", index.embeddings)
+
+
+def load_index(index_dir) -> RagIndex:
+    index_dir = Path(index_dir)
+    with open(index_dir / "chunks.json", encoding="utf-8") as f:
+        chunks = json.load(f)
+    with open(index_dir / "vectorizer.pkl", "rb") as f:
+        vectorizer = pickle.load(f)
+    with open(index_dir / "matrix.pkl", "rb") as f:
+        matrix = pickle.load(f)
+    emb_path = index_dir / "embeddings.npy"
+    embeddings = np.load(emb_path) if emb_path.exists() else None
+    return RagIndex(chunks=chunks, vectorizer=vectorizer, matrix=matrix, embeddings=embeddings)
+
+
+def search(
+    query: str,
+    index: RagIndex,
+    top: int = 3,
+    rerank: bool = True,
+    pool: int = DEFAULT_POOL,
+    embedding_model: str = DEFAULT_EMBEDDING_MODEL,
+    cross_encoder_model: str = DEFAULT_CROSS_ENCODER_MODEL,
+) -> list:
+    """
+    Returns the top `top` chunks as a list of dicts (rank, source, text,
+    score, score_type, cosine), highest-scoring first.
+
+    rerank=True (default): stage 1 pools `pool` candidates from TF-IDF
+    cosine UNION dense-embedding similarity (if the index has embeddings --
+    plain TF-IDF pool otherwise), stage 2 reorders that pool with the
+    cross-encoder and returns its top `top` ("score_type": "rerank").
+    rerank=False: plain TF-IDF cosine ranking, no sentence-transformers model
+    load needed (still needs the 'rag' extra's scikit-learn for cosine_similarity
+    itself) -- useful as a baseline, or when only embeddings are unavailable
+    for this index but a scored ranking is still wanted.
+    """
+    try:
+        from sklearn.metrics.pairwise import cosine_similarity
+    except ImportError as _import_error:  # pragma: no cover -- only reachable without scikit-learn installed, which CI here always has
+        raise ImportError(_MISSING_RAG_EXTRA.format(_import_error)) from _import_error
+
+    query_vec = index.vectorizer.transform([query])
+    cosine_scores = cosine_similarity(query_vec, index.matrix)[0]
+    tfidf_order = cosine_scores.argsort()[::-1]
+
+    if rerank and index.embeddings is not None:
+        query_emb = _get_embedder(embedding_model).encode([query], normalize_embeddings=True)[0]
+        dense_scores = index.embeddings @ query_emb
+        dense_pool = dense_scores.argsort()[::-1][:pool]
+        candidate_idx = sorted(set(tfidf_order[:pool].tolist()) | set(dense_pool.tolist()))
+    elif rerank:
+        candidate_idx = tfidf_order[:pool].tolist()
+    else:
+        candidate_idx = []
+
+    if rerank and candidate_idx:
+        pairs = [(query, index.chunks[i]["text"][:1024]) for i in candidate_idx]
+        rerank_scores = _get_reranker(cross_encoder_model).predict(pairs)
+        order = rerank_scores.argsort()[::-1][:top]
+        top_idx = [candidate_idx[j] for j in order]
+        scores = {candidate_idx[j]: float(rerank_scores[j]) for j in order}
+        score_type = "rerank"
+    else:
+        top_idx = tfidf_order[:top].tolist()
+        scores = {i: float(cosine_scores[i]) for i in top_idx}
+        score_type = "cosine"
+
+    return [
+        {
+            "rank": rank,
+            "source": index.chunks[i]["source"],
+            "text": index.chunks[i]["text"],
+            "score": scores[i],
+            "score_type": score_type,
+            "cosine": float(cosine_scores[i]),
+        }
+        for rank, i in enumerate(top_idx, 1)
+    ]
+
+
+def search_exact(pattern: str, index: RagIndex, regex: bool = False, max_hits: int = 10, context: int = 300) -> list:
+    """Substring/regex search over an index's raw chunk text -- no
+    embedding, no reranker, no model download, so this needs neither the
+    'rag' extra nor a built index's embeddings (works even on an index
+    built with compute_embeddings=False).
+
+    Semantic search (search(), above) ranks by topical similarity, which
+    can bury a short, specific, load-bearing phrase (an exact clause, a
+    fixed parameter value, a named condition) under chunks that are
+    merely more topically central. Use this instead when you already know
+    roughly what wording you're looking for and semantic search isn't
+    surfacing it high enough.
+
+    regex=False (default) treats `pattern` as a literal, case-insensitive
+    substring (re.escape'd internally); regex=True treats it as a real
+    regular expression, case-sensitive, exactly as written. Stops after
+    `max_hits` matches (a `truncated` field on the last result marks this,
+    rather than silently returning a partial, unmarked list); `context`
+    characters of surrounding text are kept on each side of the match.
+
+    Returns a list of {source, chunk_index, match, snippet, start, end}
+    dicts, at most one per chunk -- the chunk's first match only, same as
+    the original quantumrag CLI this was ported from, not an exhaustive
+    enumeration of every occurrence within a chunk. Empty list (not an
+    error) if nothing matches.
+    """
+    flags = 0 if regex else re.IGNORECASE
+    compiled = re.compile(pattern if regex else re.escape(pattern), flags)
+    hits = []
+    for i, chunk in enumerate(index.chunks):
+        text = chunk["text"]
+        m = compiled.search(text)
+        if not m:
+            continue
+        lo = max(0, m.start() - context)
+        hi = min(len(text), m.end() + context)
+        snippet = text[lo:hi]
+        hits.append({
+            "source": chunk["source"],
+            "chunk_index": i,
+            "match": m.group(0),
+            "snippet": ("..." if lo > 0 else "") + snippet + ("..." if hi < len(text) else ""),
+            "start": m.start(),
+            "end": m.end(),
+        })
+        if len(hits) >= max_hits:
+            hits[-1]["truncated"] = True
+            break
+    return hits