topologist 0.1.0__py3-none-any.whl

topologist/__init__.py

@@ -0,0 +1,17 @@
+"""Topologist: hyperdimensional neuro-symbolic topology engine."""
+
+from topologist.config import TopologistConfig
+from topologist.engine import Topologist
+from topologist.hdc import HyperVectorSpace
+from topologist.models import EdgeRecord, NodeRecord, ReasoningRule
+
+__all__ = [
+    "Topologist",
+    "TopologistConfig",
+    "HyperVectorSpace",
+    "NodeRecord",
+    "EdgeRecord",
+    "ReasoningRule",
+]
+
+__version__ = "0.1.0"

topologist/cli.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from topologist.engine import Topologist
+from topologist.models import ReasoningRule
+from topologist.visualization import export_mermaid
+
+app = typer.Typer(help="Topologist CLI")
+console = Console()
+
+
+@app.command()
+def demo(output: Path = Path("topology.json")) -> None:
+    """Create a demo hyperdimensional neuro-symbolic topology."""
+    topo = Topologist()
+    topo.add_node("Neuron", "biological_system")
+    topo.add_node("Synapse", "biological_system")
+    topo.add_node("Memory", "cognitive_system")
+    topo.add_node("HDC", "computational_model")
+    topo.add_node("KnowledgeGraph", "symbolic_model")
+    topo.add_node("Reasoning", "cognitive_process")
+    topo.add_edge("Neuron", "connects_to", "Synapse", confidence=0.95)
+    topo.add_edge("Synapse", "supports", "Memory", confidence=0.90)
+    topo.add_edge("HDC", "models", "Memory", confidence=0.85)
+    topo.add_edge("KnowledgeGraph", "supports", "Reasoning", confidence=0.92)
+    topo.add_edge("HDC", "enhances", "KnowledgeGraph", confidence=0.80)
+    topo.add_edge("Reasoning", "uses", "Memory", confidence=0.88)
+    topo.apply_rule(
+        ReasoningRule(
+            relation_a="connects_to",
+            relation_b="supports",
+            inferred_relation="indirectly_supports",
+            min_confidence=0.5,
+        )
+    )
+    topo.update_global_state(take_snapshot=True)
+    topo.save(output)
+    console.print(f"[green]Saved demo topology to {output}[/green]")
+
+
+@app.command()
+def inspect(path: Path) -> None:
+    """Print summary metrics for a saved topology."""
+    topo = Topologist.load(path)
+    table = Table(title="Topologist Summary")
+    table.add_column("Metric")
+    table.add_column("Value")
+    table.add_row("Nodes", str(topo.graph.number_of_nodes()))
+    table.add_row("Edges", str(topo.graph.number_of_edges()))
+    table.add_row("Communities", json.dumps(topo.communities()))
+    table.add_row("Drift", f"{topo.topology_drift():.4f}")
+    console.print(table)
+
+
+@app.command()
+def mermaid(path: Path, output: Path = Path("topology.mmd")) -> None:
+    """Export a saved topology as Mermaid."""
+    topo = Topologist.load(path)
+    export_mermaid(topo, output)
+    console.print(f"[green]Saved Mermaid graph to {output}[/green]")
+
+
+if __name__ == "__main__":
+    app()

topologist/config.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class TopologistConfig(BaseModel):
+    """Runtime configuration for the topology engine."""
+
+    model_config = ConfigDict(frozen=True)
+
+    dim: int = Field(default=10_000, ge=128, description="Hypervector dimensionality.")
+    seed: int = Field(default=42, description="Random seed for reproducible item memory.")
+    similarity_floor: float = Field(default=-1.0, ge=-1.0, le=1.0)
+    anomaly_threshold: float = Field(default=0.85, ge=0.0, le=2.0)
+    decay_rate: float = Field(default=0.98, gt=0.0, le=1.0)
+    max_snapshots: int = Field(default=100, ge=1)
+    default_confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    default_weight: float = Field(default=1.0, ge=0.0)

