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.
• Provenance-first memory with edge evidence, trust, reinforcement count, timestamps, and explanations.
• Persistence and export to JSON, SQLite, Postgres, GraphML, and Mermaid.
• CLI, FastAPI, streaming, ANN, tracing, and agent-memory adapters for production-facing workflows.

Why this exists

Most symbolic graph systems are explainable but brittle. Most neural/vector systems are robust but opaque.

Topologist sits between the two:

Symbolic entities and relations
  -> hyperdimensional encoding
  -> graph topology
  -> reasoning + analytics + anomaly detection
  -> persistence, streaming, service, and visualization layers

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.

Architecture

events / CSV / API / CLI
        |
        v
Topologist engine
  - NetworkX MultiDiGraph
  - HDC item memory
  - confidence-aware global state
        |
        +--> DSL and multi-hop inference
        +--> anomaly scoring and drift detection
        +--> ANN nearest-neighbor lookup
        +--> JSON / SQLite / Postgres persistence
        +--> Mermaid / GraphML export
        +--> FastAPI / Kafka / Redis / WebSocket adapters

The HDC layer uses stable namespaced item memory such as node::Host, relation::connects_to, and quantized confidence::band::N vectors. Candidate relations are scored by unbinding the relation signal and comparing it with both relation prototypes and local topology.

Install

pip install topologist

For development:

pip install -e ".[dev]"
python examples/demo.py

For real persistent homology with GUDHI and Ripser.py:

pip install "topologist[tda]"

Quick Start

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")

Worked Example: Cyber Event Topology

Run a deterministic scenario that ingests security events, infers multi-hop risk, scores anomalies, measures drift, and exports Mermaid:

python examples/cyber_event_topology.py

The example models a path like:

IP -> connects_to -> service
service -> exposes -> vulnerability
vulnerability -> enables -> privilege_escalation

Then it infers:

IP -> may_escalate_via -> privilege_escalation

The script writes:

• cyber_event_topology.json
• cyber_event_topology.mmd

There is also a smaller streaming simulation:

python examples/streaming_topology.py

CLI

Create a demo topology:

topologist demo --output topology.json

Inspect it:

topologist inspect topology.json

Export Mermaid:

topologist mermaid topology.json --output topology.mmd

Main Features

1. Hyperdimensional item memory

Stable symbols are encoded into bipolar vectors:

symbol -> {-1, +1}^D

The engine supports binding, bundling, permutation, quantized confidence bands, and cosine similarity.

2. Symbolic topology graph

The graph is a networkx.MultiDiGraph, so it supports multiple relation types between the same source and target.

HDC --models--> Memory
HDC --enhances--> KnowledgeGraph
KnowledgeGraph --supports--> Reasoning

3. Rule-based inference

Rules operate over two-hop motifs and general multi-hop DSL expressions:

A --relation_a--> B
B --relation_b--> C
----------------------
A --inferred_relation--> C

topology.apply_dsl_rule("A -[causes]-> B -[causes]-> C => [indirectly_causes]")

4. Drift detection

The global graph state is bundled into a single hypervector snapshot.

system.update_global_state(take_snapshot=True)
drift = system.topology_drift()

5. Anomaly scoring

Candidate relations are scored against relation usage already present in the graph:

score = system.relation_anomaly_score("A", "unexpected_relation", "B")

The scoring method:

1. Checks whether the exact edge is already known.
2. Compares the relation against observed endpoint kinds and local relation patterns.
3. Scores local HDC similarity against incident topology.
4. Returns anomaly in [0, 1], where 1 is most anomalous.

6. Persistence and service adapters

Topologist supports JSON, SQLite, Postgres, FastAPI, Kafka, Redis Streams, WebSocket ingestion, OpenTelemetry tracing, approximate nearest neighbors, and agent-memory persistence.

7. Provenance and reasoning traces

Edges carry provenance metadata so agent memory and streaming systems can explain why a relation exists:

topology.add_edge(
    "A",
    "supports",
    "B",
    source_type="sensor",
    evidence=["event-123"],
    trust_score=0.8,
)

