topologist 0.2.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.

---

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.

---

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