Neuro-Symbolic eXplainable Framework for Diagnostic Support
NeSy-X is a research framework that integrates large language models, text vector representations, biomedical ontologies, and a knowledge graph to support symptom-based identification and ranking of candidate diseases.
Developed as part of a master's thesis, the framework separates neural language processing from symbolic reasoning. Language models extract symptoms from unstructured text, vector representations support their mapping to ontological concepts, and the symbolic layer evaluates candidate diseases using explicit graph relations, symptom weights, and filtering rules. An explanation layer converts the structured results into natural-language explanations.
NeSy-X is designed to support four complementary properties:
- Traceability: following the processing steps from user input through extracted symptoms and mapped concepts to ranked disease candidates.
- Verifiability: checking symbolic results against the graph relations, symptom weights, and rules used to obtain them.
- Explainability: presenting understandable reasons for disease ranking and exclusion.
- Controllability: configuring processing behavior through similarity thresholds, matching requirements, filtering rules, and result limits.
These properties support transparency of the overall workflow without assuming that the internal operation of a language model is fully interpretable.
NeSy-X operates through two phases: preparation and execution. The preparation phase establishes and enriches the knowledge graph, while the execution phase processes user input and produces ranked disease candidates with accompanying explanations.
The preparation phase establishes an enriched knowledge graph based on the Human Disease Ontology (DO) and the Symptom Ontology (SYMP). Disease and symptom concepts are imported into Neo4j together with their ontological relations.
Symptom nodes are enriched with Information Content (IC) weights and vector representations of their textual labels. These precomputed properties support subsequent disease scoring and semantic mapping.
- Symptom extraction: a large language model identifies present and explicitly negated symptoms in the user's text.
- Semantic mapping: extracted expressions are mapped to SYMP concepts using vector representations and a configurable cosine-similarity threshold.
- Symbolic reasoning: graph queries retrieve candidate diseases, which are scored using matched symptom weights and square-root normalization. A negated-symptom filter separates included and excluded candidates.
- Explanation generation: the XAI layer uses structured symbolic results to explain the ranking and filtering decisions.
The language model is not used as a standalone diagnostic mechanism. Candidate retrieval, scoring, and filtering are based on the knowledge graph and explicitly defined processing rules.
The prototype consists of a React client, a FastAPI backend, and a Neo4j knowledge graph. Neural processing uses pretrained language models and a text vector representation model, with integrations for local and cloud LLM execution.
The architecture separates language processing, semantic mapping, symbolic evaluation, and explanation generation, allowing these components to be configured and evaluated individually.
The research contribution lies in integrating these components into a unified diagnostic-support workflow and evaluating their behavior under controlled conditions.
Evaluation covers symptom extraction, semantic mapping, disease ranking, negated-symptom filtering, and explanation generation. The study also examines the practical trade-offs between local and cloud model execution.
⚠️ NeSy-X is a research prototype, not a clinically validated diagnostic system. Evaluation was conducted on controlled examples and ontology-derived datasets rather than real patient data. Ranking scores and cosine-similarity values are not calibrated disease probabilities. Results remain dependent on ontology coverage, extraction and mapping quality, and the reliability of generated explanations.
The framework must not be used for medical diagnosis or treatment decisions.
- Neo4j and ontology setup
- Ontology structure and OWL representation
- Preparation and evaluation notebooks
- Local model setup with Ollama
- Backend setup and configuration
- Frontend setup
- Symptom extraction evaluation
- Semantic mapping evaluation
- Symbolic reasoning, scoring, and filtering evaluation
- Explanation generation evaluation
Distributed under the MIT License. See LICENSE.