topologist 0.1.0__tar.gz

topologist-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy topologist
+      - run: python -m pytest -q

topologist-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine upload dist/*

topologist-0.1.0/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/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include .github/workflows *.yml

topologist-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,263 @@
+# 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/examples/demo.py

@@ -0,0 +1,45 @@
+from topologist import Topologist
+from topologist.models import ReasoningRule
+from topologist.visualization import export_mermaid
+
+
+def main() -> None:
+    topo = Topologist()
+
+    topo.add_node("Agent", "system")
+    topo.add_node("Memory", "cognitive_layer")
+    topo.add_node("KnowledgeGraph", "symbolic_layer")
+    topo.add_node("HypervectorSpace", "hdc_layer")
+    topo.add_node("AnomalyDetector", "reasoning_layer")
+
+    topo.add_edge("Agent", "uses", "Memory", confidence=0.95)
+    topo.add_edge("Memory", "encoded_by", "HypervectorSpace", confidence=0.90)
+    topo.add_edge("Memory", "structured_by", "KnowledgeGraph", confidence=0.88)
+    topo.add_edge("KnowledgeGraph", "feeds", "AnomalyDetector", confidence=0.82)
+
+    inferred = topo.apply_rule(
+        ReasoningRule(
+            relation_a="uses",
+            relation_b="encoded_by",
+            inferred_relation="indirectly_uses",
+            min_confidence=0.5,
+        )
+    )
+
+    topo.update_global_state(take_snapshot=True)
+
+    print(f"Inferred edges: {inferred}")
+    print("Centrality:", topo.centrality())
+    print("Communities:", topo.communities())
+    print("Nearest to Memory:", topo.nearest_nodes("Memory", top_k=3))
+    print(
+        "Anomaly score:",
+        topo.relation_anomaly_score("Agent", "ignores", "Memory"),
+    )
+
+    topo.save("example_topology.json")
+    export_mermaid(topo, "example_topology.mmd")
+
+
+if __name__ == "__main__":
+    main()