sum-engine 0.1.0__py3-none-any.whl

internal/ensemble/epistemic_arbiter.py

@@ -0,0 +1,159 @@
+"""
+Epistemic Arbiter & Event Broadcaster — Wave Function Collapse Engine
+
+The Arbiter resolves Level 3 Curvature (semantic contradictions) by
+invoking an LLM judge to determine which conflicting fact survives.
+The EventBroadcaster streams the internal "thinking" process to the
+frontend via Server-Sent Events (SSE).
+
+Author: ototao
+License: Apache License 2.0
+"""
+
+import asyncio
+import logging
+from typing import Callable, Dict, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class EventBroadcaster:
+    """Streams internal mathematical thoughts to the frontend via SSE."""
+
+    def __init__(self):
+        self.queues: List[asyncio.Queue] = []
+
+    async def broadcast(self, message: str):
+        """Push a message to all connected SSE subscribers."""
+        logger.info("[KOS Telemetry] %s", message)
+        for queue in self.queues:
+            await queue.put(message)
+
+    def subscribe(self) -> asyncio.Queue:
+        """Create a new subscriber queue."""
+        q: asyncio.Queue = asyncio.Queue()
+        self.queues.append(q)
+        return q
+
+    def unsubscribe(self, queue: asyncio.Queue):
+        """Remove a subscriber queue."""
+        if queue in self.queues:
+            self.queues.remove(queue)
+
+
+# Global singleton — imported by quantum_router for SSE streaming
+kos_telemetry = EventBroadcaster()
+
+
+class EpistemicArbiter:
+    """
+    Resolves Level 3 Curvature (Semantic Contradictions).
+
+    Collapses the wave function of conflicting primes into
+    absolute truth by invoking an LLM judge.
+    """
+
+    def __init__(self, llm_judge: Callable):
+        self.judge = llm_judge  # async func(prompt: str) -> str
+
+    async def collapse_wave_function(
+        self, conflicts: List[Tuple[str, str, str, str]]
+    ) -> Dict[Tuple[str, str], str]:
+        """
+        Takes a list of conflicts: (subject, predicate, object_a, object_b).
+        Returns the winning mapping: {(subject, predicate): winning_object}.
+        """
+        resolutions: Dict[Tuple[str, str], str] = {}
+
+        for subject, predicate, obj_a, obj_b in conflicts:
+            await kos_telemetry.broadcast(
+                f"⚠️ Level 3 Curvature Detected: "
+                f"{subject} {predicate} [{obj_a} OR {obj_b}]"
+            )
+            await kos_telemetry.broadcast(
+                "🌀 Entering Epistemic Superposition..."
+            )
+
+            prompt = (
+                f"You are a strict logic arbiter. We have a contradiction "
+                f"regarding '{subject}'.\n"
+                f"Claim A: {subject} {predicate} {obj_a}\n"
+                f"Claim B: {subject} {predicate} {obj_b}\n"
+                f"Analyze standard logical precedence, general knowledge, "
+                f"or temporal recency, and return ONLY the correct object "
+                f"value. If tied, pick the most specific."
+            )
+
+            # Call the LLM Judge
+            winner = await self.judge(prompt)
+            winner_clean = winner.strip().lower()
+
+            # Fallback if the judge hallucinates an entirely new answer
+            if winner_clean not in [obj_a.lower(), obj_b.lower()]:
+                winner_clean = obj_a.lower()
+
+            resolutions[(subject, predicate)] = winner_clean
+            await kos_telemetry.broadcast(
+                f"⚡ Wave Function Collapsed: "
+                f"{subject} {predicate} → {winner_clean}"
+            )
+
+        return resolutions
+
+
+class DeterministicArbiter:
+    """
+    Deterministic contradiction resolution without LLM.
+
+    Resolves Level 3 Curvature using SHA-256 lexicographic ordering:
+    for each conflict (subject, predicate, obj_a, obj_b), the winner
+    is whichever object has the lower SHA-256 hash of
+    ``f"{subject}||{predicate}||{object}"``.
+
+    This guarantees:
+      - Identical resolution on every node (deterministic)
+      - No LLM cost or latency
+      - Consistent ordering regardless of minting order
+      - Reproducibility across runtimes (SHA-256 is universal)
+    """
+
+    @staticmethod
+    def _canonical_hash(subject: str, predicate: str, obj: str) -> str:
+        """SHA-256 of the canonical triplet key."""
+        import hashlib
+        return hashlib.sha256(
+            f"{subject}||{predicate}||{obj}".encode()
+        ).hexdigest()
+
+    async def collapse_wave_function(
+        self, conflicts: List[Tuple[str, str, str, str]]
+    ) -> Dict[Tuple[str, str], str]:
+        """
+        Resolve conflicts deterministically via SHA-256 ordering.
+
+        For each (subject, predicate, obj_a, obj_b), the object with
+        the lexicographically lower SHA-256 hash wins.
+        """
+        resolutions: Dict[Tuple[str, str], str] = {}
+
+        for subject, predicate, obj_a, obj_b in conflicts:
+            hash_a = self._canonical_hash(subject, predicate, obj_a)
+            hash_b = self._canonical_hash(subject, predicate, obj_b)
+
+            winner = obj_a if hash_a <= hash_b else obj_b
+
+            await kos_telemetry.broadcast(
+                f"⚠️ Level 3 Curvature: "
+                f"{subject} {predicate} [{obj_a} OR {obj_b}]"
+            )
+            await kos_telemetry.broadcast(
+                f"🔬 Deterministic Resolution: SHA-256({obj_a})={hash_a[:8]}… "
+                f"vs SHA-256({obj_b})={hash_b[:8]}…"
+            )
+            await kos_telemetry.broadcast(
+                f"⚡ Collapsed → {subject} {predicate} → {winner}"
+            )
+
+            resolutions[(subject, predicate)] = winner
+
+        return resolutions

