Add settings module and initial tests.

.github/workflows/python-ci.yaml

@@ -0,0 +1,23 @@
+name: python-ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  uv-example:
+    name: python
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev --index-strategy=unsafe-best-match
+
+      - name: Run tests
+        run: uv run pytest

blossomtune_gradio/config.py

@@ -2,6 +2,8 @@ import os
 
 from blossomtune_gradio import util
 
+# BlossomTune yaml config path
+BLOSSOMTUNE_CONFIG = os.getenv("BLOSSOMTUNE_CONFIG", None)
 
 # HF Space ID
 SPACE_ID = os.getenv("SPACE_ID", "ethicalabs/BlossomTune-Orchestrator")

blossomtune_gradio/settings/__init__.py

@@ -0,0 +1,116 @@
+import os
+import yaml
+import json
+from typing import Any, Dict
+from jsonschema import validate, ValidationError
+from jinja2 import Template
+
+from blossomtune_gradio import config as cfg
+
+
+class Settings:
+    """Handles loading and validation of UI text from a YAML file."""
+
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if not cls._instance:
+            cls._instance = super(Settings, cls).__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def _reset_instance_for_testing(cls):
+        """
+        Resets the singleton instance.
+        This method should ONLY be used in tests.
+        """
+        cls._instance = None
+
+    def __init__(self, config_path: str | None = None, schema_path: str | None = None):
+        """
+        Initializes the settings object.
+        The initialization logic runs only once per instance lifecycle.
+        """
+        # Use an instance-level flag to prevent re-initialization.
+        if hasattr(self, "_initialized_instance"):
+            return
+
+        module_dir = os.path.dirname(__file__)
+
+        # Always initialize attributes to ensure the object is in a consistent state.
+        self.templates: Dict[str, Template] = {}
+        # Prioritize env var, then passed arg, then default
+        self.config_path = (
+            cfg.BLOSSOMTUNE_CONFIG
+            or config_path
+            or os.path.join(module_dir, "blossomtune.yaml")
+        )
+        self.schema_path = schema_path or os.path.join(
+            module_dir, "blossomtune.schema.json"
+        )
+
+        # Load the configuration.
+        self._load_config()
+
+        # Mark this specific instance as initialized.
+        self._initialized_instance = True
+
+    def _load_config(self) -> bool:
+        """
+        Loads YAML config, validates it, and compiles Jinja2 templates.
+        This method populates self.templates on success or prints errors on failure.
+        Returns True on success, False on any failure.
+        """
+        # Check for and validate the main config file
+        try:
+            with open(self.config_path, "r") as f:
+                # safe_load can return None for an empty file, which is not an error itself
+                config = yaml.safe_load(f)
+                # If the file is not empty but safe_load returns None, it's invalid YAML
+                if config is None and os.fstat(f.fileno()).st_size > 0:
+                    raise yaml.YAMLError("Contains non-YAML content.")
+        except FileNotFoundError:
+            print(f"Error: Configuration file not found at {self.config_path}")
+            return False
+        except yaml.YAMLError as e:
+            print(f"Error parsing YAML file: {e}")
+            return False
+
+        # Check for and validate the schema file
+        try:
+            with open(self.schema_path, "r") as f:
+                schema = json.load(f)
+        except FileNotFoundError:
+            print(f"Error: JSON schema not found at {self.schema_path}")
+            return False
+        except json.JSONDecodeError as e:
+            print(f"Error parsing JSON schema: {e}")
+            return False
+
+        # Validate the config against the schema
+        try:
+            # The config can be None if the YAML file was empty.
+            validate(instance=config, schema=schema)
+        except ValidationError as e:
+            print(f"Error: YAML configuration is invalid. {e.message}")
+            return False
+
+        # If everything is valid, compile the templates
+        if config:
+            ui_config = config.get("ui", {})
+            for key, value in ui_config.items():
+                if isinstance(value, str):
+                    self.templates[key] = Template(value)
+
+        return True
+
+    def get_text(self, key: str, **kwargs: Any) -> str:
+        """Renders a Jinja2 template with the given context."""
+        if key in self.templates:
+            return self.templates[key].render(**kwargs)
+        return f"Warning: Text for '{key}' not found."
+
+
+# Singleton instance that runs on first import.
+# The _reset_instance_for_testing method is for isolating tests from this initial state.
+settings = Settings()

