cortexm 0.3.0__py3-none-any.whl

cortexm/cognition/analogy.py

@@ -0,0 +1,159 @@
+"""AnalogyDetector — finds structurally isomorphic domains via bipartite
+relation mapping.
+
+Fourth stage of the HMS cognition engine. Given two domains (sets of
+entities + relations), find an isomorphism between their relation
+graphs that maximizes structural overlap.
+
+Classic example from Hofstadter/Mitchell's Copycat:
+  "The atom is to the solar system as the cell is to the city."
+  The detector finds that the (nucleus, orbits, electron) relation
+  triple in atoms has the same SHAPE as (sun, orbits, planet) in solar
+  systems and (mayor, governs, citizen) in cities.
+
+For Context-M, we implement a simpler version: for each pair of
+relations (r_a, r_b) with the same fanout pattern across subjects,
+report an analogy. E.g.:
+  (father, male_parent) and (mother, female_parent) have identical
+  fanout → report analogy: father ≈ mother in shape (under sex-swap).
+
+This is the seed for cross-domain transfer learning — once we know
+the structural mapping, retrieval can find facts in domain A that
+have analogues in domain B.
+
+Hypotheses are emitted as derived facts:
+  (r_a, ANALOGOUS_TO, r_b) with confidence < 0.5
+
+So a reader can traverse the analogy graph to find structural
+equivalents across domains.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from cortexm.cognition.scanner import ScanResult
+from cortexm.trace.store import TraceStore
+from cortexm.util import iso, new_id
+
+
+# Edge kind used for analogy relations
+ANALOGOUS_TO = "ANALOGOUS_TO"
+
+
+@dataclass
+class Analogy:
+    """A structural analogy between two relations."""
+    relation_a: str
+    relation_b: str
+    shared_fanout: int = 0   # how many subjects share the fanout pattern
+    overlap_score: float = 0.0   # jaccard similarity of subject sets
+    confidence: float = 0.0
+
+
+@dataclass
+class AnalogyResult:
+    analogies: list[Analogy] = field(default_factory=list)
+    edges_added: int = 0
+    duration_ms: float = 0.0
+
+
+class AnalogyDetector:
+    """Finds structurally isomorphic relation pairs."""
+
+    def __init__(self, store: TraceStore,
+                 min_overlap: float = 0.40,
+                 min_support: int = 2) -> None:
+        self.store = store
+        self.min_overlap = min_overlap
+        self.min_support = min_support
+
+    def run(self, scan: ScanResult, *,
+            dry_run: bool = False,
+            commit_id: str | None = None,
+            user_id: str | None = None) -> AnalogyResult:
+        """Find analogies by comparing relation subject sets."""
+        import time
+        t0 = time.perf_counter()
+
+        # build a per-relation subject set
+        rel_subjects: dict[str, set[str]] = defaultdict(set)
+        where = "is_active=1 AND quarantined=0"
+        args: tuple = ()
+        if user_id is not None:
+            where += " AND user_id=?"
+            args = (user_id,)
+        rows = self.store.conn.execute(
+            f"SELECT relation, subject FROM facts WHERE {where}", args)
+        for r in rows:
+            rel_subjects[r[0]].add(r[1])
+
+        # for each pair of relations with sufficient support, compute
+        # the jaccard similarity of their subject sets
+        relations = list(rel_subjects.keys())
+        analogies: list[Analogy] = []
+        for i, ra in enumerate(relations):
+            sa = rel_subjects[ra]
+            if len(sa) < self.min_support:
+                continue
+            for rb in relations[i + 1:]:
+                sb = rel_subjects[rb]
+                if len(sb) < self.min_support:
+                    continue
+                inter = len(sa & sb)
+                if inter < self.min_support:
+                    continue
+                union = len(sa | sb)
+                if union == 0:
+                    continue
+                jac = inter / union
+                if jac < self.min_overlap:
+                    continue
+                analogies.append(Analogy(
+                    relation_a=ra,
+                    relation_b=rb,
+                    shared_fanout=inter,
+                    overlap_score=jac,
+                    confidence=min(0.49, 0.10 + 0.20 * jac),
+                ))
+
+        # emit edges as derived facts: (ra, ANALOGOUS_TO, rb)
+        edges_added = 0
+        if not dry_run and analogies:
+            ts = iso(_now())
+            for a in analogies:
+                fid = new_id()
+                self.store.conn.execute(
+                    "INSERT INTO facts "
+                    "(id, subject, relation, value, valid_from, tx_from, "
+                    " confidence, user_id, memory_type, is_derived, "
+                    " is_active, birth_commit, provenance) "
+                    "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                    (fid, a.relation_a, ANALOGOUS_TO, a.relation_b,
+                     ts, ts, a.confidence,
+                     user_id or "default", "long_term",
+                     1, 1, commit_id,
+                     json.dumps({
+                         "kind": "analogy",
+                         "overlap_score": round(a.overlap_score, 4),
+                         "shared_fanout": a.shared_fanout,
+                         "generated_by": "cognition.analogy",
+                     })))
+                edges_added += 1
+            if commit_id:
+                self.store.update_commit_n_facts(commit_id, edges_added)
+
+        return AnalogyResult(
+            analogies=analogies,
+            edges_added=edges_added,
+            duration_ms=(time.perf_counter() - t0) * 1000.0)
+
+
+def _now():
+    return datetime.now(timezone.utc)
+
+
+__all__ = ["AnalogyDetector", "Analogy", "AnalogyResult", "ANALOGOUS_TO"]

cortexm/cognition/engine.py

@@ -0,0 +1,204 @@
+"""CognitionEngine — orchestrates the 5-stage self-organization pipeline.
+
+Triggered from `cortexm consolidate` (or `Memory.consolidate()`) so
+the engine is deterministic, auditable, and never produces surprise
+writes in the foreground path. Each pass:
+
+  1. PatternScanner.run()       — surface structural regularities
+  2. AbstractionEngine.run()   — build prototype categories
+  3. GapDetector.run()         — find missing relations
+  4. HypothesisEngine.run()     — propose fillers for gaps
+  5. AnalogyDetector.run()      — find cross-domain analogies
+
+Output is committed as derived facts with confidence < 0.5 and tagged
+is_derived=1, so they don't pollute the active fact count and don't
+fire in retrieval unless explicitly promoted (via
+`Memory.promote_hypothesis(fact_id)`).
+
+The HYPOTHESIZED_BY edge kind is registered here so
+`cortexm.trace.edges.ALL_KINDS` includes it. PROMOTED_FROM is the
+inverse — when a hypothesis is confirmed by user input, the new fact
+points back to its hypothesis origin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from cortexm.cognition.scanner import PatternScanner, ScanResult
+from cortexm.cognition.abstraction import AbstractionEngine, AbstractionResult
+from cortexm.cognition.gaps import (
+    GapDetector, HypothesisEngine, GapResult, HypothesisResult, HYPOTHESIZED_BY)
+from cortexm.cognition.analogy import (
+    AnalogyDetector, AnalogyResult, ANALOGOUS_TO)
+from cortexm.trace.store import TraceStore
+
+
+# Edge kinds produced by the cognition engine. These are added to the
+# trace.edges vocabulary. We register them lazily on first cognition
+# pass so a Trace that never ran cognition doesn't see these kinds in
+# queries (avoiding schema pollution).
+PROMOTED_FROM = "PROMOTED_FROM"   # user-confirmed fact -> hypothesis origin
+ABSTRACTS = "ABSTRACTS"             # abstraction -> member
+INSTANTIATES = "INSTANTIATES"       # member -> abstraction
+
+
+@dataclass
+class CognitionReport:
+    """Full report of one cognition pass."""
+    scan: dict = field(default_factory=dict)
+    abstraction: dict = field(default_factory=dict)
+    gaps: dict = field(default_factory=dict)
+    hypotheses: dict = field(default_factory=dict)
+    analogies: dict = field(default_factory=dict)
+    commit_id: str | None = None
+    dry_run: bool = False
+    total_derived_facts: int = 0
+    duration_ms: float = 0.0
+
+
+class CognitionEngine:
+    """Orchestrates the 5-stage self-organization pipeline."""
+
+    def __init__(self, store: TraceStore, palace=None) -> None:
+        self.store = store
+        self.palace = palace
+        self.scanner = PatternScanner(store)
+        self.abstraction = AbstractionEngine(store)
+        self.gap_detector = GapDetector(store)
+        # pass palace for Hopfield cleanup path (currently not used
+        # by the simple strategies but the API accepts it)
+        self.hypothesis = HypothesisEngine(store, palace=palace)
+        self.analogy = AnalogyDetector(store)
+
+    def run(self, *,
+            dry_run: bool = False,
+            user_id: str | None = None) -> CognitionReport:
+        """Run the full 5-stage pipeline.
+
+        All writes happen inside a single commit if not dry_run.
+        Returns a CognitionReport with per-stage stats.
+        """
+        import time
+        t0 = time.perf_counter()
+
+        # if not dry_run, we expect the caller to have already started
+        # a batch + commit (consolidate() does this). We accept an
+        # optional commit_id from the caller via store._cognition_commit
+        # (stored as a session-level hint). If not present, we create
+        # our own commit.
+        own_commit = False
+        commit_id = None
+        if not dry_run:
+            try:
+                self.store.begin_batch()
+                commit_id = self.store.create_commit(
+                    "cognition: scan+abstract+gap+hypothesis+analogy",
+                    n_facts=0)
+                own_commit = True
+            except Exception:
+                # caller already in a batch — use their commit
+                commit_id = getattr(self.store, "_active_commit_id", None)
+
+        report = CognitionReport(dry_run=dry_run, commit_id=commit_id)
+
+        # 1. PatternScanner
+        scan = self.scanner.run(user_id=user_id)
+        report.scan = {
+            "patterns": len(scan.patterns),
+            "n_facts_scanned": scan.n_facts_scanned,
+            "n_relations": scan.n_relations,
+            "n_subjects": scan.n_subjects,
+            "n_values": scan.n_values,
+            "duration_ms": round(scan.duration_ms, 2),
+            "by_kind": _count_by_kind(scan.patterns),
+        }
+
+        # 2. AbstractionEngine
+        ab = self.abstraction.run(scan, dry_run=dry_run,
+                                    commit_id=commit_id, user_id=user_id)
+        report.abstraction = {
+            "abstractions": len(ab.abstractions),
+            "membership_edges_added": ab.membership_edges_added,
+            "duration_ms": round(ab.duration_ms, 2),
+        }
+
+        # 3. GapDetector
+        gaps = self.gap_detector.run(scan, user_id=user_id)
+        report.gaps = {
+            "gaps": len(gaps.gaps),
+            "n_subjects_compared": gaps.n_subjects_compared,
+            "duration_ms": round(gaps.duration_ms, 2),
+            "by_basis": _count_gaps_by_basis(gaps.gaps),
+        }
+
+        # 4. HypothesisEngine
+        hyp = self.hypothesis.run(gaps.gaps, dry_run=dry_run,
+                                    commit_id=commit_id, user_id=user_id)
+        report.hypotheses = {
+            "hypotheses": len(hyp.hypotheses),
+            "facts_added": hyp.facts_added,
+            "duration_ms": round(hyp.duration_ms, 2),
+        }
+
+        # 5. AnalogyDetector
+        ana = self.analogy.run(scan, dry_run=dry_run,
+                                 commit_id=commit_id, user_id=user_id)
+        report.analogies = {
+            "analogies": len(ana.analogies),
+            "edges_added": ana.edges_added,
+            "duration_ms": round(ana.duration_ms, 2),
+        }
+
+        report.total_derived_facts = (
+            ab.membership_edges_added
+            + hyp.facts_added
+            + ana.edges_added
+        )
+        report.duration_ms = (time.perf_counter() - t0) * 1000.0
+
+        if not dry_run and own_commit:
+            # update commit n_facts to the actual count we wrote
+            try:
+                self.store.update_commit_n_facts(
+                    commit_id, report.total_derived_facts)
+            except Exception:
+                pass
+            try:
+                self.store.end_batch()
+            except Exception:
+                pass
+
+        return report
+
+
+def run_cognition_pass(store: TraceStore, palace=None, *,
+                       dry_run: bool = False,
+                       user_id: str | None = None) -> CognitionReport:
+    """Convenience function: one-shot cognition pass on a TraceStore."""
+    return CognitionEngine(store, palace=palace).run(
+        dry_run=dry_run, user_id=user_id)
+
+
+def _count_by_kind(patterns) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for p in patterns:
+        out[p.kind] = out.get(p.kind, 0) + 1
+    return out
+
+
+def _count_gaps_by_basis(gaps) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for g in gaps:
+        out[g.basis] = out.get(g.basis, 0) + 1
+    return out
+
+
+__all__ = [
+    "CognitionEngine", "CognitionReport",
+    "run_cognition_pass",
+    "HYPOTHESIZED_BY", "PROMOTED_FROM",
+    "ABSTRACTS", "INSTANTIATES",
+    "ANALOGOUS_TO",
+]