topologist/engine.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, cast
+
+import networkx as nx
+import numpy as np
+
+from topologist.config import TopologistConfig
+from topologist.exceptions import NodeNotFoundError, PersistenceError
+from topologist.hdc import BipolarVector, HyperVectorSpace
+from topologist.models import EdgeRecord, NodeRecord, ReasoningRule
+
+logger = logging.getLogger(__name__)
+
+
+class Topologist:
+    """Production-oriented hyperdimensional neuro-symbolic topology engine."""
+
+    def __init__(self, config: TopologistConfig | None = None) -> None:
+        self.config = config or TopologistConfig()
+        self.hdc = HyperVectorSpace(dim=self.config.dim, seed=self.config.seed)
+        self.graph: nx.MultiDiGraph = nx.MultiDiGraph()
+        self.global_state: BipolarVector | None = None
+        self.snapshots: list[BipolarVector] = []
+
+    # -----------------------------
+    # Node and edge mutation
+    # -----------------------------
+
+    def add_node(self, name: str, kind: str = "concept", **metadata: Any) -> None:
+        record = NodeRecord(name=name, kind=kind, metadata=metadata)
+        name_hv = self.hdc.get(f"node::{record.name}")
+        kind_hv = self.hdc.get(f"kind::{record.kind}")
+        hv = self.hdc.bind(kind_hv, name_hv)
+        self.graph.add_node(
+            record.name,
+            kind=record.kind,
+            metadata=record.metadata,
+            name_hv=name_hv,
+            kind_hv=kind_hv,
+            hv=hv,
+        )
+        self.global_state = None
+        logger.debug("Added node %s kind=%s", record.name, record.kind)
+
+    def add_edge(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        weight: float | None = None,
+        confidence: float | None = None,
+        **metadata: Any,
+    ) -> bool:
+        record = EdgeRecord(
+            source=source,
+            relation=relation,
+            target=target,
+            weight=self.config.default_weight if weight is None else weight,
+            confidence=self.config.default_confidence if confidence is None else confidence,
+            metadata=metadata,
+        )
+        if record.source not in self.graph:
+            self.add_node(record.source)
+        if record.target not in self.graph:
+            self.add_node(record.target)
+        if self._has_edge(
+            record.source,
+            record.relation,
+            record.target,
+            record.weight,
+            record.confidence,
+            record.metadata,
+        ):
+            self._update_edge_confidence(
+                record.source,
+                record.target,
+                record.relation,
+                record.confidence,
+            )
+            logger.debug(
+                "Updated confidence for edge %s --%s--> %s to %.3f",
+                record.source,
+                record.relation,
+                record.target,
+                record.confidence,
+            )
+            return False
+        hv = self.hdc.encode_relation(record.source, record.relation, record.target)
+        self.graph.add_edge(
+            record.source,
+            record.target,
+            relation=record.relation,
+            weight=record.weight,
+            confidence=record.confidence,
+            metadata=record.metadata,
+            hv=hv,
+        )
+        self.global_state = None
+        logger.debug(
+            "Added edge %s --%s--> %s confidence=%.3f",
+            record.source,
+            record.relation,
+            record.target,
+            record.confidence,
+        )
+        return True
+
+    def remove_node(self, name: str) -> None:
+        if name not in self.graph:
+            raise NodeNotFoundError(f"node not found: {name}")
+        self.graph.remove_node(name)
+        self.global_state = None
+
+    def _has_edge(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        weight: float,
+        confidence: float,
+        metadata: dict[str, Any],
+    ) -> bool:
+        """Check if an edge exists by symbolic key (source, relation, target).
+        For inferred edges, also match rule identity if present.
+        """
+        edge_data = self.graph.get_edge_data(source, target, default={})
+        for data in edge_data.values():
+            if data.get("relation") != relation:
+                continue
+            if not metadata and not data.get("metadata"):
+                return True
+            if metadata and data.get("metadata"):
+                existing_rule = data.get("metadata", {}).get("rule")
+                new_rule = metadata.get("rule")
+                if existing_rule == new_rule:
+                    return True
+        return False
+    
+    def _update_edge_confidence(
+        self,
+        source: str,
+        target: str,
+        relation: str,
+        new_confidence: float,
+    ) -> None:
+        """Update an existing edge's confidence to the max of current and new."""
+        edge_data = self.graph.get_edge_data(source, target, default={})
+        for data in edge_data.values():
+            if data.get("relation") == relation:
+                data["confidence"] = max(float(data.get("confidence", 1.0)), new_confidence)
+                self.global_state = None
+                return
+
+    # -----------------------------
+    # HDC state and snapshots
+    # -----------------------------
+
+    def update_global_state(self, take_snapshot: bool = False) -> BipolarVector:
+        vectors: list[BipolarVector] = []
+        for _, data in self.graph.nodes(data=True):
+            # include typed node vector (already kind-bound)
+            vectors.append(data["hv"])
+        for _, _, data in self.graph.edges(data=True):
+            # incorporate confidence into the edge vector so confidence decay
+            # affects the global topology memory. We quantize confidence to
+            # a single decimal to reduce item-memory growth.
+            edge_hv = data.get("hv")
+            try:
+                conf = float(data.get("confidence", 1.0))
+            except Exception:
+                conf = 1.0
+            # encode confidence as a continuous permuted vector
+            conf_hv = self.hdc.encode_confidence(conf)
+            vectors.append(self.hdc.bind(edge_hv, conf_hv))
+        self.global_state = self.hdc.bundle(vectors)
+        if take_snapshot:
+            self.snapshots.append(self.global_state.copy())
+            self.snapshots = self.snapshots[-self.config.max_snapshots :]
+        return self.global_state
+
+    def state_similarity(self, other: "Topologist") -> float:
+        left = self.global_state if self.global_state is not None else self.update_global_state()
+        right = other.global_state if other.global_state is not None else other.update_global_state()
+        return self.hdc.similarity(left, right)
+
+    def topology_drift(self) -> float:
+        if len(self.snapshots) < 2:
+            return 0.0
+        return 1.0 - self.hdc.similarity(self.snapshots[-2], self.snapshots[-1])
+
+    # -----------------------------
+    # Retrieval and reasoning
+    # -----------------------------
+
+    def nearest_nodes(self, query: str, top_k: int = 5) -> list[tuple[str, float]]:
+        query_name_hv = self.hdc.get(f"node::{query}")
+        scores = []
+        for node, data in self.graph.nodes(data=True):
+            name_hv = data.get("name_hv", data["hv"])
+            typed_hv = data.get("hv", name_hv)
+            score = max(
+                self.hdc.similarity(query_name_hv, name_hv),
+                self.hdc.similarity(query_name_hv, typed_hv),
+            )
+            if score >= self.config.similarity_floor:
+                scores.append((node, score))
+        return sorted(scores, key=lambda item: item[1], reverse=True)[:top_k]
+
+    def neighbors(self, node: str) -> list[dict[str, Any]]:
+        if node not in self.graph:
+            raise NodeNotFoundError(f"node not found: {node}")
+        return [
+            {
+                "source": source,
+                "relation": data["relation"],
+                "target": target,
+                "weight": data.get("weight", 1.0),
+                "confidence": data.get("confidence", 1.0),
+                "metadata": data.get("metadata", {}),
+            }
+            for source, target, data in self.graph.out_edges(node, data=True)
+        ]
+
+    def apply_rule(self, rule: ReasoningRule) -> int:
+        proposed: list[tuple[str, str, str, float]] = []
+        for a, b, data_ab in self.graph.edges(data=True):
+            if data_ab.get("relation") != rule.relation_a:
+                continue
+            for _, c, data_bc in self.graph.out_edges(b, data=True):
+                if data_bc.get("relation") != rule.relation_b:
+                    continue
+                confidence = data_ab.get("confidence", 1.0) * data_bc.get("confidence", 1.0)
+                if confidence >= rule.min_confidence:
+                    proposed.append((a, rule.inferred_relation, c, confidence))
+        created = 0
+        for source, relation, target, confidence in proposed:
+            if self.add_edge(
+                source,
+                relation,
+                target,
+                confidence=confidence,
+                inferred=True,
+                rule=rule.model_dump(),
+            ):
+                created += 1
+        return created
+
+    def apply_rules(self, rules: list[ReasoningRule]) -> int:
+        return sum(self.apply_rule(rule) for rule in rules)
+
+    # -----------------------------
+    # Topological analytics
+    # -----------------------------
+
+    def centrality(self) -> dict[str, float]:
+        simple = nx.DiGraph()
+        for source, target, data in self.graph.edges(data=True):
+            simple.add_edge(source, target, weight=data.get("weight", 1.0))
+        if simple.number_of_nodes() == 0:
+            return {}
+        return cast(dict[str, float], nx.pagerank(simple, weight="weight"))
+
+    def communities(self) -> list[list[str]]:
+        if self.graph.number_of_nodes() == 0:
+            return []
+        undirected = self.graph.to_undirected()
+        groups = nx.algorithms.community.greedy_modularity_communities(undirected)
+        return [sorted(group) for group in groups]
+
+    def shortest_path(self, source: str, target: str) -> list[str] | None:
+        try:
+            return cast(list[str], nx.shortest_path(self.graph, source=source, target=target))
+        except (nx.NetworkXNoPath, nx.NodeNotFound):
+            return None
+
+    def relation_anomaly_score(self, source: str, relation: str, target: str) -> float:
+        """Compute an anomaly score for a candidate relation by comparing it
+        against local topology (source outgoing edges, target incoming edges)
+        and relation-type vector. Returns anomaly in range [0, 1], where 1 is
+        most anomalous.
+        """
+        candidate = self.hdc.encode_relation(source, relation, target)
+
+        # build local outgoing bundle from source
+        outs: list[BipolarVector] = []
+        for _, _, data in self.graph.out_edges(source, data=True):
+            edge_hv = data.get("hv")
+            try:
+                conf = float(data.get("confidence", 1.0))
+            except Exception:
+                conf = 1.0
+            conf_hv = self.hdc.encode_confidence(conf)
+            outs.append(self.hdc.bind(edge_hv, conf_hv))
+
+        # build local incoming bundle to target
+        ins: list[BipolarVector] = []
+        for _, _, data in self.graph.in_edges(target, data=True):
+            edge_hv = data.get("hv")
+            try:
+                conf = float(data.get("confidence", 1.0))
+            except Exception:
+                conf = 1.0
+            conf_hv = self.hdc.encode_confidence(conf)
+            ins.append(self.hdc.bind(edge_hv, conf_hv))
+
+        # relation template vector
+        relation_hv = self.hdc.get(f"relation::{relation}")
+
+        # helper to bundle or make zero-vector
+        def _bundle_or_zero(vs: list[BipolarVector]) -> BipolarVector:
+            if vs:
+                return self.hdc.bundle(vs)
+            return np.zeros(self.hdc.dim, dtype=np.int8)
+
+        s_bundle = _bundle_or_zero(outs)
+        t_bundle = _bundle_or_zero(ins)
+
+        # compare candidate to local bundles and relation prototype
+        scores = [
+            self.hdc.similarity(candidate, s_bundle),
+            self.hdc.similarity(candidate, t_bundle),
+            self.hdc.similarity(candidate, relation_hv),
+        ]
+
+        # Use the strongest local match as evidence; anomaly inversely
+        # proportional to the max similarity. Clamp to [0, 1] since cosine
+        # similarity can be negative in bipolar space.
+        best_sim = max(scores)
+        score = 1.0 - best_sim
+        return max(0.0, min(1.0, score))
+
+    def is_anomalous_relation(self, source: str, relation: str, target: str) -> bool:
+        return self.relation_anomaly_score(source, relation, target) >= self.config.anomaly_threshold
+
+    def decay_confidence(self) -> None:
+        """Apply confidence decay to all edges, useful for stale knowledge."""
+        for _, _, data in self.graph.edges(data=True):
+            data["confidence"] = max(0.0, float(data.get("confidence", 1.0)) * self.config.decay_rate)
+        self.global_state = None
+
+    # -----------------------------
+    # Serialization
+    # -----------------------------
+
+    def to_dict(self, include_hdc_memory: bool = True) -> dict[str, Any]:
+        nodes = [
+            NodeRecord(
+                name=node,
+                kind=data.get("kind", "concept"),
+                metadata=data.get("metadata", {}),
+            ).model_dump()
+            for node, data in self.graph.nodes(data=True)
+        ]
+        edges = [
+            EdgeRecord(
+                source=source,
+                relation=data.get("relation", "related_to"),
+                target=target,
+                weight=float(data.get("weight", 1.0)),
+                confidence=float(data.get("confidence", 1.0)),
+                metadata=data.get("metadata", {}),
+            ).model_dump()
+            for source, target, data in self.graph.edges(data=True)
+        ]
+        payload: dict[str, Any] = {
+            "config": self.config.model_dump(),
+            "nodes": nodes,
+            "edges": edges,
+            "snapshots": [snapshot.tolist() for snapshot in self.snapshots],
+        }
+        if include_hdc_memory:
+            payload["hdc"] = self.hdc.to_jsonable()
+        return payload
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "Topologist":
+        config = TopologistConfig(**payload.get("config", {}))
+        engine = cls(config=config)
+        if "hdc" in payload:
+            engine.hdc = HyperVectorSpace.from_jsonable(payload["hdc"])
+        for node in payload.get("nodes", []):
+            node_record = NodeRecord(**node)
+            engine.add_node(node_record.name, node_record.kind, **node_record.metadata)
+        for edge in payload.get("edges", []):
+            edge_record = EdgeRecord(**edge)
+            engine.add_edge(
+                edge_record.source,
+                edge_record.relation,
+                edge_record.target,
+                weight=edge_record.weight,
+                confidence=edge_record.confidence,
+                **edge_record.metadata,
+            )
+        engine.snapshots = [np.asarray(snapshot, dtype=np.int8) for snapshot in payload.get("snapshots", [])]
+        engine.update_global_state()
+        return engine
+
+    def save(self, path: str | Path) -> None:
+        try:
+            Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+        except Exception as exc:  # pragma: no cover
+            raise PersistenceError(f"failed to save topology: {exc}") from exc
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Topologist":
+        try:
+            payload = json.loads(Path(path).read_text(encoding="utf-8"))
+            return cls.from_dict(payload)
+        except Exception as exc:  # pragma: no cover
+            raise PersistenceError(f"failed to load topology: {exc}") from exc
+
+    def export_graphml(self, path: str | Path) -> None:
+        """Export symbolic topology to GraphML without raw hypervectors."""
+        export_graph = nx.MultiDiGraph()
+        for node, data in self.graph.nodes(data=True):
+            export_graph.add_node(
+                node,
+                kind=data.get("kind", "concept"),
+                metadata=json.dumps(data.get("metadata", {})),
+            )
+        for source, target, data in self.graph.edges(data=True):
+            export_graph.add_edge(
+                source,
+                target,
+                relation=data.get("relation", "related_to"),
+                weight=data.get("weight", 1.0),
+                confidence=data.get("confidence", 1.0),
+                metadata=json.dumps(data.get("metadata", {})),
+            )
+        nx.write_graphml(export_graph, path)