blossomtune_gradio/settings/blossomtune.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BlossomTune UI Configuration Schema",
+  "description": "Schema for validating the blossomtune.yaml UI text configuration.",
+  "type": "object",
+  "properties": {
+    "ui": {
+      "type": "object",
+      "description": "Contains all user-interface text templates.",
+      "properties": {
+        "welcome_message_md": {
+          "type": "string",
+          "description": "Message shown to welcome the user."
+        },
+        "error_message_md": {
+          "type": "string",
+          "description": "Message shown when an error occurs."
+        },
+        "auth_required_md": {
+          "type": "string",
+          "description": "Message shown when a user needs to log in."
+        },
+        "hf_handle_empty_md": {
+          "type": "string",
+          "description": "Error for an empty Hugging Face handle."
+        },
+        "invalid_email_md": {
+          "type": "string",
+          "description": "Error for an invalid email format."
+        },
+        "federation_full_md": {
+          "type": "string",
+          "description": "Message shown when no new participants can join."
+        },
+        "activation_invalid_md": {
+          "type": "string",
+          "description": "Error for an incorrect activation code."
+        },
+        "registration_submitted_md": {
+          "type": "string",
+          "description": "Confirmation after a user submits a join request."
+        },
+        "activation_successful_md": {
+          "type": "string",
+          "description": "Confirmation after successful email activation."
+        },
+        "missing_activation_code_md": {
+          "type": "string",
+          "description": "Message prompting the user to enter their activation code."
+        },
+        "status_approved_md": {
+          "type": "string",
+          "description": "Message for an approved participant, including connection details. JINJA2: {{ participant_id }}, {{ partition_id }}, {{ superlink_hostname }}, {{ num_partitions }}"
+        },
+        "status_pending_md": {
+          "type": "string",
+          "description": "Status message for a request awaiting admin review."
+        },
+        "status_denied_md": {
+          "type": "string",
+          "description": "Message for a denied participant. JINJA2: {{ participant_id }}"
+        },
+        "participant_not_activated_warning": {
+          "type": "string",
+          "description": "Admin warning when trying to approve a non-activated user."
+        },
+        "partition_in_use_warning": {
+          "type": "string",
+          "description": "Admin warning for an already assigned partition ID. JINJA2: {{ partition_id }}"
+        },
+        "auth_status_logged_in_owner_md": {
+          "type": "string",
+          "description": "Auth status for the space owner. JINJA2: {{ profile.username }}"
+        },
+        "auth_status_logged_in_user_md": {
+          "type": "string",
+          "description": "Auth status for a regular logged-in user. JINJA2: {{ profile.username }}"
+        },
+        "auth_status_not_logged_in_md": {
+          "type": "string",
+          "description": "Auth status when the user is not logged in."
+        },
+        "auth_status_local_mode_md": {
+          "type": "string",
+          "description": "Auth status when running the app locally."
+        }
+      },
+      "required": [
+        "welcome_message_md",
+        "error_message_md",
+        "auth_required_md",
+        "hf_handle_empty_md",
+        "invalid_email_md",
+        "federation_full_md",
+        "activation_invalid_md",
+        "registration_submitted_md",
+        "activation_successful_md",
+        "missing_activation_code_md",
+        "status_approved_md",
+        "status_pending_md",
+        "status_denied_md",
+        "participant_not_activated_warning",
+        "partition_in_use_warning",
+        "auth_status_logged_in_owner_md",
+        "auth_status_logged_in_user_md",
+        "auth_status_not_logged_in_md",
+        "auth_status_local_mode_md"
+      ]
+    }
+  },
+  "required": ["ui"]
+}

blossomtune_gradio/settings/blossomtune.yaml

