experiment_server 0.3.6__tar.gz → 0.3.7__tar.gz

{experiment_server-0.3.6 → experiment_server-0.3.7}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.3
 Name: experiment_server
-Version: 0.3.6
+Version: 0.3.7
 Summary: Server for experiments to get configuarations from
 License: MIT
 Keywords: experiment,study-design
 Author: Ahmed Shariff
 Author-email: shariff.mfa@outlook.com
-Requires-Python: >=3.8
+Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 1 - Planning
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -26,11 +24,13 @@ Requires-Dist: click-aliases (>=1.0.4)
 Requires-Dist: easydict (>=1)
 Requires-Dist: importlib-metadata (>=6.8.0)
 Requires-Dist: loguru (>=0.5,<0.6)
-Requires-Dist: pandas (>=1)
 Requires-Dist: requests (>=2.25.1)
 Requires-Dist: tabulate (>=0.8.9)
+Requires-Dist: textual (>=7.5.0,<8.0.0)
 Requires-Dist: toml (>=0.10.2)
 Requires-Dist: tornado (>=6.2)
+Requires-Dist: tree-sitter (>=0.25.2,<0.26.0)
+Requires-Dist: tree-sitter-toml (>=0.7.0,<0.8.0)
 Requires-Dist: watchdog (>=2.1.9)
 Project-URL: Documentation, https://shariff-faleel.com/experiment_server/documentation/
 Project-URL: Homepage, https://shariff-faleel.com/experiment_server/