topologist/exceptions.py

@@ -0,0 +1,14 @@
+class TopologistError(Exception):
+    """Base error for Topologist."""
+
+
+class NodeNotFoundError(TopologistError):
+    """Raised when a required node is missing."""
+
+
+class PersistenceError(TopologistError):
+    """Raised when save/load fails."""
+
+
+class ValidationError(TopologistError):
+    """Raised when graph or rule data is invalid."""

topologist/hdc.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import math
+import numpy as np
+from numpy.typing import NDArray
+
+BipolarVector = NDArray[np.int8]
+
+
+class HyperVectorSpace:
+    """Bipolar hyperdimensional vector space.
+
+    Operations:
+    - item memory: stable random vectors per symbol
+    - bind: elementwise multiplication
+    - bundle: majority superposition
+    - permute: cyclic shift for order/role encoding
+    """
+
+    def __init__(self, dim: int = 10_000, seed: int = 42) -> None:
+        if dim < 128:
+            raise ValueError("dim must be at least 128")
+        self.dim = dim
+        self.seed = seed
+        self._rng = np.random.default_rng(seed)
+        self.item_memory: dict[str, BipolarVector] = {}
+
+    def random(self) -> BipolarVector:
+        return self._rng.choice([-1, 1], size=self.dim).astype(np.int8)
+
+    def get(self, symbol: str) -> BipolarVector:
+        key = symbol.strip()
+        if not key:
+            raise ValueError("symbol cannot be blank")
+        if key not in self.item_memory:
+            self.item_memory[key] = self.random()
+        return self.item_memory[key]
+
+    @staticmethod
+    def bind(a: BipolarVector, b: BipolarVector) -> BipolarVector:
+        return (a * b).astype(np.int8)
+
+    def bundle(self, vectors: list[BipolarVector]) -> BipolarVector:
+        if not vectors:
+            return np.zeros(self.dim, dtype=np.int8)
+        stacked = np.vstack(vectors).astype(np.int16)
+        summed = np.sum(stacked, axis=0)
+        return np.where(summed >= 0, 1, -1).astype(np.int8)
+
+    @staticmethod
+    def permute(vector: BipolarVector, shifts: int = 1) -> BipolarVector:
+        return np.roll(vector, shifts).astype(np.int8)
+
+    @staticmethod
+    def similarity(a: BipolarVector, b: BipolarVector) -> float:
+        denom = float(np.linalg.norm(a) * np.linalg.norm(b))
+        if denom == 0.0:
+            return 0.0
+        return float(np.dot(a.astype(np.float32), b.astype(np.float32)) / denom)
+
+    def encode_relation(self, source: str, relation: str, target: str) -> BipolarVector:
+        return self.bind(
+            self.bind(self.get(f"node::{source}"), self.get(f"relation::{relation}")),
+            self.get(f"node::{target}"),
+        )
+
+    def encode_typed_node(self, name: str, kind: str) -> BipolarVector:
+        return self.bind(self.get(f"kind::{kind}"), self.get(f"node::{name}"))
+
+    def encode_sequence(self, symbols: list[str]) -> BipolarVector:
+        vectors = []
+        position = self.get("role::position")
+        for idx, symbol in enumerate(symbols):
+            role = self.permute(position, idx)
+            vectors.append(self.bind(role, self.get(symbol)))
+        return self.bundle(vectors)
+
+    def encode_confidence(self, confidence: float) -> BipolarVector:
+        """Encode a continuous confidence value as a permuted base vector.
+
+        Confidence is expected in [0.0, 1.0]. We create a base confidence
+        vector in item memory and apply a cyclic permutation proportional to
+        the confidence value. This gives a smooth, continuous encoding that
+        changes as confidence decays.
+        """
+        try:
+            c = float(confidence)
+        except Exception:
+            c = 1.0
+        c = max(0.0, min(1.0, c))
+        base = self.get("confidence::base")
+        # map confidence to integer shift within [0, dim-1]
+        # avoid round() overload ambiguity by using explicit float math
+        shift = math.floor(float(c) * (self.dim - 1) + 0.5)
+        return self.permute(base, shift)
+
+    def to_jsonable(self) -> dict[str, object]:
+        return {
+            "dim": self.dim,
+            "seed": self.seed,
+            "item_memory": {key: value.tolist() for key, value in self.item_memory.items()},
+        }
+
+    @classmethod
+    def from_jsonable(cls, payload: dict[str, object]) -> "HyperVectorSpace":
+        space = cls(dim=int(str(payload["dim"])), seed=int(str(payload["seed"])))
+        raw_memory = payload.get("item_memory", {})
+        if not isinstance(raw_memory, dict):
+            raise ValueError("item_memory must be an object")
+        space.item_memory = {
+            str(key): np.asarray(value, dtype=np.int8) for key, value in raw_memory.items()
+        }
+        return space
+
+    def save_item_memory(self, path: str | Path) -> None:
+        Path(path).write_text(json.dumps(self.to_jsonable()), encoding="utf-8")
+
+    @classmethod
+    def load_item_memory(cls, path: str | Path) -> "HyperVectorSpace":
+        return cls.from_jsonable(json.loads(Path(path).read_text(encoding="utf-8")))