internal/ensemble/epistemic_loop.py

@@ -0,0 +1,136 @@
+"""
+Epistemic Feedback Loop — "Tags to Tomes then Back"
+
+Governs the closed-loop extrapolation pipeline:
+    1. TOMES:  Generate narrative text from verified Gödel axioms.
+    2. TAGS:   Extract triplets from the narrative and re-encode as a
+               Gödel integer.
+    3. VERIFY: modulo check — ``global_state % generated_state == 0``.
+    4. DIAGNOSE: If verification fails, GCD-based hallucination isolation
+                 identifies the exact fabricated claims.
+    5. SELF-CORRECT: Feed hallucinated axioms back as strict negative
+                     constraints and re-generate.
+
+The loop refuses to return a string until it is *mathematically proven*
+to be a pure subset of the global truth.
+
+Author: ototao
+License: Apache License 2.0
+"""
+
+import logging
+from typing import Callable, Awaitable, List, Tuple, Dict, Any
+
+from internal.algorithms.semantic_arithmetic import GodelStateAlgebra
+
+logger = logging.getLogger(__name__)
+
+
+class QuantumExtrapolator:
+    """
+    Translates Gödel Integers (Tags) into Narrative Text (Tomes) and
+    verifies them mathematically by converting them back into Integers.
+
+    The extrapolation loop guarantees zero hallucination through an
+    unbreakable epistemic cage: no text is returned until
+    ``global_state % generated_state == 0``.
+    """
+
+    def __init__(
+        self,
+        godel_algebra: GodelStateAlgebra,
+        llm_generator: Callable[
+            [List[str], List[str]], Awaitable[str]
+        ],
+        llm_extractor: Callable[
+            [str], Awaitable[List[Tuple[str, str, str]]]
+        ],
+        max_retries: int = 3,
+    ):
+        """
+        Args:
+            godel_algebra:  A GodelStateAlgebra instance with the global
+                            truth already encoded.
+            llm_generator:  Async callable (axioms, negative_constraints) → text.
+            llm_extractor:  Async callable (text) → List[(subj, pred, obj)].
+            max_retries:    Maximum correction attempts before raising.
+        """
+        self.algebra = godel_algebra
+        self.generate_text = llm_generator
+        self.extract_triplets = llm_extractor
+        self.max_retries = max_retries
+
+    async def extrapolate_with_proof(
+        self,
+        global_state: int,
+        target_axioms: List[str],
+    ) -> str:
+        """
+        The Tags-to-Tomes pipeline.
+
+        Guarantees the output text strictly entails the global state with
+        zero hallucinations.
+
+        Args:
+            global_state:  The verified global Gödel integer.
+            target_axioms: Axiom key strings to expand into narrative.
+
+        Returns:
+            A narrative string that is *mathematically proven* to contain
+            only claims present in the global state.
+
+        Raises:
+            RuntimeError: If the LLM fails to self-correct within
+                          ``max_retries`` attempts.
+        """
+        negative_constraints: List[str] = []
+
+        for attempt in range(self.max_retries):
+            # ── 1. TOMES: Generate narrative from verified axioms ────
+            narrative = await self.generate_text(
+                target_axioms, negative_constraints
+            )
+
+            # ── 2. TAGS: Map narrative back to a Gödel integer ───────
+            extracted_triplets = await self.extract_triplets(narrative)
+
+            if not extracted_triplets:
+                negative_constraints.append(
+                    "Failed to extract any verifiable axioms. "
+                    "Be more explicit."
+                )
+                continue
+
+            generated_state = self.algebra.encode_chunk_state(
+                extracted_triplets
+            )
+
+            # ── 3. VERIFY: The Epistemic Hardware Filter ────────────
+            if self.algebra.verify_entailment(global_state, generated_state):
+                logger.info(
+                    "Mathematical Proof of Zero Hallucination achieved "
+                    "on attempt %d.",
+                    attempt + 1,
+                )
+                return narrative
+
+            # ── 4. DIAGNOSE: Isolate hallucinated primes via GCD ─────
+            hallucinations = self.algebra.isolate_hallucinations(
+                global_state, generated_state
+            )
+            logger.warning(
+                "Modulo check failed (attempt %d). "
+                "Hallucinations detected: %s",
+                attempt + 1,
+                hallucinations,
+            )
+
+            # ── 5. SELF-CORRECT: Feed exact errors back ──────────────
+            if hallucinations:
+                negative_constraints.extend(hallucinations)
+
+        raise RuntimeError(
+            f"Epistemic Failure: LLM failed to mathematically align "
+            f"after {self.max_retries} attempts. "
+            f"Residual hallucinations: {negative_constraints[-5:]}"
+        )

