ocean-runner 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

ocean_runner/runner.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import InitVar, asdict, dataclass, field
 from logging import Logger
 from pathlib import Path
-from typing import Callable, Generic, Self, TypeVar
+from typing import Callable, Generic, TypeVar
 
 from oceanprotocol_job_details import JobDetails
 
@@ -42,14 +42,15 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
     _job_details: JobDetails[JobDetailsT] = field(init=False)
     _result: ResultT | None = field(default=None, init=False)
 
-    error_callback: Callable[[Algorithm, Exception], None] = default_error_callback
-
     # Decorator-registered callbacks
     _validate_fn: Callable[[Algorithm], None] | None = field(default=None, init=False)
     _run_fn: Callable[[Algorithm], ResultT] | None = field(default=None, init=False)
     _save_fn: Callable[[ResultT, Path, Algorithm], None] | None = field(
         default=None, init=False
     )
+    _error_callback: Callable[[Algorithm, Exception], None] = field(
+        default=default_error_callback, init=False
+    )
 
     def __post_init__(self, config: Config | None) -> None:
         config: Config = config or Config()
@@ -110,20 +111,20 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
     # Decorators (FastAPI-style)
     # ---------------------------
 
-    def validate(self, fn: Callable[[Self], None]) -> Callable[[Self], None]:
+    def validate(self, fn: Callable[[], None]) -> Callable[[], None]:
         self._validate_fn = fn
         return fn
 
-    def run(self, fn: Callable[[Self], ResultT]) -> Callable[[Self], ResultT]:
+    def run(self, fn: Callable[[], ResultT]) -> Callable[[], ResultT]:
         self._run_fn = fn
         return fn
 
-    def save_results(self, fn: Callable[[ResultT, Path, Algorithm], None]) -> Callable:
+    def save_results(self, fn: Callable[[ResultT, Path], None]) -> Callable:
         self._save_fn = fn
         return fn
 
-    def on_error(self, fn: Callable[[Algorithm, Exception], None]) -> Callable:
-        self.error_callback = fn
+    def on_error(self, fn: Callable[[Exception], None]) -> Callable:
+        self._error_callback = fn
         return fn
 
     # ---------------------------
@@ -136,7 +137,7 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
             # Validation step
             if self._validate_fn:
                 self.logger.info("Running custom validation...")
-                self._validate_fn(self)
+                self._validate_fn()
             else:
                 self.logger.info("Running default validation...")
                 default_validation(self)
@@ -144,7 +145,7 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
             # Run step
             if self._run_fn:
                 self.logger.info("Running algorithm...")
-                self._result = self._run_fn(self)
+                self._result = self._run_fn()
             else:
                 self.logger.warning("No run() function defined. Skipping execution.")
                 self._result = None
@@ -155,7 +156,6 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
                 self._save_fn(
                     self._result,
                     self.job_details.paths.outputs,
-                    self,
                 )
             else:
                 self.logger.info("No save_results() defined. Using default.")
@@ -167,6 +167,6 @@ class Algorithm(Generic[JobDetailsT, ResultT]):
 
         except Exception as e:
             self.logger.exception("Error during algorithm execution")
-            self.error_callback(self, e)
+            self._error_callback(e)
 
         return self._result

