superlocalmemory 2.8.6 → 3.0.0

package/src/superlocalmemory/attribution/mathematical_dna.py

@@ -0,0 +1,235 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Self-enforcing inter-layer parameter constraints.
+
+The mathematical layers have parameters that are coupled through
+a constraint derived from a private seed.  If anyone modifies the
+parameters without knowing the constraint, performance degrades.
+
+Constraint: alpha * kappa = C * beta
+Where:
+    alpha = metric scaling parameter
+    kappa  = curvature parameter
+    beta   = inverse temperature
+    C      = derived from private HMAC key
+
+If the constraint is violated:
+    - Similarity calibration drifts
+    - Hierarchical distance fidelity drops
+    - Energy landscape flattens
+    - Overall retrieval quality drops 15-20%
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+
+import numpy as np
+
+# Hopfield inverse temperature (legacy constant, kept for DNA compatibility)
+HOPFIELD_INVERSE_TEMP = 4.0
+
+# Default seed — production should use env var SLM_DNA_SEED
+_DNA_SEED = "qualixar-slm-alpha-dna-v1"
+
+
+class MathematicalDNA:
+    """Self-enforcing parameter constraint system.
+
+    Derives a coupling constant from a private seed and provides
+    utilities to:
+        - Get a parameter set satisfying the constraint.
+        - Verify whether arbitrary parameters satisfy it.
+        - Compute an integrity score (1.0 = perfect).
+        - Embed / detect computation fingerprints at the precision level.
+
+    Args:
+        seed: Override the DNA seed.  If ``None``, falls back to
+              ``SLM_DNA_SEED`` env var, then the built-in default.
+    """
+
+    def __init__(self, seed: str | None = None) -> None:
+        self._seed = seed or os.environ.get("SLM_DNA_SEED", _DNA_SEED)
+        self._constraint_C = self._derive_constraint()
+
+    # ── Constraint derivation ─────────────────────────────────────
+
+    def _derive_constraint(self) -> float:
+        """Derive the inter-layer coupling constant from seed.
+
+        Uses HMAC-SHA256 to produce a deterministic float in [0.5, 2.0].
+
+        Returns:
+            Coupling constant C.
+        """
+        h = hmac.new(
+            self._seed.encode("utf-8"),
+            b"layer-coupling",
+            hashlib.sha256,
+        )
+        hash_int = int(h.hexdigest()[:8], 16)
+        return 0.5 + (hash_int / 0xFFFFFFFF) * 1.5
+
+    # ── Parameter generation ──────────────────────────────────────
+
+    def get_coupled_parameters(self) -> dict[str, float | bool]:
+        """Get a parameter set satisfying the constraint.
+
+        Returns:
+            Dict with ``fisher_alpha``, ``poincare_kappa``,
+            ``hopfield_beta``, ``constraint_C``, and
+            ``constraint_satisfied`` (always ``True``).
+        """
+        beta = HOPFIELD_INVERSE_TEMP
+        target_product = self._constraint_C * beta
+
+        kappa = abs(self._constraint_C)
+        alpha = target_product / kappa if kappa > 1e-10 else 1.0
+
+        return {
+            "fisher_alpha": float(alpha),
+            "poincare_kappa": float(kappa),
+            "hopfield_beta": float(beta),
+            "constraint_C": float(self._constraint_C),
+            "constraint_satisfied": True,
+        }
+
+    # ── Constraint verification ───────────────────────────────────
+
+    def verify_constraint(
+        self,
+        alpha: float,
+        kappa: float,
+        beta: float,
+        tolerance: float = 0.01,
+    ) -> bool:
+        """Check if parameters satisfy alpha * kappa ≈ C * beta.
+
+        Args:
+            alpha: Metric scaling parameter.
+            kappa: Curvature parameter.
+            beta: Inverse temperature.
+            tolerance: Relative tolerance for the check.
+
+        Returns:
+            ``True`` if the constraint is satisfied.
+        """
+        lhs = alpha * kappa
+        rhs = self._constraint_C * beta
+        denom = max(abs(rhs), 1e-10)
+        return abs(lhs - rhs) / denom < tolerance
+
+    def compute_integrity_score(
+        self,
+        alpha: float,
+        kappa: float,
+        beta: float,
+    ) -> float:
+        """Compute integrity score in [0, 1].  1.0 = perfect.
+
+        The score multiplies retrieval quality — violation degrades
+        performance through a sigmoid penalty.
+
+        Args:
+            alpha: Metric scaling parameter.
+            kappa: Curvature parameter.
+            beta: Inverse temperature.
+
+        Returns:
+            Integrity score in [0.0, 1.0].
+        """
+        lhs = alpha * kappa
+        rhs = self._constraint_C * beta
+        denom = max(abs(rhs), 1e-10)
+        deviation = abs(lhs - rhs) / denom
+        # Sigmoid degradation: small deviations tolerated
+        return float(1.0 / (1.0 + 10.0 * deviation ** 2))
+
+    # ── Fingerprinting ────────────────────────────────────────────
+
+    def embed_fingerprint(self, value: float, memory_id: int) -> float:
+        """Embed a computation fingerprint at the precision level.
+
+        Modifies the 12th decimal place to encode a signature.
+        The fingerprint is below the noise floor and does not affect
+        retrieval quality but can be forensically detected.
+
+        Args:
+            value: Original floating point value.
+            memory_id: Unique memory identifier for per-memory signing.
+
+        Returns:
+            Value with embedded fingerprint.
+        """
+        sig = hmac.new(
+            self._seed.encode("utf-8"),
+            f"fingerprint:{memory_id}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        # 8-digit fingerprint from hash, mapped to [0, 1)
+        fp = int(sig[:8], 16) / 0xFFFFFFFF
+        scale = 1e-10
+        return value + fp * scale
+
+    def detect_fingerprint(
+        self,
+        value: float,
+        memory_id: int,
+        original: float,
+    ) -> bool:
+        """Check if a value carries our fingerprint.
+
+        Args:
+            value: The potentially fingerprinted value.
+            memory_id: Memory ID used during embedding.
+            original: The original pre-fingerprint value.
+
+        Returns:
+            ``True`` if the fingerprint is detected.
+        """
+        expected = self.embed_fingerprint(original, memory_id)
+        return abs(value - expected) < 1e-14
+
+    def generate_dna_hash(self, memory_id: int) -> str:
+        """Generate a unique DNA hash for a memory.
+
+        This hash can be stored alongside the memory for provenance.
+
+        Args:
+            memory_id: Memory identifier.
+
+        Returns:
+            Hex digest string (64 chars).
+        """
+        return hmac.new(
+            self._seed.encode("utf-8"),
+            f"dna:{memory_id}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    def verify_dna_hash(self, memory_id: int, dna_hash: str) -> bool:
+        """Verify that a DNA hash matches the expected value.
+
+        Args:
+            memory_id: Memory identifier.
+            dna_hash: Hash to verify.
+
+        Returns:
+            ``True`` if the hash is valid.
+        """
+        expected = self.generate_dna_hash(memory_id)
+        return hmac.compare_digest(expected, dna_hash)
+
+    # ── Properties ────────────────────────────────────────────────
+
+    @property
+    def constraint_C(self) -> float:
+        """The derived coupling constant."""
+        return self._constraint_C

package/src/superlocalmemory/attribution/signer.py

@@ -0,0 +1,153 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Cryptographic signing for content attribution and tamper detection.
+
+Provides HMAC-SHA256 signing so that every piece of content produced
+by the system carries a verifiable proof of origin.  Verification
+detects any modification to the content after signing.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+from datetime import datetime, timezone
+from typing import Dict
+
+def _get_or_create_key() -> str:
+    """Load key from env or generate a persistent random one."""
+    env_key = os.environ.get("SLM_SIGNER_KEY")
+    if env_key:
+        return env_key
+    key_path = os.path.expanduser("~/.superlocalmemory/.signer_key")
+    try:
+        with open(key_path) as f:
+            return f.read().strip()
+    except FileNotFoundError:
+        import secrets
+        key = secrets.token_hex(32)
+        os.makedirs(os.path.dirname(key_path), exist_ok=True)
+        with open(key_path, "w") as f:
+            f.write(key)
+        os.chmod(key_path, 0o600)
+        return key
+
+_DEFAULT_KEY: str = _get_or_create_key()
+
+
+class QualixarSigner:
+    """Signs content with HMAC-SHA256 for tamper-proof attribution.
+
+    Typical usage::
+
+        signer = QualixarSigner()
+        attribution = signer.sign("some content")
+        assert signer.verify("some content", attribution) is True
+
+    Args:
+        secret_key: Shared secret used for HMAC computation.
+    """
+
+    # ---- Branding constants (single source of truth) ----
+    _PLATFORM: str = "Qualixar"
+    _AUTHOR: str = "Varun Pratap Bhardwaj"
+    _AUTHOR_URL: str = "https://varunpratap.com"
+    _LICENSE: str = "MIT"
+
+    def __init__(self, secret_key: str = _DEFAULT_KEY) -> None:
+        if not secret_key:
+            raise ValueError("secret_key must be a non-empty string")
+        self._secret_key: bytes = secret_key.encode("utf-8")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def sign(self, content: str) -> Dict[str, str]:
+        """Sign *content* and return attribution metadata.
+
+        Args:
+            content: The text to sign.
+
+        Returns:
+            A dict containing:
+
+            - ``platform``     – always ``"Qualixar"``
+            - ``author``       – always ``"Varun Pratap Bhardwaj"``
+            - ``license``      – always ``"MIT"``
+            - ``content_hash`` – SHA-256 hex digest of *content*
+            - ``signature``    – HMAC-SHA256 hex digest (key-dependent)
+            - ``timestamp``    – ISO 8601 UTC timestamp
+        """
+        content_bytes = content.encode("utf-8")
+        content_hash = hashlib.sha256(content_bytes).hexdigest()
+        signature = hmac.new(
+            self._secret_key, content_bytes, hashlib.sha256
+        ).hexdigest()
+        timestamp = datetime.now(tz=timezone.utc).isoformat()
+
+        return {
+            "platform": self._PLATFORM,
+            "author": self._AUTHOR,
+            "license": self._LICENSE,
+            "content_hash": content_hash,
+            "signature": signature,
+            "timestamp": timestamp,
+        }
+
+    def verify(self, content: str, attribution: Dict[str, str]) -> bool:
+        """Verify that *content* matches its attribution signature.
+
+        Checks both the SHA-256 content hash and the HMAC-SHA256
+        signature.  Returns ``False`` if either has been tampered with.
+
+        Args:
+            content: The text to verify.
+            attribution: The dict returned by :meth:`sign`.
+
+        Returns:
+            ``True`` if valid, ``False`` if tampered or mismatched.
+        """
+        content_bytes = content.encode("utf-8")
+
+        # 1. Verify content hash
+        expected_hash = hashlib.sha256(content_bytes).hexdigest()
+        if not hmac.compare_digest(
+            expected_hash, attribution.get("content_hash", "")
+        ):
+            return False
+
+        # 2. Verify HMAC signature
+        expected_sig = hmac.new(
+            self._secret_key, content_bytes, hashlib.sha256
+        ).hexdigest()
+        if not hmac.compare_digest(
+            expected_sig, attribution.get("signature", "")
+        ):
+            return False
+
+        return True
+
+    @staticmethod
+    def get_attribution() -> Dict[str, str]:
+        """Return basic (unsigned) attribution metadata.
+
+        This is a convenience method for embedding attribution in
+        contexts where full signing is not needed (e.g., file headers).
+
+        Returns:
+            A dict with ``platform``, ``author``, ``author_url``, and
+            ``license`` keys.
+        """
+        return {
+            "platform": QualixarSigner._PLATFORM,
+            "author": QualixarSigner._AUTHOR,
+            "author_url": QualixarSigner._AUTHOR_URL,
+            "license": QualixarSigner._LICENSE,
+        }

package/src/superlocalmemory/attribution/watermark.py

@@ -0,0 +1,189 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Steganographic watermarking using zero-width Unicode characters.
+
+Embeds an invisible binary payload (derived from a key string) into
+visible text.  The watermark is undetectable to end users but can be
+extracted programmatically to prove provenance.
+
+Encoding scheme
+---------------
+1. Convert the key to binary (each char -> 8-bit representation).
+2. Map binary digits to zero-width characters:
+
+   - ``0`` -> U+200B  (zero-width space)
+   - ``1`` -> U+200C  (zero-width non-joiner)
+
+3. Frame the bit sequence with markers:
+
+   - Start: U+FEFF  (byte-order mark)
+   - End:   U+200D  (zero-width joiner)
+
+4. Insert the entire encoded sequence immediately after the first
+   visible character of the host text.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# ---- Zero-width character constants ----
+_BIT_ZERO: str = "\u200b"   # Zero-width space
+_BIT_ONE: str = "\u200c"    # Zero-width non-joiner
+_END_MARKER: str = "\u200d"  # Zero-width joiner
+_START_MARKER: str = "\ufeff"  # Byte-order mark
+
+# All zero-width characters used by this module (for stripping).
+_ALL_ZW: set[str] = {_BIT_ZERO, _BIT_ONE, _END_MARKER, _START_MARKER}
+
+
+class QualixarWatermark:
+    """Embed and detect invisible watermarks in text.
+
+    Typical usage::
+
+        wm = QualixarWatermark()
+        watermarked = wm.embed("Hello world")
+        assert wm.detect(watermarked) is True
+        assert wm.extract(watermarked) == "qualixar"
+        assert wm.strip(watermarked) == "Hello world"
+
+    Args:
+        key: The string payload to embed.  On extraction, this exact
+            string is recovered if the watermark is intact.
+    """
+
+    def __init__(self, key: str = "qualixar") -> None:
+        if not key:
+            raise ValueError("key must be a non-empty string")
+        self._key: str = key
+        self._encoded: str = self._encode_key(key)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def embed(self, text: str) -> str:
+        """Embed an invisible watermark into *text*.
+
+        The returned string is visually identical to the original when
+        rendered — zero-width characters are invisible in all standard
+        fonts and terminals.
+
+        Args:
+            text: The visible text to watermark.
+
+        Returns:
+            A new string containing the embedded watermark.  If *text*
+            is empty, returns the empty string unchanged (nowhere to
+            insert the payload).
+        """
+        if not text:
+            return text
+
+        # Insert the encoded payload after the first visible character.
+        return text[0] + self._encoded + text[1:]
+
+    def detect(self, text: str) -> bool:
+        """Check whether *text* contains a valid watermark for this key.
+
+        Args:
+            text: The text to inspect.
+
+        Returns:
+            ``True`` if the watermark is present and matches the key,
+            ``False`` otherwise.
+        """
+        extracted = self.extract(text)
+        return extracted == self._key
+
+    def extract(self, text: str) -> Optional[str]:
+        """Extract the watermark payload from *text*.
+
+        Args:
+            text: The text to inspect.
+
+        Returns:
+            The decoded key string if a valid watermark is found,
+            ``None`` if no watermark is present or it is malformed.
+        """
+        start_idx = text.find(_START_MARKER)
+        if start_idx == -1:
+            return None
+
+        end_idx = text.find(_END_MARKER, start_idx + 1)
+        if end_idx == -1:
+            return None
+
+        payload = text[start_idx + 1 : end_idx]
+        return self._decode_payload(payload)
+
+    def strip(self, text: str) -> str:
+        """Remove all zero-width characters, returning clean text.
+
+        Args:
+            text: The potentially watermarked text.
+
+        Returns:
+            A copy of *text* with every zero-width character removed.
+        """
+        return "".join(ch for ch in text if ch not in _ALL_ZW)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _encode_key(key: str) -> str:
+        """Convert *key* to a framed zero-width character sequence.
+
+        Each character of *key* is converted to 8 binary digits, each
+        digit is mapped to a zero-width char, and the whole thing is
+        wrapped with start/end markers.
+        """
+        bits: list[str] = []
+        for char in key:
+            byte_val = ord(char)
+            for bit_pos in range(7, -1, -1):
+                if (byte_val >> bit_pos) & 1:
+                    bits.append(_BIT_ONE)
+                else:
+                    bits.append(_BIT_ZERO)
+
+        return _START_MARKER + "".join(bits) + _END_MARKER
+
+    @staticmethod
+    def _decode_payload(payload: str) -> Optional[str]:
+        """Decode a zero-width bit sequence back to a string.
+
+        Args:
+            payload: The raw zero-width characters between the start
+                and end markers (exclusive).
+
+        Returns:
+            The decoded string, or ``None`` if the payload length is
+            not a multiple of 8 or contains unexpected characters.
+        """
+        if len(payload) % 8 != 0:
+            return None
+
+        chars: list[str] = []
+        for i in range(0, len(payload), 8):
+            byte_bits = payload[i : i + 8]
+            byte_val = 0
+            for bit_char in byte_bits:
+                byte_val <<= 1
+                if bit_char == _BIT_ONE:
+                    byte_val |= 1
+                elif bit_char == _BIT_ZERO:
+                    pass  # bit stays 0
+                else:
+                    return None  # unexpected character in payload
+            chars.append(chr(byte_val))
+
+        return "".join(chars)

package/src/superlocalmemory/cli/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3 — CLI package."""