Merge pull request #243 from sciknoworg/dev

add v1.1.1

Author: HamedBabaei

CHANGELOG.md

@@ -1,7 +1,13 @@
 ## Changelog
 
+### v1.1.1 (May 27, 2025)
+- add HF documentation
+- add license headers
+- refactor documentations
+- improve hf layout
+- add examples
 
-### v1.1.0 (May 13, 2025)
+### v1.1.0 (May 21, 2025)
 - Version changes
 - Refactor documentations
 - Add Readme

CITATION.cff

@@ -31,5 +31,5 @@ keywords:
   - Large Language Models
   - Text-to-ontology
 license: MIT
-version: 1.1.0
+version: 1.1.1
 date-released: '2025'

README.md

@@ -47,7 +47,7 @@ print(ontolearner.__version__)
 ## 🚀 Quick Tour
 Get started with OntoLearner in just a few lines of code. This guide demonstrates how to initialize ontologies, load datasets, and train an LLM-assisted learner for ontology engineering tasks.
 
-**Basic Usage**:
+**Basic Usage - Automatic Download from Hugging Face**:
 ```python
 from ontolearner.ontology import Wine
 
@@ -61,6 +61,17 @@ ontology.load()
 data = ontology.extract()
 ```
 
+**Basic Usage - Manual Download from Hugging Face**:
+```python
+from ontolearner.ontology import Wine
+
+# 1. Initialize an ontologizer from OntoLearner
+ontology = Wine()
+
+# 2. Download the ontology from Hugging Face
+file_path = ontology.from_huggingface()
+```
+
 **LLM-Based Learning Pipeline**:
 ```python
 from ontolearner import ontology, utils, learner
@@ -98,11 +109,9 @@ rag_learner.fit(train_data=train_data, task="term-typing")
 predicted = rag_learner.predict(test_data, task="term-typing")
 ```
 
-
-
 ## ⭐ Contribution
 