internal/ensemble/extraction_validator.py

@@ -0,0 +1,172 @@
+"""
+Extraction Validator — Structural Gate for LLM→Algebra Boundary
+
+Phase 19A: Validates, canonicalizes, and deduplicates extracted triplets
+BEFORE they enter the Gödel State Algebra. Malformed or underspecified
+outputs are rejected with audit reasons, not silently ingested.
+
+This is the system's immune system at the NLP boundary.
+
+Pipeline:
+    1. Structural validation (non-empty, length bounds, illegal chars)
+    2. Predicate canonicalization (synonym collapse)
+    3. Batch deduplication (identical triplets within one extraction)
+    4. Return accepted + rejected with audit trail
+
+Author: ototao
+License: Apache License 2.0
+"""
+
+import re
+import logging
+from dataclasses import dataclass, field
+from typing import List, Tuple, Optional
+
+from internal.algorithms.predicate_canon import canonicalize
+
+logger = logging.getLogger(__name__)
+
+# ── Constraints ───────────────────────────────────────────────────────
+
+MIN_FIELD_LENGTH = 2          # Single-char subjects/objects are garbage
+MAX_FIELD_LENGTH = 200        # Absurdly long strings indicate extraction failure
+CONTROL_CHAR_PATTERN = re.compile(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]')
+JSON_FRAGMENT_PATTERN = re.compile(r'[{}\[\]]')
+
+
+@dataclass
+class RejectedTriplet:
+    """A triplet that failed validation, with the reason why."""
+    subject: str
+    predicate: str
+    object_: str
+    reason: str
+
+
+@dataclass
+class ValidatedExtraction:
+    """Result of running extraction through the validation gate."""
+    accepted: List[Tuple[str, str, str]] = field(default_factory=list)
+    rejected: List[RejectedTriplet] = field(default_factory=list)
+
+    @property
+    def accepted_count(self) -> int:
+        return len(self.accepted)
+
+    @property
+    def rejected_count(self) -> int:
+        return len(self.rejected)
+
+    @property
+    def valid_schema_rate(self) -> float:
+        total = self.accepted_count + self.rejected_count
+        return self.accepted_count / total if total > 0 else 0.0
+
+
+class ExtractionValidator:
+    """
+    Structural gate between LLM extraction and Gödel algebra.
+
+    Validates each triplet, canonicalizes predicates, deduplicates
+    within a batch, and returns an auditable result.
+    """
+
+    def validate_field(self, value: str, field_name: str) -> Optional[str]:
+        """
+        Validate a single triplet field. Returns rejection reason or None.
+        """
+        if not value or not value.strip():
+            return f"{field_name} is empty"
+
+        stripped = value.strip()
+
+        if len(stripped) < MIN_FIELD_LENGTH:
+            return f"{field_name} too short ({len(stripped)} chars, min {MIN_FIELD_LENGTH})"
+
+        if len(stripped) > MAX_FIELD_LENGTH:
+            return f"{field_name} too long ({len(stripped)} chars, max {MAX_FIELD_LENGTH})"
+
+        if CONTROL_CHAR_PATTERN.search(stripped):
+            return f"{field_name} contains control characters"
+
+        if JSON_FRAGMENT_PATTERN.search(stripped) and len(stripped) < 10:
+            return f"{field_name} appears to be a JSON fragment"
+
+        return None
+
+    def validate_triplet(
+        self,
+        subject: str,
+        predicate: str,
+        object_: str,
+    ) -> Optional[str]:
+        """
+        Validate a full triplet. Returns rejection reason or None if valid.
+        """
+        for val, name in [
+            (subject, "subject"),
+            (predicate, "predicate"),
+            (object_, "object"),
+        ]:
+            reason = self.validate_field(val, name)
+            if reason:
+                return reason
+
+        return None
+
+    def validate_batch(
+        self,
+        triplets: List[Tuple[str, str, str]],
+        canonicalize_predicates: bool = True,
+    ) -> ValidatedExtraction:
+        """
+        Validate, canonicalize, and deduplicate a batch of extracted triplets.
+
+        Args:
+            triplets: Raw (subject, predicate, object) tuples from LLM.
+            canonicalize_predicates: If True, run predicate canonicalization.
+
+        Returns:
+            ValidatedExtraction with accepted and rejected lists.
+        """
+        result = ValidatedExtraction()
+        seen: set = set()
+
+        for s, p, o in triplets:
+            # Normalize
+            s_clean = s.strip().lower()
+            p_clean = p.strip().lower().replace(" ", "_")
+            o_clean = o.strip().lower()
+
+            # Structural validation
+            reason = self.validate_triplet(s_clean, p_clean, o_clean)
+            if reason:
+                result.rejected.append(
+                    RejectedTriplet(s_clean, p_clean, o_clean, reason)
+                )
+                continue
+
+            # Predicate canonicalization
+            if canonicalize_predicates:
+                p_clean = canonicalize(p_clean)
+
+            # Batch deduplication
+            key = (s_clean, p_clean, o_clean)
+            if key in seen:
+                result.rejected.append(
+                    RejectedTriplet(s_clean, p_clean, o_clean, "duplicate in batch")
+                )
+                continue
+
+            seen.add(key)
+            result.accepted.append((s_clean, p_clean, o_clean))
+
+        if result.rejected_count > 0:
+            logger.info(
+                "Extraction gate: %d accepted, %d rejected (%.0f%% valid)",
+                result.accepted_count,
+                result.rejected_count,
+                result.valid_schema_rate * 100,
+            )
+
+        return result

