hypersynergy 0.1.3

A Topological Graph Neural Network framework for Traditional Medicine synergy prediction.

HyperSynergy 🌿

The HyperSynergy Python library provides the core inference and explainability (XAI) engine for the HyperSynergy Clinical Decision Support System (CDSS). It bridges centuries of Traditional Medicine with modern geometric deep learning.

This package houses the Manifold-Aware Transformer Gating (MATG) neural network, designed to predict high-order pharmacological synergies between traditional herbal components using non-Euclidean (Poincaré) geometry.

📦 Installation

You can install the library directly from PyPI:

pip install hypersynergy

Dependencies

• torch >= 2.0.0
• numpy >= 1.21.0

🚀 Quick Start

The library provides modular access to the MATG architecture and the NeuMapper Topological Explainability suite.

import torch
from hypersynergy.models import MATG_Model
from hypersynergy.explainers import NeuMapper

# 1. Initialize the MATG model natively
model = MATG_Model(num_nodes=714, num_hyperedges=150, mode='proposed')

# (Assuming node_features and incidence_matrix are pre-loaded tensors)
# 2. Forward pass automatically computes Euclidean & Hyperbolic topologies
euclidean_feats, hyperbolic_topology = model(node_features, incidence_matrix)
predictions = model.decode_synergy(euclidean_feats, hyperbolic_topology)

# 3. Extract Topological Explainable AI (XAI) insights automatically
# This returns the alpha weights (Quân-Thần-Tá-Sứ hierarchy)
xai_attention_weights = NeuMapper.extract_topological_hierarchy(model)

🔬 Core Architecture

• Framework Version: v82
• Core Task: Node-Hyperedge Incidence Prediction (Synergy Evaluation)
• Dataset: Trained on the DoTatLoi-714 Benchmark

🎓 Academic Context

This library is the computational foundation of a Ph.D. research project focusing on Macro-to-Micro Geometric Learning. It is structurally optimized for deployment as a modern, headless Clinical Decision Support System.

Lead Researcher: Vo Thi Kim Anh

• Ph.D. Candidate, VSB - Technical University of Ostrava, Czech Republic
• Researcher, Ton Duc Thang University, Vietnam

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.