ocean-runner 0.2.19__tar.gz → 0.2.25__tar.gz

{ocean_runner-0.2.19 → ocean_runner-0.2.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ocean-runner
-Version: 0.2.19
+Version: 0.2.25
 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
@@ -17,7 +17,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
-Requires-Dist: oceanprotocol-job-details>=0.2.8
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: oceanprotocol-job-details>=0.3.11
 Requires-Dist: pydantic-settings>=2.12.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pytest>=8.4.2
@@ -27,7 +28,6 @@ Description-Content-Type: text/markdown
 
 Ocean Runner is a package that eases algorithm creation in the scope of OceanProtocol.
 
-
 ## Installation
 
 ```bash
@@ -48,7 +48,7 @@ algorithm = Algorithm()
 
 
 @algorithm.run
-def run():
+def run(_: Algorithm):
     return random.randint()
 
 
@@ -75,14 +75,14 @@ algorithm = Algorithm(
     Config(
         custom_input: ... # dataclass
         # Custom algorithm parameters dataclass.
-        
+
         logger: ... # type: logging.Logger
         # Custom logger to use.
 
         source_paths: ... # type: Iterable[Path]
         # Source paths to include in the PATH
-        
-        environment: ... 
+
+        environment: ...
         # type: ocean_runner.Environment. Mock of environment variables.
     )
 )
@@ -91,12 +91,12 @@ algorithm = Algorithm(
 ```python
 import logging
 
+from pydantic import BaseModel
 from ocean_runner import Algorithm, Config
 
 
-@dataclass
-class CustomInput:
-    foobar: string 
+class CustomInput(BaseModel):
+    foobar: string
 
 
 logger = logging.getLogger(__name__)
@@ -106,7 +106,7 @@ algorithm = Algorithm(
     Config(
         custom_input: CustomInput,
         """
-        Load the Algorithm's Custom Input into a CustomInput dataclass instance.
+        Load the Algorithm's Custom Input into a CustomInput instance.
         """
 
         source_paths: [Path("/algorithm/src")],
@@ -162,34 +162,32 @@ algorithm = Algorithm()
 
 
 @algorithm.on_error
-def error_callback(ex: Exception):
+def error_callback(algorithm: Algorithm, ex: Exception):
     algorithm.logger.exception(ex)
     raise algorithm.Error() from ex
 
 
 @algorithm.validate
-def val():
+def val(algorithm: Algorithm):
     assert algorithm.job_details.files, "Empty input dir"
 
 
 @algorithm.run
-def run() -> pd.DataFrame:
-    _, filename = next(algorithm.job_details.next_path())
+def run(algorithm: Algorithm) -> pd.DataFrame:
+    _, filename = next(algorithm.job_details.inputs())
     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")
+def save(algorithm: Algorithm, result: pd.DataFrame, base: Path):
+    algorithm.logger.info(f"Descriptive statistics: {result}")
+    result.to_csv(base / "result.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.
@@ -205,7 +203,7 @@ As seen in the minimal example, all methods implemented in `Algorithm` have a de
 
 .run()
 
-    """ 
+    """
     Has NO default implementation, must pass a callback that returns a result of any type.
     """
 
@@ -221,7 +219,8 @@ 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` (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. 
+- `SECRET` (optional, default="DEFAULT"): Algorithm secret.
 - `BASE_DIR` (optional, default="/data"): Base path to the OceanProtocol data directories.

{ocean_runner-0.2.19 → ocean_runner-0.2.25}/README.md

@@ -2,7 +2,6 @@
 
 Ocean Runner is a package that eases algorithm creation in the scope of OceanProtocol.
 
-
 ## Installation
 
 ```bash
@@ -23,7 +22,7 @@ algorithm = Algorithm()
 
 
 @algorithm.run
-def run():
+def run(_: Algorithm):
     return random.randint()
 
 
@@ -50,14 +49,14 @@ algorithm = Algorithm(
     Config(
         custom_input: ... # dataclass
         # Custom algorithm parameters dataclass.
-        
+
         logger: ... # type: logging.Logger
         # Custom logger to use.
 
         source_paths: ... # type: Iterable[Path]
         # Source paths to include in the PATH
-        
-        environment: ... 
+
+        environment: ...
         # type: ocean_runner.Environment. Mock of environment variables.
     )
 )
@@ -66,12 +65,12 @@ algorithm = Algorithm(
 ```python
 import logging
 
+from pydantic import BaseModel
 from ocean_runner import Algorithm, Config
 
 
-@dataclass
-class CustomInput:
-    foobar: string 
+class CustomInput(BaseModel):
+    foobar: string
 
 
 logger = logging.getLogger(__name__)
@@ -81,7 +80,7 @@ algorithm = Algorithm(
     Config(
         custom_input: CustomInput,
         """
-        Load the Algorithm's Custom Input into a CustomInput dataclass instance.
+        Load the Algorithm's Custom Input into a CustomInput instance.
         """
 
         source_paths: [Path("/algorithm/src")],
@@ -137,34 +136,32 @@ algorithm = Algorithm()
 
 
 @algorithm.on_error
-def error_callback(ex: Exception):
+def error_callback(algorithm: Algorithm, ex: Exception):
     algorithm.logger.exception(ex)
     raise algorithm.Error() from ex
 
 
 @algorithm.validate
-def val():
+def val(algorithm: Algorithm):
     assert algorithm.job_details.files, "Empty input dir"
 
 
 @algorithm.run
-def run() -> pd.DataFrame:
-    _, filename = next(algorithm.job_details.next_path())
+def run(algorithm: Algorithm) -> pd.DataFrame:
+    _, filename = next(algorithm.job_details.inputs())
     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")
+def save(algorithm: Algorithm, result: pd.DataFrame, base: Path):
+    algorithm.logger.info(f"Descriptive statistics: {result}")
+    result.to_csv(base / "result.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.
@@ -180,7 +177,7 @@ As seen in the minimal example, all methods implemented in `Algorithm` have a de
 
 .run()
 
-    """ 
+    """
     Has NO default implementation, must pass a callback that returns a result of any type.
     """
 
@@ -196,7 +193,8 @@ 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` (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. 
+- `SECRET` (optional, default="DEFAULT"): Algorithm secret.
 - `BASE_DIR` (optional, default="/data"): Base path to the OceanProtocol data directories.

{ocean_runner-0.2.19 → ocean_runner-0.2.25}/ocean_runner/config.py

@@ -1,12 +1,12 @@
 from enum import StrEnum, auto
 from logging import Logger
 from pathlib import Path
-from typing import Generic, Sequence, TypeVar
+from typing import Generic, Sequence, Type, TypeVar
 
 from pydantic import BaseModel, ConfigDict, Field
 from pydantic_settings import BaseSettings
 
-InputT = TypeVar("InputT")
+InputT = TypeVar("InputT", BaseModel, None)
 
 DEFAULT = "DEFAULT"
 
@@ -21,13 +21,13 @@ class Keys(StrEnum):
 class Environment(BaseSettings):
     """Environment configuration loaded from environment variables"""
 
-    base_dir: str | Path | None = Field(
+    base_dir: str | Path = Field(
         default_factory=lambda: Path("/data"),
         validation_alias=Keys.BASE_DIR.value,
         description="Base data directory, defaults to '/data'",
     )
 
-    dids: str | list[Path] | None = Field(
+    dids: str | None = Field(
         default=None,
         validation_alias=Keys.DIDS.value,
         description='Datasets DID\'s, format: ["XXXX"]',
@@ -51,7 +51,7 @@ class Config(BaseModel, Generic[InputT]):
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    custom_input: InputT | None = Field(
+    custom_input: Type[InputT] | None = Field(
         default=None,
         description="Algorithm's custom input types, must be a dataclass_json",
     )

{ocean_runner-0.2.19 → ocean_runner-0.2.25}/ocean_runner/runner.py

@@ -1,26 +1,30 @@
 from __future__ import annotations
 
-from dataclasses import InitVar, asdict, dataclass, field
+from dataclasses import InitVar, dataclass, field
 from logging import Logger
 from pathlib import Path
-from typing import Callable, Generic, TypeVar
+from typing import Awaitable, Callable, Dict, Generic, TypeAlias, TypeVar
 
-from oceanprotocol_job_details import JobDetails  # type: ignore
+from oceanprotocol_job_details import JobDetails, load_job_details, run_in_executor
+from pydantic import BaseModel, JsonValue
 
 from ocean_runner.config import Config
 
-InputT = TypeVar("InputT")
+InputT = TypeVar("InputT", BaseModel, None)
 ResultT = TypeVar("ResultT")
+T = TypeVar("T")
 
-ValidateFuncT = Callable[["Algorithm"], None]
-RunFuncT = Callable[["Algorithm"], ResultT] | None
-SaveFuncT = Callable[["Algorithm", ResultT, Path], None]
-ErrorFuncT = Callable[["Algorithm", Exception], None]
 
+Algo: TypeAlias = "Algorithm[InputT, ResultT]"
+ValidateFuncT: TypeAlias = Callable[[Algo], None | Awaitable[None] | None]
+RunFuncT: TypeAlias = Callable[[Algo], ResultT | Awaitable[ResultT]]
+SaveFuncT: TypeAlias = Callable[[Algo, ResultT, Path], Awaitable[None] | None]
+ErrorFuncT: TypeAlias = Callable[[Algo, Exception], Awaitable[None] | None]
 
-def default_error_callback(algorithm: Algorithm, e: Exception) -> None:
+
+def default_error_callback(algorithm: Algorithm, error: Exception) -> None:
     algorithm.logger.exception("Error during algorithm execution")
-    raise e
+    raise error
 
 
 def default_validation(algorithm: Algorithm) -> None:
@@ -29,10 +33,20 @@ def default_validation(algorithm: Algorithm) -> None:
     assert algorithm.job_details.files, "Files missing"
 
 
-def default_save(algorithm: Algorithm, result: ResultT, base: Path) -> None:
+async def default_save(algorithm: Algorithm, result: ResultT, base: Path) -> None:
+    import aiofiles
+
     algorithm.logger.info("Saving results using default save")
-    with open(base / "result.txt", "w+") as f:
-        f.write(str(result))
+    async with aiofiles.open(base / "result.txt", "w+") as f:
+        await f.write(str(result))
+
+
+@dataclass(slots=True)
+class Functions(Generic[InputT, ResultT]):
+    validate: ValidateFuncT = field(default=default_validation, init=False)
+    run: RunFuncT | None = field(default=None, init=False)
+    save: SaveFuncT = field(default=default_save, init=False)
+    error: ErrorFuncT = field(default=default_error_callback, init=False)
 
 
 @dataclass
@@ -44,33 +58,13 @@ class Algorithm(Generic[InputT, ResultT]):
     """
 
     config: InitVar[Config[InputT] | None] = field(default=None)
-    logger: Logger = field(init=False)
-    _job_details: JobDetails[InputT] = field(init=False)
-    _result: ResultT | None = field(default=None, init=False)
-
-    # Decorator-registered callbacks
-    _validate_fn: ValidateFuncT = field(
-        default=default_validation,
-        init=False,
-        repr=False,
-    )
-
-    _run_fn: RunFuncT = field(
-        default=None,
-        init=False,
-        repr=False,
-    )
 
-    _save_fn: SaveFuncT = field(
-        default=default_save,
-        init=False,
-        repr=False,
-    )
+    logger: Logger = field(init=False, repr=False)
 
-    _error_callback: ErrorFuncT = field(
-        default=default_error_callback,
-        init=False,
-        repr=False,
+    _job_details: JobDetails[InputT] = field(init=False)
+    _result: ResultT | None = field(default=None, init=False)
+    _functions: Functions[InputT, ResultT] = field(
+        default_factory=Functions, init=False, repr=False
     )
 
     def __post_init__(self, config: Config[InputT] | None) -> None:
@@ -106,7 +100,7 @@ class Algorithm(Generic[InputT, ResultT]):
                 f"Added [{len(configuration.source_paths)}] entries to PATH"
             )
 
-        self.configuration = configuration
+        self.configuration: Config[InputT] = configuration
 
     class Error(RuntimeError): ...
 
@@ -127,55 +121,62 @@ class Algorithm(Generic[InputT, ResultT]):
     # ---------------------------
 
     def validate(self, fn: ValidateFuncT) -> ValidateFuncT:
-        self._validate_fn = fn
+        self._functions.validate = fn
         return fn
 
     def run(self, fn: RunFuncT) -> RunFuncT:
-        self._run_fn = fn
+        self._functions.run = fn
         return fn
 
     def save_results(self, fn: SaveFuncT) -> SaveFuncT:
-        self._save_fn = fn
+        self._functions.save = fn
         return fn
 
     def on_error(self, fn: ErrorFuncT) -> ErrorFuncT:
-        self._error_callback = fn
+        self._functions.error = fn
         return fn
 
     # ---------------------------
     # Execution Pipeline
     # ---------------------------
 
-    def __call__(self) -> ResultT | None:
-        """Executes the algorithm pipeline: validate → run → save_results."""
-        # Load job details
-        self._job_details = JobDetails.load(
-            _type=self.configuration.custom_input,
-            base_dir=self.configuration.environment.base_dir,
-            dids=self.configuration.environment.dids,
-            transformation_did=self.configuration.environment.transformation_did,
-            secret=self.configuration.environment.secret,
-        )
+    def execute(self) -> ResultT | None:
+        env = self.configuration.environment
+        config: Dict[str, JsonValue] = {
+            "base_dir": str(env.base_dir),
+            "dids": env.dids,
+            "secret": env.secret,
+            "transformation_did": env.transformation_did,
+        }
+
+        self._job_details = load_job_details(config, self.configuration.custom_input)
 
         self.logger.info("Loaded JobDetails")
-        self.logger.debug(asdict(self.job_details))
+        self.logger.debug(self.job_details.model_dump())
 
         try:
-            # Validation step
-            self._validate_fn(self)
+            run_in_executor(self._functions.validate(self))
 
-            # Run step
-            if self._run_fn:
+            if self._functions.run:
                 self.logger.info("Running algorithm...")
-                self._result = self._run_fn(self)
+                self._result = run_in_executor(self._functions.run(self))
             else:
                 self.logger.error("No run() function defined. Skipping execution.")
                 self._result = None
 
-            # Save step
-            self._save_fn(self, self._result, self.job_details.paths.outputs)
+            run_in_executor(
+                self._functions.save(
+                    algorithm=self,
+                    result=self._result,
+                    base=self.job_details.paths.outputs,
+                ),
+            )
 
         except Exception as e:
-            self._error_callback(self, e)
+            run_in_executor(self._functions.error(self, e))
 
         return self._result
+
+    def __call__(self) -> ResultT | None:
+        """Executes the algorithm pipeline: validate → run → save_results."""
+        return self.execute()

{ocean_runner-0.2.19 → ocean_runner-0.2.25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ocean-runner"
-version = "0.2.19"
+version = "0.2.25"
 description = "A fluent API for OceanProtocol algorithms"
 authors = [
     { name = "AgrospAI", email = "agrospai@udl.cat" },
@@ -15,7 +15,8 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
 ]
 dependencies = [
-    "oceanprotocol-job-details>=0.2.8",
+    "aiofiles>=25.1.0",
+    "oceanprotocol-job-details>=0.3.11",
     "pydantic>=2.12.5",
     "pydantic-settings>=2.12.0",
     "pytest>=8.4.2",
@@ -35,15 +36,16 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [dependency-groups]
-dev = [
-    "mypy>=1.19.1",
-]
+dev = ["mypy>=1.19.1", "types-aiofiles>=25.1.0.20251011"]
 
 [tool.hatch.build.targets.sdist]
 include = ["ocean_runner"]
 
 [tool.hatch.build.targets.wheel]
-include = ["ocean_runner"]
+packages = ["ocean_runner"]
+
+[tool.hatch.build.targets.wheel.package-data]
+ocean_runner = ["py.typed"]
 
 [tool.mypy]
 plugins = ['pydantic.mypy']