internal/ensemble/gauge_orchestrator.py

@@ -0,0 +1,150 @@
+"""
+Gauge-Theoretic Orchestrator — Commutativity Hierarchy Engine
+
+Implements Yaroslavtsev's three-level commutativity detection:
+  - Level 1 (Commutative): Independent facts, safe to merge in any order.
+  - Level 2 (Conditionally commutative): Same entity, different predicates.
+  - Level 3 (Curvature): Same entity, same predicate, different objects.
+    These MUST be serialized — triggers the EpistemicArbiter.
+
+Author: ototao
+License: Apache License 2.0
+"""
+
+import logging
+from enum import IntEnum
+from typing import Callable, List, Tuple, Optional
+
+import networkx as nx
+
+logger = logging.getLogger(__name__)
+
+
+class CommutativityLevel(IntEnum):
+    """Yaroslavtsev's Commutativity Hierarchy."""
+
+    L1_COMMUTATIVE = 1  # Independent facts — parallel merge safe
+    L2_CONDITIONAL = 2  # Same entity, different predicates
+    L3_CURVATURE = 3    # Same entity, same predicate, different objects
+
+
+class GaugeTheoreticOrchestrator:
+    """
+    Manages the merge of knowledge graph extractions according to
+    the Commutativity Hierarchy.
+
+    When Level 3 Curvature is detected, the ``arbitrate`` callback
+    (an ``EpistemicArbiter.collapse_wave_function``) is invoked to
+    select the winning fact.
+    """
+
+    def __init__(self, arbitrate_fn: Optional[Callable] = None):
+        self.arbitrate = arbitrate_fn  # async func(conflicts) -> resolutions
+
+    def detect_curvature(
+        self,
+        base_graph: nx.MultiDiGraph,
+        new_graph: nx.MultiDiGraph,
+    ) -> Tuple[CommutativityLevel, List[Tuple[str, str, str, str]]]:
+        """
+        Detect the commutativity level between two knowledge graphs.
+
+        Args:
+            base_graph: Existing knowledge graph.
+            new_graph:  Newly extracted graph.
+
+        Returns:
+            (level, conflicts) where conflicts is a list of
+            (subject, predicate, old_object, new_object) tuples.
+        """
+        conflicts: List[Tuple[str, str, str, str]] = []
+        max_level = CommutativityLevel.L1_COMMUTATIVE
+
+        # Build an index of (source, relation) -> target from the base graph
+        base_index: dict[Tuple[str, str], str] = {}
+        for src, tgt, data in base_graph.edges(data=True):
+            rel = data.get("relation", "related_to")
+            base_index[(src, rel)] = tgt
+
+        # Check new graph edges against the base index
+        for src, tgt, data in new_graph.edges(data=True):
+            rel = data.get("relation", "related_to")
+
+            if (src, rel) in base_index:
+                old_tgt = base_index[(src, rel)]
+                if old_tgt != tgt:
+                    # Level 3: Same subject + predicate, different object
+                    conflicts.append((src, rel, old_tgt, tgt))
+                    max_level = CommutativityLevel.L3_CURVATURE
+                # else: identical fact, no conflict
+            elif src in {s for s, _, _ in base_graph.edges(data=True)}:
+                # Level 2: Same entity, different predicates
+                if max_level < CommutativityLevel.L2_CONDITIONAL:
+                    max_level = CommutativityLevel.L2_CONDITIONAL
+
+        return max_level, conflicts
+
+    async def merge_extractions(
+        self,
+        base_graph: nx.MultiDiGraph,
+        new_graphs: List[nx.MultiDiGraph],
+    ) -> nx.MultiDiGraph:
+        """
+        Merge multiple extraction graphs into the base graph,
+        resolving Level 3 Curvature via arbitration.
+
+        Args:
+            base_graph: The canonical knowledge graph.
+            new_graphs: List of newly extracted graphs to merge.
+
+        Returns:
+            Merged graph with contradictions resolved.
+        """
+        merged = base_graph.copy()
+
+        for new_graph in new_graphs:
+            level, conflicts = self.detect_curvature(merged, new_graph)
+
+            if level == CommutativityLevel.L3_CURVATURE and conflicts:
+                if self.arbitrate:
+                    resolutions = await self.arbitrate(conflicts)
+                else:
+                    # Default: new information wins (recency bias)
+                    resolutions = {
+                        (subj, pred): new_obj
+                        for subj, pred, _old, new_obj in conflicts
+                    }
+
+                # Apply resolutions
+                for (subj, pred), winner in resolutions.items():
+                    # Remove conflicting edges
+                    edges_to_remove = []
+                    for u, v, key, data in merged.edges(
+                        keys=True, data=True
+                    ):
+                        if u == subj and data.get("relation") == pred:
+                            edges_to_remove.append((u, v, key))
+
+                    for u, v, key in edges_to_remove:
+                        merged.remove_edge(u, v, key=key)
+
+                    # Add the winner
+                    merged.add_edge(
+                        subj,
+                        winner,
+                        relation=pred,
+                        verified_curvature=True,
+                    )
+
+                    logger.info(
+                        "Curvature resolved: %s %s → %s", subj, pred, winner
+                    )
+
+            # Add all non-conflicting edges from new_graph
+            conflict_keys = {(s, p) for s, p, _, _ in conflicts}
+            for src, tgt, data in new_graph.edges(data=True):
+                rel = data.get("relation", "related_to")
+                if (src, rel) not in conflict_keys:
+                    merged.add_edge(src, tgt, **data)
+
+        return merged