OntoAligner is a Python library that makes ontology alignment and knowledge graph matching easy for researchers, practitioners, and developers. It ships a single, consistent parse → encode → align → postprocess pipeline behind more than a dozen alignment paradigms — from classic fuzzy/lexical matching to retrieval, Large Language Models (LLMs), Retrieval-Augmented Generation (RAG), Knowledge Graph Embeddings (KGE), fuzzy-logic KG alignment, and ensemble learning — so you can go from two raw ontologies to an evaluated alignment in a handful of lines of code.
🏆 OntoAligner was awarded the Best Resource Paper Award at ESWC 2025.
📘 New to OntoAligner? Start with the tutorial notebooks or the full documentation.
You can install OntoAligner from PyPI using pip:
pip install ontoalignerAlternatively, to get the latest version directly from the source, use the following commands:
git clone git@github.com:sciknoworg/OntoAligner.git
pip install ./ontoalignerNext, verify the installation:
importontoalignerprint(ontoaligner.__version__)The fastest way to run an alignment: pick a dataset, an encoder, and an aligner, and let the pipeline handle collection, encoding, prediction, postprocessing, and evaluation.
importontoalignerpipeline=ontoaligner.OntoAlignerPipeline(
task_class=ontoaligner.ontology.GenericOMDataset,
source_ontology_path="assets/mouse-human/source.xml",
target_ontology_path="assets/mouse-human/target.xml",
reference_matching_path="assets/mouse-human/reference.xml",
)
matchings, evaluation=pipeline(
method="rag",
encoder_model=ontoaligner.encoder.ConceptParentRAGEncoder(),
model_class=ontoaligner.aligner.MistralLLMBERTRetrieverRAG,
postprocessor=ontoaligner.postprocess.rag_hybrid_postprocessor,
llm_path="mistralai/Mistral-7B-v0.3",
retriever_path="all-MiniLM-L6-v2",
llm_threshold=0.5,
ir_rag_threshold=0.7,
top_k=5,
max_length=512,
max_new_tokens=10,
device="cuda",
batch_size=32,
return_matching=True,
evaluate=True,
)
print("Matching Evaluation Report:", evaluation)Build the same RAG-based alignment yourself for full control over every stage:
fromontoaligner.ontologyimportGenericOMDatasetfromontoaligner.utilsimportmetrics, xmlify, sssom_pydanticfromontoaligner.alignerimportMistralLLMBERTRetrieverRAGfromontoaligner.encoderimportConceptParentRAGEncoderfromontoaligner.postprocessimportrag_hybrid_postprocessor# Step 1: Initialize the dataset using GenericOMDatasettask=GenericOMDataset()
print("Test Task:", task)
# Step 2: Load source and target ontologies along with reference matchingsdataset=task.collect(
source_ontology_path="assets/MI-MatOnto/mi_ontology.xml",
target_ontology_path="assets/MI-MatOnto/matonto_ontology.xml",
reference_matching_path="assets/MI-MatOnto/matchings.xml",
)
# Step 3: Encode the source and target ontologiesencoder_model=ConceptParentRAGEncoder()
encoded_ontology=encoder_model(source=dataset["source"], target=dataset["target"])
# Step 4: Define configuration for retriever and LLMretriever_config= {"device": "cuda", "top_k": 5}
llm_config= {"device": "cuda", "max_length": 300, "max_new_tokens": 10, "batch_size": 15}
# Step 5: Generate predictions using the RAG-based ontology matchermodel=MistralLLMBERTRetrieverRAG(retriever_config=retriever_config, llm_config=llm_config)
model.load(llm_path="mistralai/Mistral-7B-v0.3", ir_path="all-MiniLM-L6-v2")
predicts=model.generate(input_data=encoded_ontology)
# Step 6: Apply hybrid postprocessinghybrid_matchings, hybrid_configs=rag_hybrid_postprocessor(
predicts=predicts, ir_score_threshold=0.1, llm_confidence_th=0.8
)
evaluation=metrics.evaluation_report(predicts=hybrid_matchings, references=dataset["reference"])
print("Hybrid Matching Evaluation Report:", evaluation)
# Step 7: Convert matchings to XML format and save the XML representationxml_str=xmlify.xml_alignment_generator(matchings=hybrid_matchings)
open("matchings.xml", "w", encoding="utf-8").write(xml_str)
# Or you can explicitly convert to SSSOM and write to disksssom_pydantic.sssom_alignment_generator(hybrid_matchings, "matchings.sssom.tsv")AlignerPipeline provides a reusable execution flow for running one user-provided encoder and one ontology matching aligner over a collected ontology matching dataset. See the bellow on how to define advanced aligner pipeline.
fromontoaligner.ontologyimportGenericOMDatasetfromontoaligner.utilsimportmetricsfromontoaligner.encoderimportConceptParentLightweightEncoderfromontoaligner.alignerimportSimpleFuzzySMLightweightfromontoalignerimportAlignerPipelinetask=GenericOMDataset()
dataset=task.collect(
source_ontology_path="assets/MI-MatOnto/mi_ontology.xml",
target_ontology_path="assets/MI-MatOnto/matonto_ontology.xml",
reference_matching_path="assets/MI-MatOnto/matchings.xml",
)
aligner_pipeline=AlignerPipeline(
encoder=ConceptParentLightweightEncoder(),
aligner=SimpleFuzzySMLightweight(fuzzy_sm_threshold=0.2),
om_dataset=dataset,
)
matchings=aligner_pipeline.generate()
evaluation=metrics.evaluation_report(predicts=matchings, references=dataset["reference"])
print("Matching Evaluation Report:", evaluation)Combine independent aligner branches (lexical, retrieval, KGE, LLM, RAG, ...) into a single, more robust alignment via a voting strategy such as WeightedVoting, BordaVoting, CondorcetVoting, or ReciprocalRankFusionVoting:
fromontoaligner.aligner.ensembleimportEnsembleLearningAlignerfromontoaligner.aligner.ensemble.votingimportWeightedVotingfromontoalignerimportAlignerPipelinelexical_pipeline=AlignerPipeline(...) # define your lexical aligner pipelineretrieval_pipeline=AlignerPipeline(...) # define your retrieval aligner pipelinellm_pipeline=AlignerPipeline(...) # define your LLM aligner pipelineensemble=EnsembleLearningAligner(
aligners=[
("lexical", lexical_pipeline, 0.2), # each branch is an AlignerPipeline
("retrieval", retrieval_pipeline, 0.3),
("llm", llm_pipeline, 0.5),
],
voting=WeightedVoting(),
)
final_matchings=ensemble.generate()See ontoaligner.readthedocs.io/developerguide/pipeline.html for more details on how to define your own AlignerPipeline and EnsembleLearningAligner.
👉 More end-to-end scripts are available in examples/, including aligner_pipeline.py, ensemble.py, flora.py, olala.py, and many more.
Comprehensive documentation, including detailed guides and examples, is available at ontoaligner.readthedocs.io. Below are key tutorials with links to both the documentation and the corresponding example scripts.
| Example | Tutorial | Script |
|---|---|---|
| Lightweight | 📚 Fuzzy Matching | 📝 Code |
| Retrieval | 📚 Retrieval Aligner | 📝 Code |
| Large Language Models | 📚 LLM Aligner | 📝 Code |
| Retrieval Augmented Generation | 📚 RAG Aligner | 📝 Code |
| FewShot | 📚 FewShot-RAG Aligner | 📝 Code |
| In-Context Vectors Learning | 📚 In-Context Vectors RAG | 📝 Code |
| Knowledge Graph Embedding | 📚 KGE Aligner | 📝 Code |
| Property Alignment | 📚 PropMatch Aligner | 📝 Code |
| FLORA (Knowledge Graphs) | 📚 FLORA Aligner | 📝 Code |
| OLaLa | 📚 OLaLa Aligner | 📝 Code |
| Ensemble Learning | 📚 Ensemble Learning | 📝 Code |
| eCommerce | 📚 Product Alignment in eCommerce | 📝 Code |
| Financial Corporate Actions | 📚 FIBO Corporate Actions Alignment | 📝 Code |
We welcome contributions to enhance OntoAligner and make it even better! Please review our contribution guidelines in CONTRIBUTING.md before getting started. You are also welcome to assist with the ongoing maintenance by referring to MAINTENANCE.md. Your support is greatly appreciated.
If you encounter any issues or have questions, please submit them in the GitHub issues tracker.
If you use OntoAligner in your work or research, please cite the following preprint:
OntoAligner Library:
Babaei Giglou, H., D'Souza, J., Karras, O., Auer, S. (2025). OntoAligner: A Comprehensive Modular and Robust Python Toolkit for Ontology Alignment. In: Curry, E., et al. The Semantic Web. ESWC 2025. Lecture Notes in Computer Science, vol 15719. Springer, Cham. https://doi.org/10.1007/978-3-031-94578-6_10
📌 BibTeX
@InProceedings{10.1007/978-3-031-94578-6_10, author="Babaei Giglou, Hamed and D'Souza, Jennifer and Karras, Oliver and Auer, S{\"o}ren", editor="Curry, Edward and Acosta, Maribel and Poveda-Villal{\'o}n, Maria and van Erp, Marieke and Ojo, Adegboyega and Hose, Katja and Shimizu, Cogan and Lisena, Pasquale", title="OntoAligner: A Comprehensive Modular and Robust Python Toolkit for Ontology Alignment", booktitle="The Semantic Web", year="2025", publisher="Springer Nature Switzerland", address="Cham", pages="174--191" }
LLMs4OM (for RAG module)
Babaei Giglou, H., D'Souza, J., Engel, F., Auer, S. (2025). LLMs4OM: Matching Ontologies with Large Language Models. In: Meroño Peñuela, A., et al. The Semantic Web: ESWC 2024 Satellite Events. ESWC 2024. Lecture Notes in Computer Science, vol 15344. Springer, Cham. https://doi.org/10.1007/978-3-031-78952-6_3
📌 BibTeX
@InProceedings{10.1007/978-3-031-78952-6_3, author="Babaei Giglou, Hamed and D'Souza, Jennifer and Engel, Felix and Auer, S{\"o}ren", editor="Mero{\~{n}}o Pe{\~{n}}uela, Albert and Corcho, Oscar and Groth, Paul and Simperl, Elena and Tamma, Valentina and Nuzzolese, Andrea Giovanni and Poveda-Villal{\'o}n, Maria and Sabou, Marta and Presutti, Valentina and Celino, Irene and Revenko, Artem and Raad, Joe and Sartini, Bruno and Lisena, Pasquale", title="LLMs4OM: Matching Ontologies with Large Language Models", booktitle="The Semantic Web: ESWC 2024 Satellite Events", year="2025", publisher="Springer Nature Switzerland", address="Cham", pages="25--35", isbn="978-3-031-78952-6" }
Knowledge Graph Embeddings based aligner
Giglou, Hamed Babaei, Jennifer D'Souza, Sören Auer, and Mahsa Sanaei. "OntoAligner Meets Knowledge Graph Embedding Aligners." arXiv preprint arXiv:2509.26417 (2025). https://arxiv.org/abs/2509.26417>
📌 BibTeX
@article{babaei2025ontoaligner, title={OntoAligner Meets Knowledge Graph Embedding Aligners}, author={Babaei Giglou, Hamed and D'Souza, Jennifer and Auer, S{\"o}ren and Sanaei, Mahsa}, journal={arXiv e-prints}, pages={arXiv--2509}, year={2025} }
This software is licensed under 