feat: Introduce NePS-Spaces

docs/getting_started.md

@@ -13,18 +13,17 @@ pip install neural-pipeline-search
 
 ## The 3 Main Components
 
-1. **Establish a [`pipeline_space`](reference/pipeline_space.md)**:
+1. **Establish a [`pipeline_space=`](reference/neps_spaces.md)**:
 
 ```python
-pipeline_space={
-    "some_parameter": (0.0, 1.0),   # float
-    "another_parameter": (0, 10),   # integer
-    "optimizer": ["sgd", "adam"],   # categorical
-    "epoch": neps.Integer(lower=1, upper=100, is_fidelity=True),
-    "learning_rate": neps.Float(lower=1e-5, upper=1, log=True),
-    "alpha": neps.Float(lower=0.1, upper=1.0, prior=0.99, prior_confidence="high")
-}
-
+class ExampleSpace(neps.PipelineSpace):
+    # Define the parameters of your search space
+    some_parameter = neps.Float(min_value=0.0, max_value=1.0)       # float
+    another_parameter = neps.Integer(min_value=0, max_value=10)     # integer
+    optimizer = neps.Categorical(choices=("sgd", "adam"))           # categorical
+    epoch = neps.Fidelity(neps.Integer(min_value=1, max_value=100))
+    learning_rate = neps.Float(min_value=1e-5, max_value=1, log=True)
+    alpha = neps.Float(min_value=0.1, max_value=1.0, prior=0.99, prior_confidence="high")
 ```
 
 2. **Define an `evaluate_pipeline()` function**:
