topologist 0.4.0

A production-hardened hyperdimensional neuro-symbolic topology system.

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

---

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 can be compared against local topology and relation prototypes using unbinding:

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

The scoring method:

1. Unbinds the candidate relation to recover the relation signal.
2. Compares against the expected relation hypervector.
3. Checks similarity to local topology edges.
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
|-- bridges.py        # PyTorch Geometric bridge
|-- cli.py            # CLI commands
|-- config.py         # Runtime configuration
|-- 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
|-- models.py         # Pydantic records
|-- persistence.py    # SQLite/Postgres adapters
|-- service.py        # FastAPI service wrapper
|-- streaming.py      # Kafka/Redis/WebSocket adapters
|-- tracing.py        # OpenTelemetry tracing
`-- visualization.py  # Mermaid and GraphML export

---

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 distances, and Mapper-style projections that preserve provenance, trust, contradiction, and reasoning metadata.

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.

Area	Topologist capability
Topological Context Retrieval	Hybrid HDC, graph-distance, trust, anomaly, contradiction, persistence, and centrality ranking with explanations.
Provenance-first Memory	Edge evidence, source type, trust score, reinforcement count, timestamps, and belief lifecycle history.
Contradiction and Belief Revision	Configurable contradiction pairs/groups, severity scoring, review hooks, and revision policies.
Temporal Topology Diff	Named snapshots with metadata, HDC drift, confidence/trust changes, persistence changes, and drift explanations.
Subgraph Intelligence	Motif matching, HDC subgraph fingerprints, similar subgraph search, and context fingerprints.
Cybersecurity Domain Pack	Login, process, network, vulnerability, attack-path, lateral-movement, and privilege-escalation helpers.
Agent Memory Use Case	Threaded memory namespaces, recall, reinforcement, stale-memory cleanup, promotion, and explanation.
Dashboard Demo	Streamlit graph, provenance, contradiction, persistence, Mapper, context, and reasoning-trace panels.
Benchmarks	CLI benchmark for insertion, HDC state updates, context retrieval, anomaly scoring, contradiction detection, and snapshots.

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