@@ -0,0 +1,82 @@
+# Configuration for BlossomTune Orchestrator
+# This file uses Jinja2 templating for dynamic content.
+
+ui:
+  # --- Join Federation Tab ---
+  welcome_message_md: |
+    Hello!
+  error_message_md: |
+    An error occurred!
+  auth_required_md: |
+    ### Authentication Required
+    **Please log in with Hugging Face to request to join the federation.**
+  
+  hf_handle_empty_md: |
+    ### Invalid Input
+    Hugging Face handle cannot be empty.
+  
+  invalid_email_md: |
+    ### Invalid Input
+    Please provide a valid email address.
+    
+  federation_full_md: |
+    ### Federation Full
+    **We're sorry, but we cannot accept new participants at this time.**
+
+  activation_invalid_md: |
+    ### ❌ Activation Failed
+    The activation code is not valid, or the participant has not subscribed yet.
+
+  registration_submitted_md: |
+    ### ✅ Registration Submitted!
+    Please check your email for an activation code to complete your request.
+    
+  activation_successful_md: |
+    ### ✅ Activation Successful!
+    Your request is now pending review by an administrator.
+
+  missing_activation_code_md: |
+    ### ⏳ Missing Activation Code
+    Please check your email and enter the activation code you received.
+
+  status_approved_md: |
+    ### ✅ Approved
+    Your request for ID `{{ participant_id }}` has been approved.
+    - **Your Assigned Partition ID:** `{{ partition_id }}`
+    - **Superlink Address:** `{{ superlink_hostname }}:9092`
+
+    **Instructions:** Your Flower client code should use your assigned Partition ID to load the correct data subset.
+    The server address is for your client's connection command.
+    
+    *Example `flower-supernode` command:*
+    ```bash
+    flower-supernode --superlink {{ superlink_hostname }}:9092 --insecure --node-config "partition-id={{ partition_id }} num-partitions={{ num_partitions }}"
+    ```
+
+  status_pending_md: |
+    ### ⏳ Pending
+    Your request has been activated and is awaiting administrator review.
+    
+  status_denied_md: |
+    ### ❌ Denied
+    Your request for ID `{{ participant_id }}` has been denied.
+
+  # --- Admin Panel ---
+  participant_not_activated_warning: |
+    This participant has not activated their email yet. Approval is not allowed.
+    
+  partition_in_use_warning: |
+    Partition ID {{ partition_id }} is already assigned. Please choose a different one.
+
+  # --- Authentication Status ---
+  auth_status_logged_in_owner_md: |
+    ✅ Logged in as **{{ profile.username }}**. You are the space owner.
+
+  auth_status_logged_in_user_md: |
+    Logged in as: **{{ profile.username }}**.
+  
+  auth_status_not_logged_in_md: |
+    ⚠️ You are not logged in. Please log in with Hugging Face.
+    
+  auth_status_local_mode_md: |
+    Running in local mode. Admin controls enabled.

pyproject.toml

@@ -13,7 +13,8 @@ dependencies = [
     "transformers>=4.56.1",
     "scikit-learn>=1.7.1",
     "evaluate>=0.4.5",
-    "markupsafe==2.1.3"
+    "markupsafe==2.1.3",
+    "jinja2>=3.1.6",
 ]
 
 [tool.uv.sources]
@@ -75,6 +76,7 @@ pythonpath = "."
 addopts = [
     "--import-mode=importlib",
 ]
+testpaths = ["tests"]
 
 [build-system]
 requires = ["setuptools>=61.0", "wheel", "build"]

tests/test_settings.py

