Metadata-Version: 2.4
Name: hypersynergy
Version: 0.1.3
Summary: A Topological Graph Neural Network framework for Traditional Medicine synergy prediction.
Home-page: https://github.com/vothikimanh1007/HyperSynergy-CDSS
Author: Vo Thi Kim Anh
Author-email: vothikimanh@tdtu.edu.vn
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: networkx>=2.5
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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  
<br/>\# 1. Initialize the MATG model natively  
model = MATG_Model(num_nodes=714, num_hyperedges=150, mode='proposed')  
<br/>\# (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)  
<br/>\# 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.