@@ -48,6 +48,7 @@ Documentation is available at [https://shariff-faleel.com/experiment_server/](ht
 - [Overview](#overview)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Textual UI (TUI)](#textual-ui-tui)
   - [Configuration of an experiment](#configuration-of-an-experiment)
   - [Verify config](#verify-config)
   - [Loading experiment through server](#loading-experiment-through-server)
@@ -72,6 +73,55 @@ $ poetry add experiment-server
 ```
 
 # Usage
+## Textual UI (TUI)
+
+A terminal-based user interface is provided for interactive management and monitoring of an experiment. It is useful when you want a lightweight, keyboard-driven interface to load configs, inspect/generate per‑participant configs, edit files, and control participant flow without using the web UI.
+
+Launch the TUI with:
+
+```sh
+# Start TUI (optionally provide a config file)
+$ experiment-server ui
+$ experiment-server ui -c sample_config.toml
+
+# Common options
+$ experiment-server ui -c sample_config.toml -i 1 -h 127.0.0.1 -p 5000
+```
+
+Options:
+- -c, --config-file : path to a .toml config to load on start (optional).
+- -i, --default-participant-index : default participant index to use when no explicit participant id is provided (default 1).
+- -h, --host : host/interface for the server (default 127.0.0.1).
+- -p, --port : port for the server (default 5000).
+
+Behavior and features
+- Can be started without a config file; load a config later from the built-in file browser (filters to directories and .toml files).
+- When a config is loaded the package starts the server in the same event loop, exposing the same REST API described elsewhere in this README.
+- Participant management:
+  - View all participants and their status, block id and block name.
+  - Create new participants (auto id or a specific id).
+  - Move the default or a specific participant to the next block or to a specific block id.
+  - Move all active participants to a block.
+  - Reset a participant.
+  - Choose a monitored participant to view its current config and status.
+- Config management:
+  - View the currently loaded .toml contents in a code editor pane.
+  - Edit the config in place and save; saving writes the file and the app will attempt to reload the config.
+  - Generate new config files using simple or advanced helpers (write a minimal example or build from JSON-specified order/blocks/parameters).
+  - Generate expanded JSON configs for a range of participant indices (write output to a directory).
+- Live logging pane shows application logs for actions and errors.
+- A simple edit UI is available to tweak the in-memory per-participant config (submit or cancel edits).
+
+Notes
+- Editing and saving the config file from the TUI writes to the same config path the server is using; the TUI will attempt to reload the new configuration but will preserve participant state (see server behavior note in the [Loading experiment through server](#loading-experiment-through-server) section).
+- The TUI requires the textual/Rich environment provided by the package (normally installed with the package). Use `Ctrl+q` to exit or the TUI's quit action.
+
+This TUI is intended as a compact, interactive alternative to the web interface for quick testing, config edits, and participant control.
+<p style="display:flex; gap:8px; align-items:flex-start;">
+  <img src="https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot_tui1.png" alt="web UI screenshot 1" style="width:49%;">
+  <img src="https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot_tui2.png" alt="web UI screenshot 2" style="width:49%;">
+</p>
+
 ## Configuration of an experiment
 The configuration is defined in a [toml](https://toml.io/en/) file. 
 
@@ -311,6 +361,8 @@ See [toml spec](https://toml.io/en/v1.0.0) for more information on the format of
 ```
 </details>
 
+See [construct_participant_condition][experiment_server._participant_ordering.construct_participant_condition] and [process_config_file][experiment_server._process_config.process_config_file] for more information.
+
 ## Verify config
 A config file can be validated by running:
 ```sh
@@ -318,6 +370,8 @@ $ experiment-server verify-config-file sample_config.toml
 ```
 This will show how the expanded config looks like for the first 5 participants.
 
+See also [verify_config][experiment_server._process_config.verify_config]
+
 ## Loading experiment through server
 After installation, the server can used as:
 
@@ -359,7 +413,7 @@ The server exposes the following REST API:
 
 - [PUT] `/api/add-participant/:participant-id` - Add a new participant with `participant-id`. If there is already a participant with the `participant-id`, this will fail. 
 
-For a Python application, `experiment_server.Client` can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
+For a Python application, [`experiment_server.Client`][experiment_server.Client] can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
 
 **NOTE**: If the config file served is changed, the new config will be loaded, but the state of the participants will be maintained. i.e., the added participants and the block id they are at will not change. To move the block ids for all active participants, you would have to call the `move-all-to-block` endpoint.
 
@@ -369,7 +423,7 @@ The server also provides a simple web interface, which can be accessed at `/` or
 
 
 ## Loading experiment through API
-A configuration can be loaded and managed by importing `experiment_server.Experiment`.
+A configuration can be loaded and managed by importing [`experiment_server.Experiment`][experiment_server.Experiment].
 
 ## Generate expanded configs
 A config file (i.e. `.toml` file), can be expanded to JSON with the following command
@@ -380,6 +434,8 @@ $ experiment-server generate-config-json sample_config.toml --participant-range
 
 The above will generate the expanded configs for participant indices 1 to 5 as JSON output on stdout. This result can be written out to individual JSON files by setting the `--out-dir`/`-d` to a directory. See more options with `--help`
 
+See also [_generate_config_json][experiment_server._api._generate_config_json]
+
 ## Function calls in config
 A function call in the config is represented by a table, with the following keys 
 - `function_name`: This should be one of the names in the supported functions list below.
@@ -402,7 +458,3 @@ param = { foo = "test", bar = { function_name = "choices", args = { population =
 
 For more on the `experiemnt-server` and how it can be used see the [wiki](https://github.com/ahmed-shariff/experiment_server/wiki)
 
-# Wishlist (todo list?)
-- Improved docs
-  - Add the option of using dict values in order
-

{experiment_server-0.3.6 → experiment_server-0.3.7}/README.md

@@ -9,6 +9,7 @@ Documentation is available at [https://shariff-faleel.com/experiment_server/](ht
 - [Overview](#overview)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Textual UI (TUI)](#textual-ui-tui)
   - [Configuration of an experiment](#configuration-of-an-experiment)
   - [Verify config](#verify-config)
   - [Loading experiment through server](#loading-experiment-through-server)
@@ -33,6 +34,55 @@ $ poetry add experiment-server
 ```
 
 # Usage
+## Textual UI (TUI)
+
+A terminal-based user interface is provided for interactive management and monitoring of an experiment. It is useful when you want a lightweight, keyboard-driven interface to load configs, inspect/generate per‑participant configs, edit files, and control participant flow without using the web UI.
+
+Launch the TUI with:
+
+```sh
+# Start TUI (optionally provide a config file)
+$ experiment-server ui
+$ experiment-server ui -c sample_config.toml
+
+# Common options
+$ experiment-server ui -c sample_config.toml -i 1 -h 127.0.0.1 -p 5000
+```
+
+Options:
+- -c, --config-file : path to a .toml config to load on start (optional).
+- -i, --default-participant-index : default participant index to use when no explicit participant id is provided (default 1).
+- -h, --host : host/interface for the server (default 127.0.0.1).
+- -p, --port : port for the server (default 5000).
+
+Behavior and features
+- Can be started without a config file; load a config later from the built-in file browser (filters to directories and .toml files).
+- When a config is loaded the package starts the server in the same event loop, exposing the same REST API described elsewhere in this README.
+- Participant management:
+  - View all participants and their status, block id and block name.
+  - Create new participants (auto id or a specific id).
+  - Move the default or a specific participant to the next block or to a specific block id.
+  - Move all active participants to a block.
+  - Reset a participant.
+  - Choose a monitored participant to view its current config and status.
+- Config management:
+  - View the currently loaded .toml contents in a code editor pane.
+  - Edit the config in place and save; saving writes the file and the app will attempt to reload the config.
+  - Generate new config files using simple or advanced helpers (write a minimal example or build from JSON-specified order/blocks/parameters).
+  - Generate expanded JSON configs for a range of participant indices (write output to a directory).
+- Live logging pane shows application logs for actions and errors.
+- A simple edit UI is available to tweak the in-memory per-participant config (submit or cancel edits).
+
+Notes
+- Editing and saving the config file from the TUI writes to the same config path the server is using; the TUI will attempt to reload the new configuration but will preserve participant state (see server behavior note in the [Loading experiment through server](#loading-experiment-through-server) section).
+- The TUI requires the textual/Rich environment provided by the package (normally installed with the package). Use `Ctrl+q` to exit or the TUI's quit action.
+
+This TUI is intended as a compact, interactive alternative to the web interface for quick testing, config edits, and participant control.
+<p style="display:flex; gap:8px; align-items:flex-start;">
+  <img src="https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot_tui1.png" alt="web UI screenshot 1" style="width:49%;">
+  <img src="https://raw.githubusercontent.com/ahmed-shariff/experiment_server/master/media/screenshot_tui2.png" alt="web UI screenshot 2" style="width:49%;">
+</p>
+
 ## Configuration of an experiment
 The configuration is defined in a [toml](https://toml.io/en/) file. 
 
@@ -272,6 +322,8 @@ See [toml spec](https://toml.io/en/v1.0.0) for more information on the format of
 ```
 </details>
 
+See [construct_participant_condition][experiment_server._participant_ordering.construct_participant_condition] and [process_config_file][experiment_server._process_config.process_config_file] for more information.
+
 ## Verify config
 A config file can be validated by running:
 ```sh
@@ -279,6 +331,8 @@ $ experiment-server verify-config-file sample_config.toml
 ```
 This will show how the expanded config looks like for the first 5 participants.
 
+See also [verify_config][experiment_server._process_config.verify_config]
+
 ## Loading experiment through server
 After installation, the server can used as:
 
@@ -320,7 +374,7 @@ The server exposes the following REST API:
 
 - [PUT] `/api/add-participant/:participant-id` - Add a new participant with `participant-id`. If there is already a participant with the `participant-id`, this will fail. 
 
-For a Python application, `experiment_server.Client` can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
+For a Python application, [`experiment_server.Client`][experiment_server.Client] can be used to access configs from the server. Also, the server can be launched programmatically using `experiment_server.server_process` which returns a [`Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process) object.
 
 **NOTE**: If the config file served is changed, the new config will be loaded, but the state of the participants will be maintained. i.e., the added participants and the block id they are at will not change. To move the block ids for all active participants, you would have to call the `move-all-to-block` endpoint.
 
@@ -330,7 +384,7 @@ The server also provides a simple web interface, which can be accessed at `/` or
 
 
 ## Loading experiment through API
-A configuration can be loaded and managed by importing `experiment_server.Experiment`.
+A configuration can be loaded and managed by importing [`experiment_server.Experiment`][experiment_server.Experiment].
 
 ## Generate expanded configs
 A config file (i.e. `.toml` file), can be expanded to JSON with the following command
@@ -341,6 +395,8 @@ $ experiment-server generate-config-json sample_config.toml --participant-range
 
 The above will generate the expanded configs for participant indices 1 to 5 as JSON output on stdout. This result can be written out to individual JSON files by setting the `--out-dir`/`-d` to a directory. See more options with `--help`
 
+See also [_generate_config_json][experiment_server._api._generate_config_json]
+
 ## Function calls in config
 A function call in the config is represented by a table, with the following keys 
 - `function_name`: This should be one of the names in the supported functions list below.
@@ -362,7 +418,3 @@ param = { foo = "test", bar = { function_name = "choices", args = { population =
 ```
 
 For more on the `experiemnt-server` and how it can be used see the [wiki](https://github.com/ahmed-shariff/experiment_server/wiki)
-
-# Wishlist (todo list?)
-- Improved docs
-  - Add the option of using dict values in order

{experiment_server-0.3.6 → experiment_server-0.3.7}/experiment_server/_api.py

@@ -1,5 +1,5 @@
 from sys import stdout
-from typing import Any, Dict, Iterable, List, Union
+from typing import Any, Callable, Dict, Iterable, List, Union
 
 from loguru import logger
 from experiment_server._process_config import process_config_file
@@ -89,25 +89,85 @@ class Experiment:
             config_file (str): Path to the TOML configuration file.
             default_participant_index (int): Default 1-based index used when none is provided.
         """
-        assert default_participant_index > 0, "Default participant index should be >0"
+        self.on_file_change_callback:list[Callable] = []
+        self.on_config_change_callback:list[Callable] = []
+
+        self.watchdog = None
         self.global_state: Dict[int, ParticipantState] = {}
+        self.config_file = Path(config_file)
         self.default_participant_index = default_participant_index
-        self.watchdog = FileModifiedWatcher(config_file, self._config_file_modified_callback)
-        self.config_file = config_file
 
-        if default_participant_index not in self.global_state:
-            self.global_state[default_participant_index] = ParticipantState(
-                process_config_file(config_file, default_participant_index),
-                default_participant_index,
+    @property
+    def config_file(self) -> Path:
+        return self._config_file
+
+    @config_file.setter
+    def config_file(self, value):
+        """Load a new config file. All participants states will be reset."""
+        try:
+            for ppid in self.global_state.keys():
+                self.global_state[ppid] = ParticipantState(
+                    process_config_file(value, ppid), ppid, False)
+
+            if self.watchdog is not None:
+                self.watchdog.end_watch()
+            self.watchdog = FileModifiedWatcher(value, self._config_file_modified_callback)
+
+            self._config_file = value
+
+            for _callback in self.on_config_change_callback:
+                try:
+                    _callback(True)
+                except Exception as _e:
+                    logger.exception(f"Failed to call callback {_callback}: {_e}")
+        except Exception as e:
+            if self.watchdog is not None:
+                self.watchdog.end_watch()
+            self.watchdog = FileModifiedWatcher(self._config_file, self._config_file_modified_callback)
+
+            for _callback in self.on_config_change_callback:
+                try:
+                    _callback(False)
+                except Exception as _e:
+                    logger.exception(f"Failed to call callback {_callback}: {_e}")
+            logger.exception(f"Failed to set new config {e}")
+            raise
+
+    @property
+    def default_participant_index(self) -> int:
+        return self._default_participant_index
+
+    @default_participant_index.setter
+    def default_participant_index(self, value):
+        assert value > 0, "Default participant index should be >0"
+        self._default_participant_index = value
+
+        if self._default_participant_index not in self.global_state:
+            self.global_state[self._default_participant_index] = ParticipantState(
+                process_config_file(self._config_file, self._default_participant_index),
+                self._default_participant_index,
                 False,
             )
 
     def _config_file_modified_callback(self):
         """Reload configurations for all known participants when the file changes."""
         logger.info("Reloading config")
-        for participantState in self.global_state.values():
-            config = process_config_file(self.config_file, participantState.participant_index)
-            participantState.config = config
+        try:
+            for participantState in self.global_state.values():
+                config = process_config_file(self._config_file, participantState.participant_index)
+                participantState.config = config
+            for _callback in self.on_file_change_callback:
+                try:
+                    _callback(True)
+                except Exception as _e:
+                    logger.exception(f"Failed to call callback {_callback}: {_e}")
+        except Exception as e:
+            for _callback in self.on_file_change_callback:
+                try:
+                    _callback(False)
+                except Exception as _e:
+                    logger.exception(f"Failed to call callback {_callback}: {_e}")
+            logger.exception(f"Failed to load config {e}")
 
     def get_next_participant(self) -> int:
         """Allocate and return the next participant index (max existing + 1)."""
@@ -124,7 +184,7 @@ class Experiment:
         if participant_index in self.global_state:
             return False
         self.global_state[participant_index] = ParticipantState(
-            process_config_file(self.config_file, participant_index),
+            process_config_file(self._config_file, participant_index),
             participant_index,
             False,
         )
@@ -169,7 +229,7 @@ class Experiment:
         """Reload the participant's configuration from file and replace their stored config."""
         if participant_index is None:
             participant_index = self.default_participant_index
-        self.global_state[participant_index].config = process_config_file(self.config_file, participant_index)
+        self.global_state[participant_index].config = process_config_file(self._config_file, participant_index)
         return True
 
     def get_blocks_count(self, participant_index:int|None=None) -> int:

{experiment_server-0.3.6 → experiment_server-0.3.7}/experiment_server/_client.py

@@ -14,16 +14,14 @@ class Client:
     - Methods operate on a per-participant basis when applicable (provide
       participant_index or omit to use the server's default participant).
 
-    Parameters
-    - server_host (str): Hostname or IP of the server (default "127.0.0.1").
-    - server_port (str|int): Port of the server (default "5000").
-
     Return value for API methods
+
     - All public API methods return a tuple (success: bool, data: dict|str).
       On success data is the parsed JSON response (or "" if empty). On failure
       success is False and data contains an error message.
 
     Main methods
+
     - move_to_next(participant_index=None)
     - get_config(participant_index=None)
     - server_is_active(participant_index=None)
@@ -33,6 +31,11 @@ class Client:
     - new_participant()
     - add_participant(participant_index)
     - shutdown()
+
+    Parameters:
+        server_host (str): Hostname or IP of the server (default "127.0.0.1").
+        server_port (str|int): Port of the server (default "5000").
+
     """
     def __init__(self, server_host:str ="127.0.0.1", server_port:Union[str, int]="5000") -> None:
         self._server_url = f"http://{server_host}:{server_port}"

{experiment_server-0.3.6 → experiment_server-0.3.7}/experiment_server/_participant_ordering.py

@@ -29,91 +29,95 @@ def construct_participant_condition(config: List[Dict],
       - within_groups (ordering of elements inside each group)
       - init_blocks and final_blocks (ordering of initial and final blocks appended before/after main groups)
 
-    Parameters
-    - config (List[Dict]):
-        A list of block configuration dictionaries. Each dict must contain a unique "name" key whose
-        value will be coerced to a string. The returned value is a list of these configuration dicts
-        arranged according to the computed participant order.
-
-    - participant_index (int):
-        1-based index of the participant used to select deterministic rotations when latin-square or
-        per-participant dictionary-based indexing is used. Must be positive.
-
-    - order (Union[dict, list]):
-        Specification of the main experimental order. Two forms are supported:
-          * list of groups: e.g. [["A","B"], ["C","D","E"]] where each inner list is a group of block names.
-            If a flat list of strings is provided (["A","B","C"]) it will be treated as a single group.
-          * dict keyed by participant index (string or int keys) mapping to a group-list for that participant.
-            When a dict is provided, the `groups_strategy` must be "as_is" (per-participant assignment by key).
-        All block names in the resolved order must be strings and must exist in `config`.
-
-    - init_block_names (Union[dict, list]):
-        Names of blocks to prepend for the participant. Accepts a list of block names (strings) or a
-        dictionary keyed by participant indices (1-based) to select a list for the participant. When a
-        dict is supplied, the strategy for init blocks must be "as_is" (per-participant selection).
-
-    - final_block_names (Union[dict, list]):
-        Names of blocks to append for the participant. Accepts same forms and constraints as init_block_names.
-
-    - within_groups_strategy (Union[str, None]):
-        Strategy applied to the ordering of elements inside each group. Allowed values:
-          * "as_is"      - leave element order as provided
-          * "randomize"  - shuffle elements inside each group (non-deterministic)
-          * "latin_square" - apply a balanced Latin square to permute positions across participants
-        If None, defaults to "as_is". If `order` was provided as a list-of-lists and `groups_strategy`
-        was set to "randomize" or "latin_square" and not explicitly set for `within_groups_strategy`,
-        the `groups_strategy` may be reused for within-groups behavior in some calling patterns.
-
-    - groups_strategy (Union[str, None]):
-        Strategy applied to the sequence of groups. Allowed values:
-          * "as_is"
-          * "randomize"
-          * "latin_square"
-        If None, defaults to "as_is". When `order` is a dict keyed by participant index, `groups_strategy`
-        must be "as_is" because the dict already selects per-participant grouping.
-
-    - init_blocks_strategy (Union[str, None]):
-        Strategy for ordering initial blocks. Allowed values:
-          * "as_is"
-          * "randomize"
-        If None, defaults to "as_is". When init_block_names is a dict keyed by participant index,
-        the strategy must be "as_is" (per-participant selection).
-
-    - final_blocks_strategy (Union[str, None]):
-        Strategy for ordering final blocks. Same semantics and allowed values as init_blocks_strategy.
-
-    Returns
-    - List:
-        A list of block configuration dictionaries (the original dicts from `config`) in the final
-        order constructed for the participant: [init_blocks..., main_blocks..., final_blocks...].
-        The main_blocks portion is produced by flattening the possibly nested group structure after
-        applying the requested group- and within-group strategies.
-
-    Behavior details and constraints
-    - Names in `order`, `init_block_names`, and `final_block_names` are validated to be strings and must
-      match unique names in `config`. Duplicate names in `config` cause an error.
-    - When `groups_strategy` or `within_groups_strategy` is "randomize", Python's random.shuffle is used
-      (non-deterministic unless the caller seeds the RNG).
-    - When "latin_square" is requested for groups or within-group ordering, a balanced Latin square
-      generator is used and `participant_index` selects the row; latin-square requires equal-sized
-      values where appropriate (e.g., all groups must have the same size when using within-group
-      latin-square).
-    - When dictionary mappings are provided for order/init/final blocks, keys are expected to be
-      1-based consecutive integer indices (or strings coercible to those integers). For dicts, the
-      corresponding strategy argument must be "as_is".
-
-    Exceptions
-    - Raises ExperimentServerConfigurationExcetion on invalid configuration, such as:
-        * duplicate block names in config
-        * non-string block names in orders
-        * unsupported strategy names
-        * inconsistent group sizes for latin-square within-group ordering
-        * improper dict key sets or types when dict-based per-participant selection is used
-
-    Notes
-    - The function does not modify the input `config` objects beyond coercing the "name" field to str.
-    - Deterministic rotation behavior for latin-square and dict-based selection is 1-based and uses
-      (participant_index - 1) modulo the appropriate period.
+    Behavior details and constraints:
+        - Names in `order`, `init_block_names`, and `final_block_names` are validated to be strings and must
+          match unique names in `config`. Duplicate names in `config` cause an error.
+        - When `groups_strategy` or `within_groups_strategy` is "randomize", Python's random.shuffle is used
+          (non-deterministic unless the caller seeds the RNG).
+        - When "latin_square" is requested for groups or within-group ordering, a balanced Latin square
+          generator is used and `participant_index` selects the row; latin-square requires equal-sized
+          values where appropriate (e.g., all groups must have the same size when using within-group
+          latin-square).
+        - When dictionary mappings are provided for order/init/final blocks, keys are expected to be
+          1-based consecutive integer indices (or strings coercible to those integers). For dicts, the
+          corresponding strategy argument must be "as_is".
+
+    Notes:
+          The function does not modify the input `config` objects beyond coercing the "name" field to str.
+              Deterministic rotation behavior for latin-square and dict-based selection is 1-based and uses
+              (participant_index - 1) modulo the appropriate period.
+
+    Args:
+        config (List[Dict]): A list of block configuration dictionaries. Each dict must contain a
+        unique "name" key whose value will be coerced to a string. The returned value is a list of
+        these configuration dicts arranged according to the computed participant order.
+
+        participant_index (int): 1-based index of the participant used to select deterministic
+        rotations when latin-square or per-participant dictionary-based indexing is used. Must be
+        positive.
+
+        order (Union[dict, list]):
+            Specification of the main experimental order. Two forms are supported:
+
+            * list of groups: e.g. [["A","B"], ["C","D","E"]] where each inner list is a group of block names.
+              If a flat list of strings is provided (["A","B","C"]) it will be treated as a single group.
+            * dict keyed by participant index (string or int keys) mapping to a group-list for that participant.
+              When a dict is provided, the `groups_strategy` must be "as_is" (per-participant assignment by key).
+
+            All block names in the resolved order must be strings and must exist in `config`.
+
+        init_block_names (Union[dict, list]): Names of blocks to prepend for the
+            participant. Accepts a list of block names (strings) or a dictionary keyed by participant
+            indices (1-based) to select a list for the participant. When a dict is supplied, the
+            strategy for init blocks must be "as_is" (per-participant selection).
+
+        final_block_names (Union[dict, list]): Names of blocks to append for the
+            participant. Accepts same forms and constraints as init_block_names.
+
+        within_groups_strategy (Union[str, None]):
+            Strategy applied to the ordering of elements inside each group. Allowed values:
+
+              * "as_is"      - leave element order as provided
+              * "randomize"  - shuffle elements inside each group (non-deterministic)
+              * "latin_square" - apply a balanced Latin square to permute positions across participants
+
+            If None, defaults to "as_is". If `order` was provided as a list-of-lists and `groups_strategy`
+            was set to "randomize" or "latin_square" and not explicitly set for `within_groups_strategy`,
+            the `groups_strategy` may be reused for within-groups behavior in some calling patterns.
+
+        groups_strategy (Union[str, None]): Strategy applied to the sequence of groups. Allowed values:
+
+              * "as_is"
+              * "randomize"
+              * "latin_square"
+
+            If None, defaults to "as_is". When `order` is a dict keyed by participant index, `groups_strategy`
+            must be "as_is" because the dict already selects per-participant grouping.
+
+        init_blocks_strategy (Union[str, None]): Strategy for ordering initial blocks. Allowed values:
+
+              * "as_is"
+              * "randomize"
+
+            If None, defaults to "as_is". When init_block_names is a dict keyed by participant index,
+            the strategy must be "as_is" (per-participant selection).
+
+        final_blocks_strategy (Union[str, None]): Strategy for ordering final blocks. Same semantics and allowed values as init_blocks_strategy.
+
+    Returns:
+        List: A list of block configuration dictionaries (the original dicts from `config`) in the final
+            order constructed for the participant: [init_blocks..., main_blocks..., final_blocks...].
+            The main_blocks portion is produced by flattening the possibly nested group structure after
+            applying the requested group- and within-group strategies.
+
+    Exceptions:
+        ExperimentServerConfigurationExcetion: on invalid configuration, such as:
+
+            * duplicate block names in config
+            * non-string block names in orders
+            * unsupported strategy names
+            * inconsistent group sizes for latin-square within-group ordering
+            * improper dict key sets or types when dict-based per-participant selection is used
     """
     if within_groups_strategy is None:
         within_groups_strategy = ORDERING_STRATEGY.as_is