@@ -0,0 +1,148 @@
+import pytest
+import yaml
+import json
+from unittest.mock import patch
+
+# Import the Settings class specifically to allow for instance management in tests
+from blossomtune_gradio.settings import Settings
+
+
+@pytest.fixture(autouse=True)
+def reset_settings_singleton():
+    """
+    Fixture to automatically reset the Settings singleton before each test.
+    This allows creating a new, clean instance for each test scenario by
+    directly resetting the internal `_instance` variable.
+    """
+    Settings._instance = None
+
+
+@pytest.fixture
+def valid_config_files(tmp_path):
+    """Creates a valid config and schema file in a temporary directory."""
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    config_content = {
+        "ui": {
+            "welcome_message_md": "Hello, {{ name }}!",
+            "error_message_md": "An error occurred.",
+        }
+    }
+    schema_content = {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+            "ui": {
+                "type": "object",
+                "properties": {
+                    "welcome_message_md": {"type": "string"},
+                    "error_message_md": {"type": "string"},
+                },
+                "required": ["welcome_message_md", "error_message_md"],
+            }
+        },
+        "required": ["ui"],
+    }
+
+    config_path = config_dir / "blossomtune.yaml"
+    schema_path = config_dir / "blossomtune.schema.json"
+
+    with open(config_path, "w") as f:
+        yaml.dump(config_content, f)
+    with open(schema_path, "w") as f:
+        json.dump(schema_content, f)
+
+    return str(config_path), str(schema_path)
+
+
+def test_load_valid_config(valid_config_files):
+    """Tests successful loading of a valid configuration."""
+    config_path, schema_path = valid_config_files
+    settings = Settings(config_path=config_path, schema_path=schema_path)
+
+    assert "welcome_message_md" in settings.templates
+    assert "error_message_md" in settings.templates
+
+    rendered_text = settings.get_text("welcome_message_md", name="World")
+    assert rendered_text == "Hello, World!"
+
+
+def test_missing_config_file(tmp_path, capsys):
+    """Tests handling of a missing configuration file and captures stdout."""
+    schema_path = tmp_path / "schema.json"
+    schema_path.touch()  # Create an empty schema for the test
+    settings = Settings(config_path="nonexistent.yaml", schema_path=str(schema_path))
+
+    assert not settings.templates
+
+    # Check that an error was printed to the console
+    captured = capsys.readouterr()
+    assert "Error: Configuration file not found" in captured.out
+
+
+def test_invalid_yaml_file(tmp_path, capsys):
+    """Tests handling of a syntactically incorrect YAML file."""
+    config_path = tmp_path / "invalid.yaml"
+    schema_path = tmp_path / "schema.json"
+    schema_path.touch()
+
+    with open(config_path, "w") as f:
+        f.write("ui: { welcome: 'Hello'")  # Malformed YAML
+
+    settings = Settings(config_path=str(config_path), schema_path=str(schema_path))
+    assert not settings.templates
+    captured = capsys.readouterr()
+    assert "Error parsing YAML file" in captured.out
+
+
+def test_schema_validation_failure(tmp_path, capsys):
+    """Tests that validation fails if the config doesn't match the schema."""
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+
+    # Config is missing the required 'error_message'
+    config_content = {"ui": {"welcome_message_md": "Hello!"}}
+    schema_content = {
+        "type": "object",
+        "properties": {"ui": {"type": "object", "required": ["error_message_md"]}},
+    }
+
+    config_path = config_dir / "blossomtune.yaml"
+    schema_path = config_dir / "blossomtune.schema.json"
+
+    with open(config_path, "w") as f:
+        yaml.dump(config_content, f)
+    with open(schema_path, "w") as f:
+        json.dump(schema_content, f)
+
+    settings = Settings(config_path=str(config_path), schema_path=str(schema_path))
+    assert not settings.templates
+    captured = capsys.readouterr()
+    assert "Error: YAML configuration is invalid" in captured.out
+
+
+@patch("blossomtune_gradio.config.BLOSSOMTUNE_CONFIG")
+def test_load_from_env_variable(mock_config_env, valid_config_files):
+    """Tests loading the config path from an environment variable."""
+    config_path, schema_path = valid_config_files
+    mock_config_env = config_path
+
+    # By patching the config module, the Settings constructor will pick it up
+    with patch("blossomtune_gradio.settings.cfg.BLOSSOMTUNE_CONFIG", mock_config_env):
+        settings = Settings(schema_path=schema_path)
+
+    assert settings.config_path == config_path
+    rendered_text = settings.get_text("welcome_message_md", name="From Env")
+    assert rendered_text == "Hello, From Env!"
+
+
+def test_singleton_pattern(valid_config_files):
+    """Tests that the same instance of Settings is always returned."""
+    config_path, schema_path = valid_config_files
+    s1 = Settings(config_path=config_path, schema_path=schema_path)
+    s2 = Settings()  # Should return the same instance as s1
+
+    assert s1 is s2
+    # Verify s2 is configured, proving it's the same instance
+    assert "welcome_message_md" in s2.templates

uv.lock

@@ -231,6 +231,7 @@ dependencies = [
     { name = "flwr", extra = ["simulation"] },
     { name = "flwr-datasets" },
     { name = "gradio", extra = ["oauth"] },
+    { name = "jinja2" },
     { name = "markupsafe" },
     { name = "scikit-learn" },
     { name = "torch", version = "2.8.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform == 'darwin'" },
@@ -250,6 +251,7 @@ requires-dist = [
     { name = "flwr", extras = ["simulation"], specifier = ">=1.21.0" },
     { name = "flwr-datasets", specifier = ">=0.5.0" },
     { name = "gradio", extras = ["oauth"], specifier = ">=5.44.1" },
+    { name = "jinja2", specifier = ">=3.1.6" },
     { name = "markupsafe", specifier = "==2.1.3" },
     { name = "scikit-learn", specifier = ">=1.7.1" },
     { name = "torch", specifier = ">=2.8.0", index = "https://download.pytorch.org/whl/cpu" },