topologist/io.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Iterable
+
+from topologist.engine import Topologist
+from topologist.models import EdgeRecord, NodeRecord
+
+
+def load_edges_csv(path: str | Path) -> list[EdgeRecord]:
+    with Path(path).open("r", newline="", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        edges: list[EdgeRecord] = []
+        for row in reader:
+            metadata = {}
+            metadata_json = row.get("metadata_json")
+            if metadata_json:
+                metadata = json.loads(metadata_json)
+            elif row.get("metadata"):
+                raw_metadata = row["metadata"]
+                try:
+                    metadata = json.loads(raw_metadata)
+                except json.JSONDecodeError:
+                    metadata = {"metadata": raw_metadata}
+            weight = float(row["weight"]) if row.get("weight") not in (None, "") else 1.0
+            confidence = float(row["confidence"]) if row.get("confidence") not in (None, "") else 1.0
+            edges.append(
+                EdgeRecord(
+                    source=row["source"],
+                    relation=row["relation"],
+                    target=row["target"],
+                    weight=weight,
+                    confidence=confidence,
+                    metadata=metadata,
+                )
+            )
+        return edges
+
+
+def save_edges_csv(path: str | Path, edges: Iterable[EdgeRecord]) -> None:
+    rows: list[dict[str, object]] = []
+    for edge in edges:
+        edge_data = edge.model_dump()
+        edge_data["metadata_json"] = json.dumps(edge_data.pop("metadata"))
+        rows.append(edge_data)
+    if not rows:
+        return
+    with Path(path).open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(rows[0].keys()))
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def build_from_records(nodes: Iterable[NodeRecord], edges: Iterable[EdgeRecord]) -> Topologist:
+    topology = Topologist()
+    for node in nodes:
+        topology.add_node(node.name, node.kind, **node.metadata)
+    for edge in edges:
+        topology.add_edge(
+            edge.source,
+            edge.relation,
+            edge.target,
+            weight=edge.weight,
+            confidence=edge.confidence,
+            **edge.metadata,
+        )
+    topology.update_global_state(take_snapshot=True)
+    return topology