-We welcome contributions to enhance OntoLearner and make it even better! Please review our contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) before getting started.You are also welcome to assist with the ongoing maintenance by referring to [MAINTENANCE.md](MAINTENANCE.md). Your support is greatly appreciated.
+We welcome contributions to enhance OntoLearner and make it even better! Please review our contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) before getting started. You are also welcome to assist with the ongoing maintenance by referring to [MAINTENANCE.md](MAINTENANCE.md). Your support is greatly appreciated.
 
 
 If you encounter any issues or have questions, please submit them in the [GitHub issues tracker](https://github.com/sciknoworg/OntoLearner/issues).

docs/source/huggingface.rst

@@ -1,10 +1,91 @@
-HuggingFace
+HuggingFace Integration
 ==========================
+OntoLearner provides seamless integration with Hugging Face,
+allowing you to easily download ontologies and use pre-trained models.
+
+Ontology Repositories
+--------------------
 OntoLearner maintains a set of default repositories for each domain under the `SciKnowOrg` organization.
 These repositories follow the naming pattern `SciKnowOrg/ontolearner-{domain}` and contain pre-processed ontology data.
 
-Basic Usage
------------
+Available domains include:
+
+.. list-table:: OntoLearner Domain Repositories
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Domain
+     - Repository
+     - Description
+   * - Agriculture
+     - `ontolearner-agriculture <https://huggingface.co/datasets/SciKnowOrg/ontolearner-agriculture>`_
+     - Ontologies about farming systems, crops, food production, and agricultural vocabularies.
+   * - Arts and Humanities
+     - `ontolearner-arts_and_humanities <https://huggingface.co/datasets/SciKnowOrg/ontolearner-arts_and_humanities>`_
+     - Ontologies that describe music, iconography, cultural artifacts, and humanistic content.
+   * - Biology and Life Sciences
+     - `ontolearner-biology_and_life_sciences <https://huggingface.co/datasets/SciKnowOrg/ontolearner-biology_and_life_sciences>`_
+     - Ontologies about biological entities, systems, organisms, and molecular biology.
+   * - Chemistry
+     - `ontolearner-chemistry <https://huggingface.co/datasets/SciKnowOrg/ontolearner-chemistry>`_
+     - Ontologies describing chemical entities, reactions, methods, and computational chemistry models.
+   * - Ecology and Environment
+     - `ontolearner-ecology_and_environment <https://huggingface.co/datasets/SciKnowOrg/ontolearner-ecology_and_environment>`_
+     - Ontologies about ecological systems, environments, biomes, and sustainability science.
+   * - Education
+     - `ontolearner-education <https://huggingface.co/datasets/SciKnowOrg/ontolearner-education>`_
+     - Ontologies describing learning content, educational programs, competencies, and teaching resources.
+   * - Events
+     - `ontolearner-events <https://huggingface.co/datasets/SciKnowOrg/ontolearner-events>`_
+     - Ontologies for representing events, time, schedules, and calendar-based occurrences.
+   * - Finance
+     - `ontolearner-finance <https://huggingface.co/datasets/SciKnowOrg/ontolearner-finance>`_
+     - Ontologies describing economic indicators, e-commerce, trade, and financial instruments.
+   * - Food and Beverage
+     - `ontolearner-food_and_beverage <https://huggingface.co/datasets/SciKnowOrg/ontolearner-food_and_beverage>`_
+     - Ontologies related to food, beverages, ingredients, and culinary products.
+   * - General Knowledge
+     - `ontolearner-general_knowledge <https://huggingface.co/datasets/SciKnowOrg/ontolearner-general_knowledge>`_
+     - Broad-scope ontologies and upper vocabularies used across disciplines for general-purpose semantic modeling.
+   * - Geography
+     - `ontolearner-geography <https://huggingface.co/datasets/SciKnowOrg/ontolearner-geography>`_
+     - Ontologies for modeling spatial and geopolitical entities, locations, and place names.
+   * - Industry
+     - `ontolearner-industry <https://huggingface.co/datasets/SciKnowOrg/ontolearner-industry>`_
+     - Ontologies describing industrial processes, smart buildings, manufacturing systems, and equipment.
+   * - Law
+     - `ontolearner-law <https://huggingface.co/datasets/SciKnowOrg/ontolearner-law>`_
+     - Ontologies dealing with legal processes, regulations, and rights (e.g., copyright).
+   * - Library and Cultural Heritage
+     - `ontolearner-library_and_cultural_heritage <https://huggingface.co/datasets/SciKnowOrg/ontolearner-library_and_cultural_heritage>`_
+     - Ontologies used in cataloging, archiving, and authority control of cultural and scholarly resources.
+   * - Materials Science and Engineering
+     - `ontolearner-materials_science_and_engineering <https://huggingface.co/datasets/SciKnowOrg/ontolearner-materials_science_and_engineering>`_
+     - Ontologies related to materials, their structure, properties, processing, and engineering applications.
+   * - Medicine
+     - `ontolearner-medicine <https://huggingface.co/datasets/SciKnowOrg/ontolearner-medicine>`_
+     - Ontologies covering clinical knowledge, diseases, drugs, treatments, and biomedical data.
+   * - News and Media
+     - `ontolearner-news_and_media <https://huggingface.co/datasets/SciKnowOrg/ontolearner-news_and_media>`_
+     - Ontologies that model journalism, broadcasting, creative works, and media metadata.
+   * - Scholarly Knowledge
+     - `ontolearner-scholarly_knowledge <https://huggingface.co/datasets/SciKnowOrg/ontolearner-scholarly_knowledge>`_
+     - Ontologies modeling the structure, process, and administration of scholarly research, publications, and infrastructure.
+   * - Social Sciences
+     - `ontolearner-social_sciences <https://huggingface.co/datasets/SciKnowOrg/ontolearner-social_sciences>`_
+     - Ontologies for modeling societal structures, behavior, identity, and social interaction.
+   * - Units and Measurements
+     - `ontolearner-units_and_measurements <https://huggingface.co/datasets/SciKnowOrg/ontolearner-units_and_measurements>`_
+     - Ontologies defining scientific units, quantities, dimensions, and observational models.
+   * - Upper Ontology
+     - `ontolearner-upper_ontology <https://huggingface.co/datasets/SciKnowOrg/ontolearner-upper_ontology>`_
+     - Foundational ontologies that provide abstract concepts like objects, processes, and relations.
+   * - Web and Internet
+     - `ontolearner-web_and_internet <https://huggingface.co/datasets/SciKnowOrg/ontolearner-web_and_internet>`_
+     - Ontologies that model web semantics, linked data, APIs, and online communication standards.
+
+Loading Ontologies from Hugging Face
+-----------------------------------
 The simplest way to load an ontology from Hugging Face:
 
 .. code-block:: python
@@ -13,3 +94,14 @@ The simplest way to load an ontology from Hugging Face:
     ontology = Wine()
     ontology.load()  # automatically downloads from HuggingFace
     data = ontology.extract()
+
+This will automatically download the ontology file and pre-processed datasets from the appropriate Hugging Face repository.
+
+.. hint::
+   Each ontology repository on Hugging Face includes comprehensive documentation:
+
+   * **README.md**: Contains information about the domain and available ontologies
+   * **Citation Information**: How to cite the ontologies in academic work
+   * **Usage Examples**: Code snippets showing how to use the ontologies
+
+   For example, see the `SciKnowOrg/ontolearner-agriculture <https://huggingface.co/datasets/SciKnowOrg/ontolearner-agriculture>`_ repository.

docs/source/learners/learner.rst

@@ -1,2 +1,36 @@
 Learners
-=======================================
+========
+This section presents **three minimal, runnable walk-throughs** that showcase each
+learner type supported by *OntoLearner*:
+
+Authentication
+--------------
+Some models on Hugging Face require authentication. You can provide your Hugging Face token in several ways:
+1. **Environment Variable**: Set the `HUGGINGFACE_ACCESS_TOKEN` environment variable
+2. **Direct Parameter**: Pass the token directly to the constructor:
+
+   .. code-block:: python
+
+       llm = AutoLearnerLLM(token="your_huggingface_token")
+
+3. **.env File**: Create a `.env` file with your token:
+
+   .. code-block:: text
+
+       HUGGINGFACE_ACCESS_TOKEN=your_huggingface_token
+
+   Then load it in your script:
+
+   .. code-block:: python
+
+       from dotenv import find_dotenv, load_dotenv
+       _ = load_dotenv(find_dotenv())
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Available tutorials
+
+   retrieval.rst
+   llm.rst
+   rag.rst

docs/source/learners/llm.rst

@@ -1,2 +1,75 @@
 Large Language Models
 ========================
+LLM-only learners leverage the power of large language models to perform ontology learning tasks
+without using retrieval components. This approach is particularly useful when you want to rely
+on the model's inherent knowledge rather than specific examples from the training data.
+
+How LLM-only Learners Work
+--------------------------
+LLM-only learners operate by:
+1. **Prompting**: Formulating a task-specific prompt that describes the ontology learning task
+2. **Generation**: Using the LLM to generate a response based on the prompt and its pre-trained knowledge
+
+The methodology behind LLM-only learners relies on the model's ability to understand and interpret
+ontological concepts through prompt engineering. These prompts encode domain knowledge and task requirements,
+guiding the model to generate structured ontological elements such as taxonomies, relations,
+and concept classifications. The approach leverages the fact that pre-trained LLMs
+have internalized substantial background knowledge about various domains during their training,
+which can be accessed and systematically organized through appropriate prompting strategies
+without explicitly retrieving external knowledge.
+
+Setting Up an LLM-only Learner
+------------------------------
+Here's how to set up an LLM-only learner using the OntoLearner pipeline:
+
+.. code-block:: python
+
+    from ontolearner.learner_pipeline import LearnerPipeline
+    from ontolearner.learner import AutoLearnerLLM
+    from ontolearner.ontology import Wine
+    from ontolearner.utils.train_test_split import train_test_split
+
+    ontology = Wine()
+    ontology.load()
+    train_data, test_data = train_test_split(ontology.extract(), test_size=0.2)
+
+    pipeline = LearnerPipeline(
+        task="taxonomy-discovery",
+        llm=AutoLearnerLLM(token="your_huggingface_token"),
+        llm_id="mistralai/Mistral-7B-Instruct-v0.1"
+    )
+
+    results, metrics = pipeline.fit_predict_evaluate(
+        train_data=train_data,
+        test_data=test_data,
+        test_limit=10
+    )
+
+Supported Models
+----------------
+OntoLearner supports various LLM models, including:
+
+- Mistral models (e.g., "mistralai/Mistral-7B-Instruct-v0.1")
+- Llama models (e.g., "meta-llama/Llama-3.1-8B-Instruct")
+- Qwen models (e.g., "Qwen/Qwen3-0.6B")
+- DeepSeek models (e.g., "deepseek-ai/deepseek-llm-7b-base")
+
+Supported Tasks
+---------------
+LLM-only learners support all three main ontology learning tasks:
+
+1. **Term Typing**: Predicting the type(s) of a given term
+2. **Taxonomy Discovery**: Identifying hierarchical relationships
+3. **Non-Taxonomy Discovery**: Identifying non-hierarchical relationships
+
+Example
+-------
+For a complete example of using an LLM-only learner, see the example script:
+
+.. code-block:: bash
+
+    python scripts/examples/learner_example_llm.py
+
+.. note::
+
+   The code is available at `OntoLearner GitHub repository <https://github.com/sciknoworg/OntoLearner/blob/dev/scripts/examples/learner_example_llm.py>`_

docs/source/learners/rag.rst

@@ -1,2 +1,66 @@
 Retrieval Augmented Generation
-=======================================
+==============================
+RAG (Retrieval Augmented Generation) learners combine the strengths of both retrieval models
+and large language models to perform ontology learning tasks.
+
+How RAG Learners Work
+---------------------
+RAG learners operate in two main steps:
+1. **Retrieval**: First, the retriever component finds the most relevant examples from the training data based on similarity to the input query.
+2. **Generation**: Then, the LLM component uses these retrieved examples as context to generate a response.
+
+The methodology behind RAG learners combines vector retrieval with generative language modeling
+to enhance ontology learning tasks. This hybrid approach addresses the limitations of using LLMs alone
+by grounding the model's responses in specific ontological examples from the training data.
+By encoding ontological elements into a vector space, the retriever can identify semantically similar concepts,
+relations, or taxonomic structures. These retrieved examples serve as few-shot demonstrations
+that provide the LLM with domain-specific context, enabling more accurate and consistent ontological inferences.
+This approach is particularly effective for specialized domains where the model's pre-trained knowledge
+may be insufficient or where precise ontological alignments are critical.
+
+Setting Up a RAG Learner
+------------------------
+Here's how to set up a RAG learner using the OntoLearner pipeline:
+
+.. code-block:: python
+
+    from ontolearner.learner_pipeline import LearnerPipeline
+    from ontolearner.ontology import Wine
+    from ontolearner.utils.train_test_split import train_test_split
+
+    ontology = Wine()
+    ontology.load()
+    train_data, test_data = train_test_split(ontology.extract(), test_size=0.2)
+
+    pipeline = LearnerPipeline(
+        task="term-typing",
+        retriever_id="sentence-transformers/all-MiniLM-L6-v2",
+        llm_id="mistralai/Mistral-7B-Instruct-v0.1",
+        hf_token="your_huggingface_token"
+    )
+
+    results, metrics = pipeline.fit_predict_evaluate(
+        train_data=train_data,
+        test_data=test_data,
+        top_k=3,
+        test_limit=10
+    )
+
+Supported Tasks
+---------------
+RAG learners support all three main ontology learning tasks:
+1. **Term Typing**: Predicting the type(s) of a given term
+2. **Taxonomy Discovery**: Identifying hierarchical relationships
+3. **Non-Taxonomy Discovery**: Identifying non-hierarchical relationships
+
+Example
+-------
+For a complete example of using a RAG learner, see the example script:
+
+.. code-block:: bash
+
+    python scripts/examples/learner_example_rag.py
+
+.. note::
+
+   The code is available at `OntoLearner GitHub repository <https://github.com/sciknoworg/OntoLearner/blob/dev/scripts/examples/learner_example_rag.py>`_