feat: Introduce `equilib` package with RLHF steering and Sperner dataset generation examples, and add project license.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Oussama Mesbah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,5 +1,27 @@
+---
+title: Topo-Align (Equilib)
+emoji: 🧬
+colorFrom: blue
+colorTo: indigo
+sdk: null
+pinned: true
+license: mit
+tags:
+  - reinforcement-learning
+  - rlhf
+  - alignment
+  - topology
+  - mathematics
+  - sperner-lemma
+  - human-in-the-loop
+  - library
+  - custom-implementation
+---
+
 # Topo-Align (Equilib)
 
+[![Hugging Face Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Dataset-green)](https://huggingface.co/datasets/omesbah/sperner-bench)
+
 **Gradient-Free Multi-Objective Alignment for Large Language Models using Topological Fixed-Point Theory**
 
 Topo-Align is a specialized library designed for the alignment of large language models (LLMs) across multiple, often conflicting, objectives (e.g., safety, helpfulness, and creative expression). Utilizing the principles of Combinatorial Topology, specifically Sperner's Lemma, Topo-Align treats the alignment process as a mathematical fixed-point problem rather than a traditional optimization task.
@@ -18,9 +40,9 @@ In contrast, Topo-Align provides:
 
 ## Comparative Analysis
 
-| Feature                      | Linear Scalarization             | Grid/Bayesian Search        | Topo-Align (Equilib)                         |
-| :--------------------------- | :------------------------------- | :-------------------------- | :------------------------------------------- |
-| **Primary Logic**      | Weighted Sum Optimization        | Stochastic Sampling         | Sperner Fixed-Point Walk                     |
+| Feature                | Linear Scalarization             | Grid/Bayesian Search        | Topo-Align (Equilib)                   |
+| :--------------------- | :------------------------------- | :-------------------------- | :------------------------------------- |
+| **Primary Logic**      | Weighted Sum Optimization        | Stochastic Sampling         | Sperner Fixed-Point Walk               |
 | **Scaling Complexity** | O(1) (Static)                    | O(k^N) (Exponential)        | **O(N) Memory (Linear Scalability)**   |
 | **Reliability**        | Susceptible to gradient collapse | High risk of missing optima | **Guaranteed convergence**             |
 | **Diagnostics**        | No inherent conflict metrics     | Visual inspection only      | **Topological Frustration Score**      |
@@ -104,8 +126,8 @@ optimal_weights = solver.solve_with_surrogate(max_iterations=15)
 
 ## Core Components
 
-| Component                      | Module                      | Description                                                         |
-| :----------------------------- | :-------------------------- | :------------------------------------------------------------------ |
+| Component                | Module                    | Description                                                         |
+| :----------------------- | :------------------------ | :------------------------------------------------------------------ |
 | **N-Dimensional Solver** | `ndim_topo_align.py`      | The primary engine implementing implicit Freudenthal triangulation. |
 | **Sperner Trainer**      | `sperner_trainer.py`      | Integration layer for Hugging Face Transformers and PEFT.           |
 | **Analytics Suite**      | `analytics.py`            | Diagnostic tools including the Topological Frustration Score.       |
@@ -121,3 +143,17 @@ optimal_weights = solver.solve_with_surrogate(max_iterations=15)
 ## License
 
 This project is licensed under the MIT License.
+
+## 📖 Citation
+
+If you find this project useful for your research, please consider citing:
+
+```bibtex
+@misc{mesbah2024topoalign,
+    title={Fixpunktsätze und ihre Anwendungen (Fixed Point Theorems and their Applications)},
+    author={Mesbah, Oussama}, 
+    howpublished={\url{https://huggingface.co/omesbah/topo-align}},
+    year={2024},
+    note={Bachelor's Thesis, Ludwig-Maximilians-Universität München}
+}
+```

equilib/__init__.py

@@ -1,6 +1,8 @@
 from .topo_align import TopoAlignSolver
 from .adaptive_topo_align import AdaptiveTopoAlignSolver
 from .surrogate_topo_align import SurrogateTopoAlignSolver, NDimSurrogateTopoAlignSolver
+__version__ = "0.1.0"
+
 from .ndim_topo_align import NDimTopoAlignSolver
 from .sperner_trainer import SpernerTrainer
 

examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+This directory contains standalone scripts demonstrating the capabilities of the Topo-Align (Equilib) library.
+
+- `rlhf_steering_demo.py`: Simulates a Multi-Objective RLHF environment (Helpfulness, Safety, Verbosity) and uses the topological solver to find optimal reward mixing weights.
+- `generate_sperner_dataset.py`: The utility used to create the `sperner-bench` dataset, demonstrating how to generate high-dimensional simplex triangulations.
+
+## How to run
+From the repository root:
+```bash
+python examples/rlhf_steering_demo.py
+```

{equilib → examples}/rlhf_steering_demo.py

@@ -1,6 +1,10 @@
-import numpy as np
-import sys
 import os
+import sys
+
+# Ensure repository root is in path for imports
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+import numpy as np
 
 # Create a mock RLHF environment
 # Three objectives: [Helpfulness, Safety, Verbosity]

tools/equilib_login.py

@@ -0,0 +1,22 @@
+from huggingface_hub import login
+import getpass
+import sys
+
+def secure_login():
+    print("--- Topo-Align Hugging Face Authentication ---")
+    print("Please generate a 'Write' token at: https://huggingface.co/settings/tokens")
+    try:
+        token = getpass.getpass("Paste your Hugging Face Write Token (input is hidden): ")
+        if not token:
+            print("Error: No token provided.")
+            return
+        
+        login(token=token, add_to_git_credential=True)
+        print("\n[SUCCESS] Login successful! Your session is now saved.")
+        print("You can now tell the assistant: 'I am logged in'.")
+    except Exception as e:
+        print(f"\n[ERROR] Login failed: {e}")
+        print("Please ensure you have an active internet connection and the token is valid.")
+
+if __name__ == "__main__":
+    secure_login()