Refactor Navigation and KGE Pipeline: Consistent Entity Naming, Enhanced Evaluation, and Robust Config Management

[HernandezEduin]

Summary of Recent Changes

This pull request brings major refactors, feature enhancements, configuration changes, and bug fixes, particularly around navigation (supervised), KGE, and configuration management.

Highlights

• Consistent Data Schema and Naming

  • Standardized the codebase to use source_ent/Source-Entity throughout, replacing query_ent/Query-Entity and the use of query_rel (relation) where possible. This impacts all data loading, supervision, and environment interfaces.
  • Function signatures, docstrings, and data processing logic updated for consistency and clarity across supervised and RL navigation.

• Supervised Path Learning

  • Cleanup and removal of unnecessary variables and lines.
  • Added saving and loading functions for supervised navigation.
  • Config updates and added support for optional validation and model checkpointing.
  • Training, testing, and validation can now be performed independently.
  • Rollouts and noise injection added to training process.
  • Improved tqdm and metrics printing for easier monitoring.
  • Updated configs and sweeps for best performance (KinshipHinton, etc.).
  • Configurations added for reproducibility.
  • Fixed typo in filename: nav_superviced_training.py → nav_supervised_training.py.

• Knowledge Graph Embedding (KGE)

  • Moved KGE loading logic from training scripts to utility modules.
  • Log metrics and model saving functions refactored into utilities.
  • Embedded calculations and cleaning functions moved to appropriate utility files.
  • Best model loading for evaluation after training.
  • Added option for full graph training (navigability focus).
  • Improved config dump formatting for clarity.

• Configuration Management

  • Major reorganization: RL navigation and KGE configs/sweeps moved to dedicated directories.
  • Timestamps corrected to consistent format.
  • Store action now used for certain CLI arguments.
  • Improved data splitting: now recognizes both dev and test splits if present, with fallback to random splits.

• Reinforcement Learning and Environment

  • Added rollouts to supervised navigation and noise to agent position.
  • Added option for extrinsic reward calculation using FAISS or epsilon threshold.
  • Refactored rollout logic: now returns richer tensors, loss calculation done separately.
  • Environment now recycles answer ID tensors for efficiency.
  • Added and clarified metric variable names for disambiguation.
  • Improved initial state/embedding logic and batch handling for environment resets and RL episodes.

• Metrics and Evaluation

  • Enhanced evaluation routines: now computes Hits@1, Hits@3, Hits@5, Hits@10, Hits@20, and Mean Reciprocal Rank (MRR) with improved rank calculation.
  • Logging and output updated to match new metrics.
  • Improved nearest-neighbor search and reshaping for batch evaluation.

• General Refactoring

  • Refactored and consolidated code from exogenous/sun_models.py into utils modules for convenience, saving, cleaning, and metrics.
  • Removed obsolete triplet-saving and debugging code.
  • Improved variable naming, documentation, bugfixes for index/batch handling, and code maintainability throughout.

---

This PR introduces significant backend improvements, enhances reproducibility, and streamlines configuration and training workflows. It lays groundwork for future development and improves maintainability for navigation and embedding tasks.

Major affected files

• README.md
• mlm_training.py
• nav_supervised_training.py
• nav_training.py
• multihopkg/data_utils.py
• multihopkg/rl/graph_search/pn.py
• multihopkg/utils_debug/dump_evals.py
• multihopkg/vector_search.py

For the full commit list and details, see the commit history in the source repository.