{ocean_runner-0.2.14.dist-info → ocean_runner-0.2.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ocean-runner
-Version: 0.2.14
+Version: 0.2.16
 Summary: A fluent API for OceanProtocol algorithms
 Project-URL: Homepage, https://github.com/AgrospAI/ocean-runner
 Project-URL: Issues, https://github.com/AgrospAI/ocean-runner/issues
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
 
 # ocean-runner
 
-Ocean Runner is a package that brings a fluent API for APP creation and running in the scope of OceanProtocol.
+Ocean Runner is a package that eases algorithm creation in the scope of OceanProtocol.
 
 
 ## Installation
@@ -40,33 +40,40 @@ uv add ocean-runner
 
 ```python
 import random
-from ocean_runner import Algorithm, Config
+from ocean_runner import Algorithm
+
+algorithm = Algorithm()
+
 
+@algorithm.run
+def run():
+    return random.randint()
 
-Algorithm().run(lambda _: random.randint()).save_results()    
+
+if __name__ == "__main__":
+    algorithm()
 ```
 
-To use minimally the API, you can just provide a callback to the run method, defaulting for the rest of behaviours. This code snippet will:
+This code snippet will:
 
-- Read the OceanProtocol JobDetails from the environment variables and use default file paths.
-- Generate a random integer.
-- Store the result in a "result.txt" file within the default outputs path.
+- Read the OceanProtocol JobDetails from the environment variables and use default configuration file paths.
+- Execute the run function.
+- Execute the default saving function, storing the result in a "result.txt" file within the default outputs path.
 
 ### Tuning
 
 #### Application Config
 
-The application configuration can be tweaked by passing a Config instance to its' constructor.
+The application configuration can be tweaked by passing a Config instance to its constructor.
 
 ```python
-Algorithm(
+from ocean_runner import Algorithm, Config
+
+algorithm = Algorithm(
     Config(
         custom_input: ... # dataclass
         # Custom algorithm parameters dataclass.
         
-        error_callback: ... # Callable[[Exception], None]
-        # Callback to run on exceptions.
-        
         logger: ... # type: logging.Logger
         # Custom logger to use.
 
@@ -82,6 +89,8 @@ Algorithm(
 ```python
 import logging
 
+from ocean_runner import Algorithm, Config
+
 
 @dataclass
 class CustomInput:
@@ -91,19 +100,13 @@ class CustomInput:
 logger = logging.getLogger(__name__)
 
 
-Algorithm(
+algorithm = Algorithm(
     Config(
         custom_input: CustomInput,
         """
         Load the Algorithm's Custom Input into a CustomInput dataclass instance.
         """
 
-        error_callback: lambda ex: logger.exception(ex),
-        """
-        Run this callback when an exception is caught
-        NOTE: it's not recommended to catch exceptions this way. Should re-raise and halt the execution.
-        """
-
         source_paths: [Path("/algorithm/src")],
         """
         Source paths to include in the PATH. '/algorithm/src' is the default since our templates place the algorithm source files there.
@@ -143,44 +146,72 @@ Algorithm(
 
 ```
 
-## Default behaviours
+#### Behaviour Config
 
-### Default implementations
-
-As seen in the minimal example, all methods implemented in `Algorithm` have a default implementation which will be commented here.
+To fully configure the behaviour of the algorithm as in the [Minimal Example](#minimal-example), you can do it decorating your defined function as in the following example, which features all the possible algorithm customization.
 
 ```python
+from pathlib import Path
 
-(
-    Algorithm()
-    
-        """
-        Default constructor, will use default values of Config.
-        """
-    
-    .validate()
-    
-        """
-        Will validate the algorithm's job detail instance, checking for the existence of:
-        - `job_details.ddos` 
-        - `job_details.files`
-        """
+import pandas as pd
+from ocean_runner import Algorithm
 
-    .run()
+algorithm = Algorithm()
 
-        """ 
-        Has NO default implementation, must pass a callback that returns a result of any type.
-        """
 
-    .save_results()
+@algorithm.on_error
+def error_callback(ex: Exception):
+    algorithm.logger.exception(ex)
+    raise algorithm.Error() from ex
 
-        """
-        Stores the result of running the algorithm in "outputs/results.txt"
-        """
 
-)
+@algorithm.validate
+def val():
+    assert algorithm.job_details.files, "Empty input dir"
+
+
+@algorithm.run
+def run() -> pd.DataFrame:
+    _, filename = next(algorithm.job_details.next_path())
+    return pd.read_csv(filename).describe(include="all")
+
+
+@algorithm.save_results
+def save(results: pd.DataFrame, path: Path):
+    algorithm.logger.info(f"Descriptive statistics: {results}")
+    results.to_csv(path / "results.csv")
+
+
+if __name__ == "__main__":
+    algorithm()
+```
+
+
+
+### Default implementations
+
+As seen in the minimal example, all methods implemented in `Algorithm` have a default implementation which will be commented here.
+
+```python
+.validate()
+
+    """
+    Will validate the algorithm's job detail instance, checking for the existence of:
+    - `job_details.ddos`
+    - `job_details.files`
+    """
+
+.run()
+
+    """ 
+    Has NO default implementation, must pass a callback that returns a result of any type.
+    """
 
+.save_results()
 
+    """
+    Stores the result of running the algorithm in "outputs/results.txt"
+    """
 ```
 
 ### Job Details
@@ -188,7 +219,7 @@ As seen in the minimal example, all methods implemented in `Algorithm` have a de
 To load the OceanProtocol JobDetails instance, the program will read some environment variables, they can be mocked passing an instance of `Environment` through the configuration of the algorithm.
 
 Environment variables:
-- `DIDS` Input dataset(s) DID's, must have format: `["abc..90"]`
-- `TRANSFORMATION_DID` Algorithm DID, must have format: `abc..90`
-- `SECRET` Algorithm secret.
+- `DIDS` (optional) Input dataset(s) DID's, must have format: `["abc..90"]`. Defaults to reading them automatically from the `DDO` data directory.
+- `TRANSFORMATION_DID` (optional, default="DEFAULT"): Algorithm DID, must have format: `abc..90`.
+- `SECRET` (optional, default="DEFAULT"): Algorithm secret. 
 - `BASE_DIR` (optional, default="/data"): Base path to the OceanProtocol data directories.

ocean_runner-0.2.16.dist-info/RECORD

@@ -0,0 +1,7 @@
+ocean_runner/__init__.py,sha256=awAmE6kZhuwcrD3gT7qFZArdhiuzW-EFTA6tGKhw06k,138
+ocean_runner/config.py,sha256=gyyUotPJ7n8wPPdsJZIBUT4zBlkoNbhV876JDTdPNsY,1398
+ocean_runner/runner.py,sha256=mPxnJCP-XYl0akRAI4HdAku0KlsTCrXTVPCwlQj5JoY,5721
+ocean_runner-0.2.16.dist-info/METADATA,sha256=s4MrShZfoQzbWIXZRV06Rt0S4lhqYuRjK_OG9QKJoKg,6562
+ocean_runner-0.2.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ocean_runner-0.2.16.dist-info/licenses/LICENSE,sha256=_B25KqK4amoADWkMN150tnZFm_Fy7VvZpvIC8ZydWdI,1053
+ocean_runner-0.2.16.dist-info/RECORD,,

ocean_runner-0.2.14.dist-info/RECORD

@@ -1,7 +0,0 @@
-ocean_runner/__init__.py,sha256=awAmE6kZhuwcrD3gT7qFZArdhiuzW-EFTA6tGKhw06k,138
-ocean_runner/config.py,sha256=gyyUotPJ7n8wPPdsJZIBUT4zBlkoNbhV876JDTdPNsY,1398
-ocean_runner/runner.py,sha256=AM4GlgpGGOSLa_TfO8rAdWmTGTPTZoTT84LNtUswTXw,5762
-ocean_runner-0.2.14.dist-info/METADATA,sha256=bIdyxazZ4mWCOUW7JULJaykDgDCd03yZ91CWG4BbsT8,5919
-ocean_runner-0.2.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ocean_runner-0.2.14.dist-info/licenses/LICENSE,sha256=_B25KqK4amoADWkMN150tnZFm_Fy7VvZpvIC8ZydWdI,1053
-ocean_runner-0.2.14.dist-info/RECORD,,