fred-oss 0.55.0__tar.gz → 0.57.0__tar.gz

{fred_oss-0.55.0/src/main/fred_oss.egg-info → fred_oss-0.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-oss
-Version: 0.55.0
+Version: 0.57.0
 Summary: FREDOSS
 Home-page: https://fred.fahera.mx
 Author: Fahera Research, Education, and Development

fred_oss-0.57.0/src/main/fred/cli/main.py

@@ -0,0 +1,59 @@
+from typing import Optional
+
+from fred.version import version
+from fred.settings import logger_manager
+from fred.cli.interface import AbstractCLI
+
+
+logger = logger_manager.get_logger(name=__name__)
+
+
+class CLIExtensionGroups:
+    """CLI Extensions providing access to various integrations by following a lazy loading pattern."""
+
+    @property
+    def databricks(self):
+        from fred.integrations.databricks.cli_ext import DatabricksExt
+        return DatabricksExt()
+    
+    @property
+    def runpod(self):
+        from fred.integrations.runpod.cli_ext import RunPodExt
+        return RunPodExt()
+    
+    @property
+    def runner_server(self):
+        from fred.worker.runner.rest.cli_ext import RunnerServerExt
+        return RunnerServerExt()
+
+
+class CLI(AbstractCLI, CLIExtensionGroups):
+
+    def version(self) -> str:
+        return version.value
+
+    def serve(
+            self,
+            classname: Optional[str] = None,
+            classpath: Optional[str] = None,
+            include_routers: Optional[list[str]] = None,
+            exclude_routers: Optional[list[str]] = None,
+            fastapi_configs: Optional[dict] = None,
+            server_configs: Optional[dict] = None,
+    ):
+        from fred.rest.server import FredServer
+
+        include_routers = include_routers or []
+        exclude_routers = exclude_routers or []
+        fastapi_configs = fastapi_configs or {}
+        server_configs = server_configs or {}
+
+        logger.info("Starting the Fred-REST Server...")
+        server = FredServer.auto(
+            include_routers=include_routers,
+            exclude_routers=exclude_routers,
+            router_classname=classname,
+            router_classpath=classpath,
+            **fastapi_configs,
+        )
+        server.start(**server_configs)

fred_oss-0.57.0/src/main/fred/rest/__init__.py

@@ -0,0 +1,17 @@
+"""
+[Fred-REST] Fred's Simple Extensible REST-API Server
+========================================================
+This module provides a simple and extensible REST-API server implementation using FastAPI.
+It includes configurations for authentication, router management, and server startup.
+"""
+from fred.maturity import Maturity, MaturityLevel
+
+
+module_maturity = Maturity(
+    level=MaturityLevel.ALPHA,
+    reference=__name__,
+    message=(
+        "Fred-REST implementation is in early development "
+        "and therefore currently with incomplete and unstable features."
+    )
+)

{fred_oss-0.55.0/src/main/fred/worker/runner → fred_oss-0.57.0/src/main/fred}/rest/auth.py

@@ -1,7 +1,8 @@
 from fastapi import Security, HTTPException, status
 from fastapi.security import APIKeyHeader
 
-from fred.worker.runner.rest.settings import FRD_RESTAPI_TOKEN
+from fred.rest.settings import FRD_RESTAPI_TOKEN
+
 
 async def verify_key(
         api_key_header: str = Security(

fred_oss-0.57.0/src/main/fred/rest/config.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from fred.rest.router.catalog.interface import RouterCatalogInterface
+from fred.rest.settings import (
+    FRD_RESTAPI_ROUTERCATALOG_CLASSPATH,
+    FRD_RESTAPI_ROUTERCATALOG_CLASSNAME,
+)
+
+@dataclass(frozen=True, slots=True)
+class ServerRouterCatalogConfig:
+    classname: str
+    classpath: str
+
+    @classmethod
+    def auto(cls, classname: Optional[str] = None, classpath: Optional[str] = None) -> "ServerRouterCatalogConfig":
+        return cls(
+            classname=classname or FRD_RESTAPI_ROUTERCATALOG_CLASSNAME,
+            classpath=classpath or FRD_RESTAPI_ROUTERCATALOG_CLASSPATH,
+        )
+
+    @property
+    def catalog(self) -> type[RouterCatalogInterface]:
+        import importlib
+
+        module = importlib.import_module(self.classpath)
+        catalog_class = getattr(module, self.classname, None)
+        if catalog_class is None:
+            raise ImportError(f"Could not find class '{self.classname}' in module '{self.classpath}'")
+        if not issubclass(catalog_class, RouterCatalogInterface):
+            raise TypeError(f"Class '{self.classname}' is not a subclass of RouterCatalogInterface")
+        return catalog_class

fred_oss-0.57.0/src/main/fred/rest/router/catalog/default/__init__.py

@@ -0,0 +1,10 @@
+from fred.rest.router.catalog.default.catalog import RouterCatalog
+from fred.settings import logger_manager
+
+logger = logger_manager.get_logger(name=__name__)
+
+
+logger.warning(
+    "You are using the default router catalog intended for demonstration purposes only. "
+    "For production use, please implement a custom router catalog."
+)

fred_oss-0.57.0/src/main/fred/rest/router/catalog/default/_base.py

@@ -0,0 +1,29 @@
+from fred.rest.router.interface import RouterInterfaceMixin
+from fred.rest.router.endpoint import RouterEndpointAnnotation
+
+
+class RouterBaseMixin(RouterInterfaceMixin):
+
+    @RouterEndpointAnnotation.set(
+        path="/",
+        methods=["GET"],
+        summary="Base endpoint",
+        description="A simple base endpoint to check service availability."
+    )
+    def base(self, include_telemetry: bool = False, **kwargs) -> dict:
+        if include_telemetry:
+            from fred.utils.runtime import RuntimeProfilingSnapshot
+            kwargs["telemetry"] = RuntimeProfilingSnapshot.auto().to_dict()
+        return {
+            "ok": True,
+            **kwargs
+        }
+
+    @RouterEndpointAnnotation.set(
+        path="/passthrough",
+        methods=["POST"],
+        summary="Passthrough POST endpoint",
+        description="An endpoint that returns all received parameters.",
+    )
+    def passthrough(self, **kwargs) -> dict:
+        return kwargs

fred_oss-0.57.0/src/main/fred/rest/router/catalog/default/_example.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from fred.rest.router.interface import RouterInterfaceMixin
+from fred.rest.router.endpoint import RouterEndpointAnnotation
+
+
+class RouterExampleMixin(RouterInterfaceMixin):
+
+    @RouterEndpointAnnotation.set(
+        path="/ping",
+        methods=["GET"],
+        summary="Ping endpoint",
+        description="A simple ping endpoint to check service availability.",
+    )
+    def ping(self, pong: Optional[str] = None, **kwargs) -> dict:
+        from fred.utils.dateops import datetime_utcnow
+
+        return {
+            "ping_time": datetime_utcnow().isoformat(),
+            "ping_response": pong or "pong",
+        }
+
+    @RouterEndpointAnnotation.set(
+        path="/passthrough",
+        methods=["GET"],
+        summary="Passthrough GET endpoint",
+        description="An endpoint that returns all received parameters.",
+    )
+    def passthrough(self, **kwargs) -> dict:
+        return kwargs

fred_oss-0.57.0/src/main/fred/rest/router/catalog/default/catalog.py

@@ -0,0 +1,20 @@
+import enum
+
+from fred.rest.router.config import RouterConfig
+from fred.rest.router.catalog.default._base import RouterBaseMixin
+from fred.rest.router.catalog.default._example import RouterExampleMixin
+
+from fred.rest.router.catalog.interface import RouterCatalogInterface
+
+
+class RouterCatalog(RouterCatalogInterface, enum.Enum):
+    BASE = RouterConfig.auto(prefix="")(apply=RouterBaseMixin)
+    EXAMPLE = RouterConfig.auto(prefix="/example")(apply=RouterExampleMixin)
+
+    def get_kwargs(self) -> dict:
+        match self:
+            case RouterCatalog.EXAMPLE:
+                # Disable the backend for the example router
+                return {"disregard_backend": True}
+            case _:
+                return {}

fred_oss-0.57.0/src/main/fred/rest/router/catalog/interface.py

@@ -0,0 +1,11 @@
+from fred.rest.router.interface import RouterInterface
+
+
+class RouterCatalogInterface:
+
+    def auto(self, **kwargs) -> RouterInterface:
+        return self.value.reference.auto(**kwargs)
+
+    def get_kwargs(self) -> dict:
+        # This method can be overridden to provide specific kwargs for router initialization
+        return {}

fred_oss-0.57.0/src/main/fred/rest/router/config.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from fred.rest.router.interface import RouterInterface, RouterInterfaceMixin
+
+
+@dataclass(frozen=True, slots=True)
+class RouterConfig:
+    prefix: str
+    other: dict
+
+    @classmethod
+    def auto(cls, prefix: str = "", **kwargs) -> "RouterConfig":
+        return cls(
+            prefix=prefix,
+            other=kwargs,
+        )
+
+    def get_applied_configs(self, router_class: type[RouterInterface]) -> "AppliedRouterConfig":
+        return AppliedRouterConfig(
+            reference=router_class,
+            config=self,
+        )
+
+    def __call__(self, apply: type[RouterInterfaceMixin]) -> "AppliedRouterConfig":
+        router_classname = f"Router{apply.__name__}"
+        return self.get_applied_configs(
+            router_class=type(router_classname, (RouterInterface, apply, ), {})
+        )
+    
+    def get_configs(self) -> dict:
+        return {
+            "prefix": self.prefix,
+            **self.other,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class AppliedRouterConfig:
+    reference: type[RouterInterface]
+    config: RouterConfig

fred_oss-0.57.0/src/main/fred/rest/router/endpoint.py

@@ -0,0 +1,97 @@
+import os
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from fastapi import Request
+
+from fred.settings import logger_manager
+
+logger = logger_manager.get_logger(name=__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class RouterEndpointConfig:
+    path: Optional[str] = None
+    methods: list[str] = field(default_factory=lambda: ["GET"])
+    configs: dict = field(default_factory=dict)
+
+    @classmethod
+    def auto(cls, **kwargs) -> "RouterEndpointConfig":
+        return cls(
+            path=kwargs.pop("path", None),
+            methods=(
+                kwargs.pop("methods", None)
+                or ["GET"]
+            ),
+            configs=kwargs
+        ) 
+
+
+@dataclass(frozen=True, slots=False)
+class RouterEndpoint:
+    function: Callable
+    configs: RouterEndpointConfig
+
+    def __call__(self, *args, **kwargs):
+        return self.function(*args, **kwargs)
+
+    def get_path(self, overwrite: Optional[str] = None) -> str:
+        fname = self.function.__name__
+        return (
+            overwrite
+            or self.configs.path
+            or logger.debug(f"Missing 'path' definition, defaulting to function name: {fname}")
+            or os.path.join("/", fname)
+        )
+
+    def route_config(self, path: Optional[str] = None) -> dict:
+        return {
+            "path": self.get_path(overwrite=path),
+            "methods": self.configs.methods,
+            **self.configs.configs,
+        }
+
+# Here are a couple of reference to understand why this class is needed:
+# https://stackoverflow.com/questions/2365701/decorating-class-methods-how-to-pass-the-instance-to-the-decorator/3296318#3296318
+# https://stackoverflow.com/questions/75409483/why-do-i-get-missing-required-argument-self-when-using-a-decorator-written-as
+@dataclass(frozen=True, slots=True)
+class RouterEndpointAnnotation(RouterEndpoint):
+    
+    @classmethod
+    def set(cls, **kwargs) -> Callable:
+        config = RouterEndpointConfig.auto(**kwargs)
+        return lambda function: cls(function=function, configs=config)
+
+    def __get__(self, other_instance, other_class) -> RouterEndpoint:
+        # Create a partial function that binds the instance (other) to the method.
+        # This method was originally implemented using the following approaches:
+        # - function = functools.partial(self.function, other)
+        # - function = lambda payload: self.function(other, **payload)
+        # - function = functools.wraps(self.function)(lambda *args, **kwargs: self.function(other, *args, **kwargs)) 
+        # However, these approaches did not work well with FastAPI's async handling and request parsing
+        # since the dynamic lambda attributes were not being recognized properly by FastAPI.
+        # The current implementation defines an async closure that correctly calls the inner function
+        # and retrieves the parameters directly from the Request object.
+        # For more info on how to use the request object, see:
+        # - https://fastapi.tiangolo.com/advanced/using-request-directly/#use-the-request-object-directly
+        # - https://stackoverflow.com/questions/67636088/how-to-access-request-object-in-router-function-using-fastapi
+        # - https://www.starlette.dev/requests/
+        async def closure(request: Request):
+            params = {
+                **request.headers,
+                **request.path_params,
+                **request.query_params,
+            }
+            try:
+                if request.method in ("POST", "PUT", "PATCH"):
+                    params.update(await request.json())
+            except Exception:
+                pass
+            # Since the annotation is usually applied to methods within a class,
+            # in most cases the 'other_instance' will be 'None'; therefore using 'other_class'
+            # should allow accessing the shared-class level state (e.g., runner_backend).
+            return self.function(other_class, **params)
+        return RouterEndpoint(
+            function=closure,
+            configs=self.configs
+        )

fred_oss-0.57.0/src/main/fred/rest/router/interface.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from fred.worker.runner.backend import RunnerBackend
+from fred.worker.runner.settings import FRD_RUNNER_BACKEND
+from fred.rest.router.endpoint import RouterEndpoint
+from fred.settings import logger_manager
+
+from fastapi import APIRouter
+
+logger = logger_manager.get_logger(name=__name__)
+
+
+class RouterInterfaceMixin:
+    """Base class for router interfaces that require a backend service."""
+    runner_backend: RunnerBackend
+
+
+@dataclass(frozen=True, slots=True)
+class RouterInterface(RouterInterfaceMixin):
+    router: APIRouter
+
+    @classmethod
+    def set_backend(
+            cls,
+            service_name: Optional[str] = None,
+            disable_runner_reuse: bool = False,
+            **kwargs
+        ) -> type["RouterInterface"]:
+        runner_backend = kwargs.pop("runner_backend", None)
+        if not disable_runner_reuse and runner_backend is None:
+            logger.warning(
+                "Runner reuse is enabled but no existing backend was provided; "
+                "a new backend will be created."
+            )
+            disable_runner_reuse = True
+        if disable_runner_reuse:
+            runner_backend = RunnerBackend.auto(
+                service_name=service_name or FRD_RUNNER_BACKEND,
+                **kwargs,
+            )
+        if runner_backend is None:
+            raise ValueError("Runner backend could not be determined or created.")
+        return type(
+            "RouterInterfaceWithBackend",
+            (cls, ),
+            {
+                "runner_backend": runner_backend
+            }
+        ) 
+
+    @classmethod
+    def auto(
+        cls,
+        service_name: Optional[str] = None,
+        router: Optional[APIRouter] = None,
+        disregard_backend: bool = False,
+        disregard_endpoint_setup: bool = False,
+        **kwargs,
+    ) -> "RouterInterface":
+        subcls = cls if disregard_backend else cls.set_backend(
+            service_name=service_name,
+            runner_backend=getattr(cls, "runner_backend", None),
+            **kwargs
+        )
+        instance = subcls(router=router or APIRouter())
+        if disregard_endpoint_setup:
+            return instance
+        for endpoint in subcls.endpoint_definitions():
+            instance.register_endpoint(endpoint)
+        return instance
+
+    def register_endpoint(self, endpoint: RouterEndpoint, path: Optional[str] = None):
+        route_config = endpoint.route_config(path=path)
+        self.router.add_api_route(endpoint=endpoint.function, **route_config)
+
+    @classmethod
+    def endpoint_definitions(cls) -> list[RouterEndpoint]:
+        return [
+            obj
+            for attr in dir(cls)
+            if isinstance((obj := getattr(cls, attr)), RouterEndpoint)
+        ]
+    
+    @classmethod
+    def endpoint_definition_mapping(cls) -> dict[str, RouterEndpoint]:
+        return {
+            endpoint.get_path(): endpoint
+            for endpoint in cls.endpoint_definitions()
+        }

{fred_oss-0.55.0/src/main/fred/worker/runner → fred_oss-0.57.0/src/main/fred}/rest/server.py

@@ -1,29 +1,37 @@
 from dataclasses import dataclass
+from typing import Optional
 
 from fastapi import FastAPI, Depends
 
-from fred.settings import logger_manager, get_environ_variable
-from fred.worker.runner.rest.settings import (
+from fred.settings import (
+    get_environ_variable,
+    logger_manager,
+)
+from fred.rest.settings import (
     FRD_RESTAPI_HOST,
     FRD_RESTAPI_PORT,
+    FRD_RESTAPI_LOGLEVEL,
+    FRD_RESTAPI_DISABLE_AUTH,
 )
-from fred.worker.runner.rest.routers.catalog import RouterCatalog
-from fred.worker.runner.rest.auth import verify_key
+from fred.rest.config import ServerRouterCatalogConfig
+from fred.rest.auth import verify_key
 
 logger = logger_manager.get_logger(name=__name__)
 
 
 @dataclass(frozen=True, slots=True)
-class RunnerServer:
+class FredServer:
     app: FastAPI
     include_routers: list[str]
     exclude_routers: list[str]
+    router_classname: Optional[str] = None
+    router_classpath: Optional[str] = None
 
     @classmethod
-    def auto(cls, **kwargs) -> "RunnerServer":
+    def auto(cls, **kwargs) -> "FredServer":
         # Include routers by checking on keyword argument or environment variable
         include_routers = kwargs.pop("include_routers", None) or get_environ_variable(
-            "FRD_RUNNER_API_INCLUDE_ROUTERS",
+            "FRD_RESTAPI_INCLUDE_ROUTERS",
             default=""
         )
         if isinstance(include_routers, str):
@@ -34,7 +42,7 @@ class RunnerServer:
             ]
         # Exclude routers by checking on keyword argument or environment variable
         exclude_routers = kwargs.pop("exclude_routers", None) or get_environ_variable(
-            "FRD_RUNNER_API_EXCLUDE_ROUTERS",
+            "FRD_RESTAPI_EXCLUDE_ROUTERS",
             default=""
         )
         if isinstance(exclude_routers, str):
@@ -43,23 +51,33 @@ class RunnerServer:
                 for router in exclude_routers.split(";")
                 if (name := router.strip())
             ]
-        # Create FastAPI instance
-        kwargs["dependencies"] = kwargs.get("dependencies", []) + [
+        # Auth dependencies setup
+        auth_dependency = [] if FRD_RESTAPI_DISABLE_AUTH else [
             Depends(verify_key),
         ]
+        kwargs["dependencies"] = kwargs.get("dependencies", []) + auth_dependency
+        # Create FastAPI app instance
         app_instance = FastAPI(**kwargs)
+        router_classname = kwargs.pop("router_classname", None)
+        router_classpath = kwargs.pop("router_classpath", None)
         return cls(
             app=app_instance,
             include_routers=include_routers,
             exclude_routers=exclude_routers,
+            router_classname=router_classname,
+            router_classpath=router_classpath,
         )
 
     def __post_init__(self):
         logger.info("Attempting to register routers...")
         logger.info("Included routers candidates: %s", self.include_routers or "ALL")
         logger.info("Excluded routers candidates: %s", self.exclude_routers or "NONE")
-        for router in RouterCatalog:
-            name = router.name.upper()
+        srcc = ServerRouterCatalogConfig.auto(
+            classname=self.router_classname,
+            classpath=self.router_classpath,
+        )
+        for router_spec in srcc.catalog:
+            name = router_spec.name.upper()
             if self.include_routers and name not in self.include_routers:
                 logger.info(f"Skipping router '{name}' as it's not in the include list.")
                 continue
@@ -67,10 +85,11 @@ class RunnerServer:
                 logger.info(f"Skipping router '{name}' as it's in the exclude list.")
                 continue
             logger.info(f"Registering router '{name}'.")
-            self.app.include_router(
-                router.get_router_instance(),
-                **router.get_router_configs(),
-            ) 
+            kwargs = router_spec.get_kwargs()
+            router_instance = router_spec.value.reference.auto(**kwargs)
+            router_configs = router_spec.value.config.get_configs()
+            # Register the router in the FastAPI app
+            self.app.include_router(router_instance.router, **router_configs) 
 
     def start(self, **kwargs):
         import uvicorn
@@ -78,7 +97,7 @@ class RunnerServer:
         server_kwargs = {
             "host": kwargs.pop("host", FRD_RESTAPI_HOST),
             "port": int(kwargs.pop("port", FRD_RESTAPI_PORT)),
-            "log_level": "info",
+            "log_level": FRD_RESTAPI_LOGLEVEL,
             **kwargs,
         }
 

fred_oss-0.57.0/src/main/fred/rest/settings.py

@@ -0,0 +1,46 @@
+from fred.settings import get_environ_variable, logger_manager
+
+logger = logger_manager.get_logger(name=__name__)
+
+
+FRD_RESTAPI_HOST = get_environ_variable(
+    "FRD_RESTAPI_HOST",
+    default="0.0.0.0"
+)
+FRD_RESTAPI_PORT = int(get_environ_variable(
+    "FRD_RESTAPI_PORT",
+    default=8000
+))
+
+FRD_RESTAPI_LOGLEVEL = get_environ_variable(
+    "FRD_RESTAPI_LOGLEVEL",
+    default="info"
+).lower()
+
+FRD_RESTAPI_DISABLE_AUTH = get_environ_variable(
+    "FRD_RESTAPI_DISABLE_AUTH",
+    default="false"
+).lower() in ("1", "true", "yes", "on")
+
+FRD_RESTAPI_TOKEN = get_environ_variable(
+    "FRD_RESTAPI_TOKEN",
+    default=None
+)
+if not FRD_RESTAPI_TOKEN:
+    logger.warning("FRD_RESTAPI_TOKEN not found in environment; using default token 'changeme'.")
+    FRD_RESTAPI_TOKEN = "changeme"
+
+FRD_RESTAPI_EXCLUDE_BUILTIN_ROUTERS = get_environ_variable(
+    "FRD_RESTAPI_EXCLUDE_BUILTIN_ROUTERS",
+    default="false",
+).lower() in ("1", "true", "yes", "on")
+
+FRD_RESTAPI_ROUTERCATALOG_CLASSNAME = get_environ_variable(
+    "FRD_RESTAPI_ROUTERCATALOG_CLASSNAME",
+    default="RouterCatalog",
+)
+
+FRD_RESTAPI_ROUTERCATALOG_CLASSPATH = get_environ_variable(
+    "FRD_RESTAPI_ROUTERCATALOG_CLASSPATH",
+    default="fred.rest.router.catalog.default",
+)

fred_oss-0.57.0/src/main/fred/version

@@ -0,0 +1 @@
+0.57.0

fred_oss-0.57.0/src/main/fred/worker/runner/rest/router/_base.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+
+from fred.rest.router.interface import RouterInterfaceMixin
+from fred.rest.router.endpoint import RouterEndpointAnnotation
+
+@dataclass(frozen=True, slots=True)
+class RouterBaseMixin(RouterInterfaceMixin):
+    
+    @RouterEndpointAnnotation.set(
+        path="/",
+        methods=["GET"],
+        summary="Base endpoint",
+        description="A simple base endpoint to check service availability."
+    )
+    def base(self, include_telemetry: bool = False, **kwargs) -> dict:
+        if include_telemetry:
+            from fred.utils.runtime import RuntimeProfilingSnapshot
+            kwargs["telemetry"] = RuntimeProfilingSnapshot.auto().to_dict()
+        return {
+            "ok": True,
+            **kwargs
+        }