topology.explain_edge("A", "supports", "B")

Inferred edges include the rule and evidence path used to derive them.

8. Contradiction detection and belief revision

Topologist can flag directly conflicting relations and revise stale beliefs while preserving evidence:

topology.add_edge("service_api", "is_safe", "public_endpoint", confidence=0.8)
topology.add_edge("service_api", "is_risky", "public_endpoint", confidence=0.9)

topology.detect_contradictions()

topology.revise_belief(
    old=("service_api", "is_safe", "public_endpoint"),
    new=("service_api", "is_risky", "public_endpoint"),
    evidence="scanner finding",
)

Belief revision lowers the old edge confidence, adds the replacement edge, records a contradicts relation, and keeps provenance for the revision evidence.

Project Structure

topologist/
|-- __init__.py
|-- agent.py          # Agent memory adapters
|-- ann.py            # Approximate nearest-neighbor search
|-- benchmark.py      # Benchmark harness
|-- bridges.py        # PyTorch Geometric bridge
|-- cli.py            # CLI commands
|-- config.py         # Runtime configuration
|-- dashboard.py      # Optional Streamlit dashboard
|-- domains/          # Cyber, agent memory, medical evidence, research, and architecture packs
|-- dsl.py            # Rule DSL for multi-hop inference
|-- engine.py         # Core topology engine
|-- exceptions.py     # Custom exception types
|-- hdc.py            # Hyperdimensional computing operations
|-- io.py             # CSV utilities
|-- mapper.py         # Mapper-style topology projection
|-- mcp.py            # Optional MCP tool/server surface
|-- models.py         # Pydantic records
|-- pipeline.py       # Lightweight graph ML pipeline facade
|-- persistence.py    # SQLite/Postgres adapters
|-- service.py        # FastAPI service wrapper
|-- streaming.py      # Kafka/Redis/WebSocket adapters
|-- tda.py            # Lightweight TDA-inspired complex and summary helpers
|-- tracing.py        # OpenTelemetry tracing
|-- visualization.py  # Mermaid, HTML, and GraphML export
`-- workflow.py       # Checkpointed event runner and replay helpers

Benchmark Notes

See BENCHMARKS.md for current benchmark guidance. The practical knobs are graph size, hypervector dimension, snapshot frequency, and rule/path length. For early releases, benchmark results should be treated as environment-specific until a repeatable benchmark harness is added.

Topologist vs TDA, Graph Analytics, and Agent Workflow Tools

Topologist is not a replacement for GUDHI, giotto-tda, or Ripser.py. Those libraries compute classical persistent homology over metric or simplicial data. Topologist borrows TDA ideas for symbolic/HDC graphs: clique-based complexes, confidence filtrations, persistence-style summaries, topology-distance-style comparisons, and Mapper-style projections that preserve provenance, trust, contradiction, and reasoning metadata.

When installed with topologist[tda], Topologist also exposes real persistent homology:

result = topology.persistent_homology(backend="gudhi", max_dimension=2)
intervals = topology.real_persistence_diagram(backend="ripser", max_dimension=1)

The GUDHI backend builds a filtered clique complex from symbolic graph confidence/trust. The Ripser backend computes Vietoris-Rips persistence over a graph-derived shortest-path distance matrix.

Topologist is also not just NetworkX, Neo4j GDS, or LangGraph. NetworkX and graph data science systems provide broad graph algorithms; LangGraph provides agent workflow orchestration. Topologist combines graph reasoning, high-dimensional distributed memory, provenance-first edge records, contradiction detection, belief revision, topology-aware context retrieval, temporal drift/diffing, subgraph fingerprints, checkpoints, review queues, and domain packs in one explainable memory engine.

The project identity is: an explainable hyperdimensional topology memory engine for dynamic symbolic systems such as AI agents, cybersecurity event reasoning, dynamic knowledge graphs, research evidence graphs, and explainable memory systems.

Development

pip install -e ".[dev]"
ruff check .
mypy topologist
pytest -q
python -m build
twine check dist/*

See CONTRIBUTING.md and CHANGELOG.md.

License

MIT