topologist/models.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class NodeRecord(BaseModel):
+    """Serializable symbolic node record."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1)
+    kind: str = Field(default="concept", min_length=1)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("name", "kind")
+    @classmethod
+    def strip_text(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value cannot be blank")
+        return value
+
+
+class EdgeRecord(BaseModel):
+    """Serializable symbolic edge record."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: str = Field(min_length=1)
+    relation: str = Field(min_length=1)
+    target: str = Field(min_length=1)
+    weight: float = Field(default=1.0, ge=0.0)
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("source", "relation", "target")
+    @classmethod
+    def strip_text(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value cannot be blank")
+        return value
+
+
+class ReasoningRule(BaseModel):
+    """A simple two-hop symbolic inference rule.
+
+    Example:
+        if A --connects_to--> B and B --supports--> C,
+        infer A --indirectly_supports--> C.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    relation_a: str = Field(min_length=1)
+    relation_b: str = Field(min_length=1)
+    inferred_relation: str = Field(min_length=1)
+    min_confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)

topologist/visualization.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from topologist.engine import Topologist
+
+
+def export_mermaid(topology: Topologist, path: str | Path) -> None:
+    """Export graph as a Mermaid flowchart."""
+    lines = ["flowchart LR"]
+    for source, target, data in topology.graph.edges(data=True):
+        relation = str(data.get("relation", "related_to")).replace('"', "'")
+        lines.append(f'    "{source}" -- "{relation}" --> "{target}"')
+    Path(path).write_text("\n".join(lines) + "\n", encoding="utf-8")

topologist-0.1.0.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: topologist
+Version: 0.1.0
+Summary: A production-hardened hyperdimensional neuro-symbolic topology system.
+Author: Robert McMenemy
+License: MIT
+Project-URL: Homepage, https://github.com/EasyTees/Topologist
+Project-URL: Repository, https://github.com/EasyTees/Topologist
+Project-URL: Documentation, https://github.com/EasyTees/Topologist#readme
+Project-URL: Issues, https://github.com/EasyTees/Topologist/issues
+Keywords: hyperdimensional-computing,neuro-symbolic,topology,reasoning,knowledge-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: networkx>=3.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Topologist
+
+A production-hardened **hyperdimensional neuro-symbolic topology system** in Python.
+
+Topologist combines:
+
+- **Hyperdimensional Computing / Vector Symbolic Architecture** for robust distributed representations.
+- **Neuro-symbolic graph topology** using NetworkX.
+- **Rule-based inference** over symbolic relations.
+- **Topology analytics** including PageRank centrality, communities, shortest paths, drift, and anomaly scoring.
+- **Persistence and export** to JSON, GraphML, and Mermaid.
+- **CLI tooling** for demos and inspection.
+
+---
+
+## Why this exists
+
+Most symbolic graph systems are explainable but brittle. Most neural/vector systems are robust but opaque.
+
+Topologist sits between the two:
+
+```text
+Symbolic entities and relations
+        ↓
+Hyperdimensional encoding
+        ↓
+Topology graph
+        ↓
+Reasoning + analytics + anomaly detection
+```
+
+Each node and relation is stored symbolically, but also encoded into a high-dimensional bipolar hypervector. This gives you a graph that is queryable and explainable while also having a distributed topology-level memory state.
+
+---
+
+## Install
+
+```bash
+cd topologist
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+For development without installing, ensure the package is in the Python path:
+
+```bash
+pip install -e .
+python examples/demo.py
+```
+
+---
+
+## Quick start
+
+```python
+from topologist import Topologist
+from topologist.models import ReasoningRule
+
+system = Topologist()
+
+system.add_edge("Neuron", "connects_to", "Synapse", confidence=0.95)
+system.add_edge("Synapse", "supports", "Memory", confidence=0.90)
+system.add_edge("HDC", "models", "Memory", confidence=0.85)
+
+created = system.apply_rule(
+    ReasoningRule(
+        relation_a="connects_to",
+        relation_b="supports",
+        inferred_relation="indirectly_supports",
+        min_confidence=0.5,
+    )
+)
+
+system.update_global_state(take_snapshot=True)
+
+print("Created inferred edges:", created)
+print("Centrality:", system.centrality())
+print("Communities:", system.communities())
+print("Nearest nodes:", system.nearest_nodes("Memory"))
+print("Path:", system.shortest_path("Neuron", "Memory"))
+
+system.save("topology.json")
+```
+
+Streaming example
+
+```bash
+# Run the streaming demo which ingests events, applies inference,
+# snapshots state, computes drift, and scores anomalies.
+python examples/streaming_topology.py
+```
+
+---
+
+## CLI
+
+Create a demo topology:
+
+```bash
+topologist demo --output topology.json
+```
+
+Inspect it:
+
+```bash
+topologist inspect topology.json
+```
+
+Export Mermaid:
+
+```bash
+topologist mermaid topology.json --output topology.mmd
+```
+
+---
+
+## Main features
+
+### 1. Hyperdimensional item memory
+
+Stable symbols are encoded into bipolar vectors:
+
+```text
+symbol → {-1, +1}^D
+```
+
+The engine supports:
+
+- Binding: elementwise multiplication
+- Bundling: majority superposition
+- Permutation: cyclic shifts for order/role encoding
+- Similarity: cosine similarity
+
+### 2. Symbolic topology graph
+
+The graph is a `networkx.MultiDiGraph`, so it supports multiple relation types between the same source and target.
+
+Example:
+
+```text
+HDC --models--> Memory
+HDC --enhances--> KnowledgeGraph
+KnowledgeGraph --supports--> Reasoning
+```
+
+### 3. Rule-based inference
+
+Rules operate over two-hop motifs:
+
+```text
+A --relation_a--> B
+B --relation_b--> C
+----------------------
+A --inferred_relation--> C
+```
+
+### 4. Drift detection
+
+The global graph state is bundled into a single hypervector snapshot.
+
+```python
+system.update_global_state(take_snapshot=True)
+drift = system.topology_drift()
+```
+
+This lets you measure how much the topology has changed over time.
+
+### 5. Anomaly scoring
+
+Candidate relations can be compared against the global topology state:
+
+```python
+score = system.relation_anomaly_score("A", "unexpected_relation", "B")
+```
+
+Higher scores mean the relation is less aligned with the current topology memory.
+
+### 6. Confidence decay
+
+Knowledge that is not reinforced can gradually lose confidence:
+
+```python
+system.decay_confidence()
+```
+
+This is useful for agent memory, dynamic knowledge graphs, cybersecurity events, medical evidence tracking, and live topology streams.
+
+---
+
+## Project structure
+
+```text
+topologist/
+├── topologist/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── config.py
+│   ├── engine.py
+│   ├── exceptions.py
+│   ├── hdc.py
+│   ├── io.py
+│   ├── models.py
+│   └── visualization.py
+├── examples/
+│   ├── demo.py
+│   └── streaming_topology.py
+├── tests/
+│   ├── test_engine.py
+│   └── test_hdc.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Run tests
+
+```bash
+pytest -q
+```
+
+---
+
+## Production hardening included
+
+This package includes:
+
+- Typed modules
+- Pydantic validation
+- Custom exceptions
+- Save/load roundtrip support
+- CLI entrypoint
+- Config object
+- Test suite
+- Export helpers
+- No notebook-only assumptions
+- No hidden API dependency
+- Deterministic seed support
+- Dimension validation
+- Confidence decay
+- Snapshot capping
+
+---
+
+## Good next upgrades
+
+Useful next layers would be:
+
+1. PyTorch Geometric bridge for GNN message passing.
+2. Streaming event ingestion from Kafka, Redis Streams, or WebSockets.
+3. Approximate nearest-neighbour search for large item memories.
+4. Rule DSL with richer multi-hop inference.
+5. OpenTelemetry tracing.
+6. FastAPI service wrapper.
+7. SQLite/Postgres persistence adapter.
+8. Agent memory adapter for Claude Code, OpenClaw, or local LLM agents.
+
+---
+
+## License
+
+MIT

topologist-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+topologist/__init__.py,sha256=desvdhtnzcFN0IKEU7fnYsuDHCtL4_WoCupCO0t7n9s,429
+topologist/cli.py,sha256=QRoHeqW7gGEopOXEg4n2Q5BQ-KBkRx3JZ5__VL-rwIU,2412
+topologist/config.py,sha256=8K0eWpo4jQ5YFWMtUcjdWs6MAbBNaHjcyUngBzeenQs,770
+topologist/engine.py,sha256=Tj4dkU5wgeuaJxWpcyHcDqfs06ziPsonEwnCSGgKS1o,16940
+topologist/exceptions.py,sha256=xiu4Nv-0cm1ldgssPRff1SQv_lmifXfujWvRJWfi2nU,342
+topologist/hdc.py,sha256=HGMjWPb9DpbeZPwpRl8tfRss82X3C91CHLgo7SUkLrA,4583
+topologist/io.py,sha256=0bIuy_yfxhBS7zbHWqa_pitHT5gnrxk2Vjzt9o3O6Uw,2459
+topologist/models.py,sha256=JGEqB7ycyz0KC0MZr-gnOWAJuv-hBfT42KerDBKlYO4,1781
+topologist/visualization.py,sha256=rjsIzkBDLnydNtE3ff2_vabmgjY-SXsfl1TfawM2mGs,531
+topologist-0.1.0.dist-info/licenses/LICENSE,sha256=35xim7D8bs26EtC_a3-kD7iy6_fynbcSyj3waYYD6Rc,1070
+topologist-0.1.0.dist-info/METADATA,sha256=3GgxoK2NEAczbI_MX3UCatb0Cw0Khx2B7PgeMdfSOio,7197
+topologist-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+topologist-0.1.0.dist-info/entry_points.txt,sha256=hZip_p1rAqPOvlkFMJfLYX_2uTCDF0010aMYtFLeTWk,50
+topologist-0.1.0.dist-info/top_level.txt,sha256=ljH5-HroXMEudy8ScSlLuaEpjxsySoANa0NjLxFJ0bw,11
+topologist-0.1.0.dist-info/RECORD,,

topologist-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

topologist-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+topologist = topologist.cli:app

topologist-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JadeyGraham96
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topologist-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+topologist