@@ -42,7 +41,7 @@ def evaluate_pipeline(some_parameter: float,
 3. **Execute with [`neps.run()`](reference/neps_run.md)**:
 
 ```python
-neps.run(evaluate_pipeline, pipeline_space)
+neps.run(evaluate_pipeline, ExampleSpace())
 ```
 
 ---
@@ -52,7 +51,7 @@ neps.run(evaluate_pipeline, pipeline_space)
 The [reference](reference/neps_run.md) section provides detailed information on the individual components of NePS.
 
 1. How to use the [**`neps.run()`** function](reference/neps_run.md) to start the optimization process.
-2. The different [search space](reference/pipeline_space.md) options available.
+2. The different [search space](reference/neps_spaces.md) options available.
 3. How to choose and configure the [optimizer](reference/optimizers.md) used.
 4. How to define the [`evaluate_pipeline()` function](reference/evaluate_pipeline.md).
 5. How to [analyze](reference/analyse.md) the optimization runs.

docs/index.md

@@ -59,33 +59,26 @@ import logging
 
 
 # 1. Define a function that accepts hyperparameters and computes the validation error
-def evaluate_pipeline(
-        hyperparameter_a: float, hyperparameter_b: int, architecture_parameter: str
-) -> dict:
+def evaluate_pipeline(hyperparameter_a: float, hyperparameter_b: int, architecture_parameter: str):
     # Create your model
     model = MyModel(architecture_parameter)
 
     # Train and evaluate the model with your training pipeline
-    validation_error = train_and_eval(
-        model, hyperparameter_a, hyperparameter_b
-    )
+    validation_error = train_and_eval(model, hyperparameter_a, hyperparameter_b)
     return validation_error
 
 
 # 2. Define a search space of parameters; use the same parameter names as in evaluate_pipeline
-pipeline_space = dict(
-    hyperparameter_a=neps.Float(
-        lower=0.001, upper=0.1, log=True  # The search space is sampled in log space
-    ),
-    hyperparameter_b=neps.Integer(lower=1, upper=42),
-    architecture_parameter=neps.Categorical(["option_a", "option_b"]),
-)
+class ExampleSpace(neps.PipelineSpace):
+    hyperparameter_a = neps.Float(min_value=0.001, max_value=0.1, log=True)  # Log scale parameter
+    hyperparameter_b = neps.Integer(min_value=1, max_value=42)
+    architecture_parameter = neps.Categorical(choices=("option_a", "option_b"))
 
 # 3. Run the NePS optimization
 logging.basicConfig(level=logging.INFO)
 neps.run(
     evaluate_pipeline=evaluate_pipeline,
-    pipeline_space=pipeline_space,
+    pipeline_space=ExampleSpace(),
     root_directory="path/to/save/results",  # Replace with the actual path.
     evaluations_to_spend=100,
 )

docs/reference/evaluate_pipeline.md

@@ -1,38 +1,38 @@
-# The `evaluate_pipeline` function
+# The `evaluate_pipeline` function
 
 > **TL;DR**
 > *Sync*: return a scalar or a dict ⟶ NePS records it automatically.
 > *Async*: return `None`, launch a job, and call `neps.save_pipeline_results()` when the job finishes.
 
 ---
 
-## 1  Return types
+## 1 Return types
 
 | Allowed return | When to use                                 | Minimal example                              |
 | -------------- | ------------------------------------------- | -------------------------------------------- |
 | **Scalar**     | simple objective, single fidelity           | `return loss`                                |
 | **Dict**       | need cost/extra metrics                     | `{"objective_to_minimize": loss, "cost": 3}` |
-| **`None`**     | you launch the job elsewhere (SLURM, k8s …) | *see § 3 Async*                              |
+| **`None`**     | you launch the job elsewhere (SLURM, k8s …) | *see § 3 Async*                              |
 
 All other values raise a `TypeError` inside NePS.
 
-## 2  Result dictionary keys
+## 2 Result dictionary keys
 
 | key                     | purpose                                                                      | required?                     |
 | ----------------------- | ---------------------------------------------------------------------------- | ----------------------------- |
 | `objective_to_minimize` | scalar NePS will minimise                                                    | **yes**                       |
-| `cost`                  | wall‑clock, GPU‑hours, … — only if you passed `cost_to_spend` to `neps.run` | yes *iff* cost budget enabled |
+| `cost`                  | wall‑clock, GPU‑hours, … — only if you passed `cost_to_spend` to `neps.run` | yes *iff* cost budget enabled |
 | `learning_curve`        | list/np.array of intermediate objectives                                     | optional                      |
 | `extra`                 | any JSON‑serialisable blob                                                   | optional                      |
 | `exception`                 | any Exception illustrating the error in evaluation                                                   | optional                      |
 
-> **Tip**  Return exactly what you need; extra keys are preserved in the trial’s `report.yaml`.
+> **Tip**  Return exactly what you need; extra keys are preserved in the trial’s `report.yaml`.
 
 ---
 
-## 3  Asynchronous evaluation (advanced)
+## 3 Asynchronous evaluation (advanced)
 
-### 3.1 Design
+### 3.1 Design
 
 1. **The Python side** (your `evaluate_pipeline` function)
 
@@ -52,9 +52,9 @@ All other values raise a `TypeError` inside NePS.
    when it finishes.
    This writes `report.yaml` and marks the trial *SUCCESS* / *CRASHED*.
 
-### 3.2 Code walk‑through
+### 3.2 Code walk‑through
 
-`submit.py` – called by NePS synchronously
+`submit.py` – called by NePS synchronously
 
 ```python
 from pathlib import Path
@@ -68,7 +68,7 @@ def evaluate_pipeline(
     learning_rate: float,
     optimizer: str,
 ):
-    # 1) write a Slurm script
+    # 1) write a Slurm script
     script = f"""#!/bin/bash
 #SBATCH --time=0-00:10
 #SBATCH --job-name=trial_{pipeline_id}
@@ -83,15 +83,15 @@ python run_pipeline.py \
        --root_dir {root_directory}
 """)
 
-    # 2) submit and RETURN None (async)
+    # 2) submit and RETURN None (async)
     script_path = pipeline_directory / "submit.sh"
     script_path.write_text(script)
     os.system(f"sbatch {script_path}")
 
-    return None  # ⟵ signals async mode
+    return None  # ⟵ signals async mode
 ```
 
-`run_pipeline.py` – executed on the compute node
+`run_pipeline.py` – executed on the compute node
 
 ```python
 import argparse, json, time, neps
@@ -128,7 +128,7 @@ neps.save_pipeline_results(
 
 the default value for `post_run_summary` is True, if you want to prevent any summary creation, you should specify in the arguments.
 
-### 3.3 Why this matters
+### 3.3 Why this matters
 
 * No worker idles while your job is in the queue ➜ better throughput.
 * Crashes inside the job still mark the trial *CRASHED* instead of hanging.
@@ -138,7 +138,7 @@ the default value for `post_run_summary` is True, if you want to prevent any sum
 
 * When using async approach, one worker, may create as many trials as possible, of course that in `Slurm` or other workload managers it's impossible to overload the system because of limitations set for each user, but if you want to control resources used for optimization, it's crucial to set `max_evaluations_per_run` when calling `neps.run`.
 
-## 4  Extra injected arguments
+## 4 Extra injected arguments
 
 | name                          | provided when           | description                                                |
 | ----------------------------- | ----------------------- | ---------------------------------------------------------- |
@@ -150,7 +150,7 @@ Use them to handle warm‑starts, logging and result persistence.
 
 ---
 
-## 5  Checklist
+## 5 Checklist
 
 * [x] Return scalar **or** dict **or** `None`.
 * [x] Include `cost` when using cost budgets.

docs/reference/neps_run.md

@@ -17,32 +17,32 @@ import neps
 
 def evaluate_pipeline(learning_rate: float, epochs: int) -> float:
     # Your code here
-
     return loss
 
+class ExamplePipeline(neps.PipelineSpace):
+    learning_rate = neps.Float(1e-3, 1e-1, log=True)
+    epochs = neps.Fidelity(neps.Integer(10, 100))
+
 neps.run(
     evaluate_pipeline=evaluate_pipeline, # (1)!
-    pipeline_space={, # (2)!
-        "learning_rate": neps.Float(1e-3, 1e-1, log=True),
-        "epochs": neps.Integer(10, 100)
-    },
+    pipeline_space=ExamplePipeline(), # (2)!
     root_directory="path/to/result_dir" # (3)!
 )
 ```
 
 1.  The objective function, targeted by NePS for minimization, by evaluation various configurations.
     It requires these configurations as input and should return either a dictionary or a sole loss value as the output.
 2.  This defines the search space for the configurations from which the optimizer samples.
-    It accepts either a dictionary with the configuration names as keys, a path to a YAML configuration file, or a [`configSpace.ConfigurationSpace`](https://automl.github.io/ConfigSpace/) object.
-    For comprehensive information and examples, please refer to the detailed guide available [here](../reference/pipeline_space.md)
+    It accepts a class instance inheriting from `neps.PipelineSpace` or a [`configSpace.ConfigurationSpace`](https://automl.github.io/ConfigSpace/) object.
+    For comprehensive information and examples, please refer to the detailed guide available [here](../reference/neps_spaces.md)
 3.  The directory path where the information about the optimization and its progress gets stored.
     This is also used to synchronize multiple calls to `neps.run()` for parallelization.
 
 
 See the following for more:
 
-* What kind of [pipeline space](../reference/pipeline_space.md) can you define?
-* What goes in and what goes out of [`evaluate_pipeline()`](../reference/evaluate_pipeline.md)?
+* What kind of [pipeline space](../reference/neps_spaces.md) can you define?
+* What goes in and what goes out of [`evaluate_pipeline()`](../reference/neps_run.md)?
 
 ## Budget, how long to run?
 To define a budget, provide `evaluations_to_spend=` to [`neps.run()`][neps.api.run],
@@ -69,7 +69,7 @@ neps.run(
 2.  Prevents the initiation of new evaluations once this cost threshold is surpassed.
     This can be any kind of cost metric you like, such as time, energy, or monetary, as long as you can calculate it.
     This requires adding a cost value to the output of the `evaluate_pipeline` function, for example, return `#!python {'objective_to_minimize': loss, 'cost': cost}`.
-    For more details, please refer [here](../reference/evaluate_pipeline.md)
+    For more details, please refer [here](../reference/neps_spaces.md)
 
 ## Getting some feedback, logging
 NePS will not print anything to the console. To view the progress of workers,
@@ -140,7 +140,7 @@ provided to [`neps.run()`][neps.api.run].
     │   └── config_2
     │       ├── config.yaml
     │       └── metadata.json
-    ├── summary                 
+    ├── summary
     │  ├── full.csv
     │  └── short.csv
     │  ├── best_config_trajectory.txt