Merge branch 'adding-fast-api-registry' into distracted-shirley

* adding-fast-api-registry:
  started adding the Fast_API registry classes
  Update release badge and version file

Author: DinisCruz

README.md

@@ -1,6 +1,6 @@
 # OSBot-Fast-API
 
-![Current Release](https://img.shields.io/badge/release-v0.32.1-blue)
+![Current Release](https://img.shields.io/badge/release-v0.32.2-blue)
 ![Python](https://img.shields.io/badge/python-3.8+-green)
 ![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-red)
 ![Type-Safe](https://img.shields.io/badge/Type--Safe-✓-brightgreen)

osbot_fast_api/services/__init__.py

@@ -0,0 +1,32 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Service__Client__Base
+# Abstract base class that all service clients must inherit
+# Provides the contract for registration with Services__Registry
+# ═══════════════════════════════════════════════════════════════════════════════
+from osbot_fast_api.services.schemas.registry.Schema__Service__Client__Config import Schema__Service__Client__Config
+from osbot_fast_api.services.schemas.registry.collections.List__Env_Vars import List__Env_Vars
+from osbot_utils.type_safe.Type_Safe                                            import Type_Safe
+
+
+
+# todo: rename this class to Fast_API__Service__Registry__Client__Base
+
+class Service__Client__Base(Type_Safe):                                         # Base class for all service clients
+    config : Schema__Service__Client__Config                                    # Configuration for this client
+
+    def setup_from_env(self) -> 'Service__Client__Base':                        # Configure from environment variables
+        raise NotImplementedError("Subclass must implement setup_from_env()")
+
+    def requests(self):                                                         # Return the *__Requests transport object
+        raise NotImplementedError("Subclass must implement requests()")
+
+    def health(self) -> bool:                                                   # Basic health check
+        raise NotImplementedError("Subclass must implement health()")
+
+    @classmethod
+    def env_vars(cls) -> List__Env_Vars:                                        # Expected env vars for this client
+        raise NotImplementedError("Subclass must implement env_vars()")
+
+    @classmethod
+    def client_name(cls) -> str:                                                # Human-readable name for errors
+        return cls.__name__

osbot_fast_api/services/registry/Service__Client__Base.py

@@ -0,0 +1,49 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Services__Registry
+# Central registry for service client discovery across deployment modes
+# Enables zero-code-change switching between IN_MEMORY and REMOTE modes
+# ═══════════════════════════════════════════════════════════════════════════════
+from osbot_fast_api.services.registry.Service__Client__Base import Service__Client__Base
+from osbot_fast_api.services.schemas.registry.collections.Dict__Clients__By_Type import Dict__Clients__By_Type
+from osbot_fast_api.services.schemas.registry.collections.List__Client_Types import List__Client_Types
+from osbot_utils.type_safe.type_safe_core.decorators.type_safe import type_safe
+
+
+# todo: rename this class to Fast_API__Service__Registry
+#       this class needs to be refactored to not use static methods where _clients is an instance variable
+#       and the main static reference for the shared (singleton method) is retrieve by the "fast_api__service_registry = Services__Registry() " that can be seen at the end of this file
+#       this means that we can make the Services__Registry a Type_Safe class and remove the None assigment, since Type_Safe will then create that _clients object
+#       rename '_clients' with 'clients
+class Services__Registry:                                                       # Static singleton registry for service clients
+    _clients : Dict__Clients__By_Type = None                                   # Class-level storage (lazy initialized)
+
+    @classmethod
+    def clients(cls) -> Dict__Clients__By_Type:                                 # Lazy initialization of storage
+        if cls._clients is None:
+            cls._clients = Dict__Clients__By_Type()
+        return cls._clients
+
+    @classmethod
+    @type_safe
+    def register(cls, client: Service__Client__Base) -> None:                   # Register a client instance
+        cls.clients()[type(client)] = client                                    # Index by actual type
+
+    @classmethod
+    def client(cls, client_type: type) -> Service__Client__Base:                # Retrieve client by type
+        if client_type not in cls.clients():
+            return None                                                         # Not registered = None
+        return cls.clients()[client_type]                                       # Return registered client
+
+    @classmethod
+    def is_registered(cls, client_type: type) -> bool:                          # Check if type is registered
+        return client_type in cls.clients()
+
+    @classmethod
+    def clear(cls) -> None:                                                     # Reset registry for test isolation
+        cls._clients = None
+
+    @classmethod
+    def registered_types(cls) -> List__Client_Types:                            # List all registered client types
+        return List__Client_Types(list(cls.clients().keys()))
+
+fast_api__service_registry = Services__Registry()

osbot_fast_api/services/registry/Services__Registry.py

@@ -0,0 +1,16 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Schema__Env_Var
+# Defines an environment variable that a service client expects
+# ═══════════════════════════════════════════════════════════════════════════════
+
+from osbot_utils.type_safe.Type_Safe             import Type_Safe
+from osbot_utils.type_safe.primitives.core.Safe_Str import Safe_Str
+
+# todo: refactor this class to be Schema__Fast_API__Registry__Env_Var
+#     : also:
+#           name should a type of Schema__Env_Var__Name (which needs to be created)
+#           we should also create an Schema__Env_Var__Value
+#           add note to refactor these to the OSbot-Utils project
+class Schema__Env_Var(Type_Safe):                                               # Pure data - environment variable definition
+    name     : Safe_Str                                                        # Env var name (e.g., "URL__TARGET_SERVER__CACHE")
+    required : bool      = True                                                # Must be present at startup?

osbot_fast_api/services/registry/__init__.py

@@ -0,0 +1,20 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Schema__Service__Client__Config
+# Configuration schema shared by all service clients
+# ═══════════════════════════════════════════════════════════════════════════════
+
+from fastapi                                                                            import FastAPI
+from osbot_utils.type_safe.Type_Safe                                                    import Type_Safe
+from mgraph_ai_service_cache_client.client.requests.schemas.enums.Enum__Client__Mode    import Enum__Client__Mode
+from osbot_fast_api.services.schemas.registry.safe_str.Safe_Str__API_Key__Name          import Safe_Str__API_Key__Name
+from osbot_fast_api.services.schemas.registry.safe_str.Safe_Str__API_Key__Value         import Safe_Str__API_Key__Value
+from osbot_utils.type_safe.primitives.domains.web.safe_str.Safe_Str__Url                import Safe_Str__Url
+
+# todo: rename this class to Fast_API__Service__Registry__Client__Config
+
+class Schema__Service__Client__Config(Type_Safe):                               # Pure data - client configuration
+    mode          : Enum__Client__Mode             = None                       # IN_MEMORY or REMOTE (None = not configured)
+    fast_api_app  : FastAPI                        = None                       # FastAPI app for IN_MEMORY mode
+    base_url      : Safe_Str__Url                  = None                       # Base URL for REMOTE mode
+    api_key_name  : Safe_Str__API_Key__Name        = None                       # HTTP header name for auth
+    api_key_value : Safe_Str__API_Key__Value       = None                       # HTTP header value for auth

osbot_fast_api/services/schemas/__init__.py

@@ -0,0 +1,12 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Dict__Clients__By_Type
+# Type-safe dictionary for storing service clients indexed by their class type
+# ═══════════════════════════════════════════════════════════════════════════════
+from osbot_fast_api.services.registry.Service__Client__Base           import Service__Client__Base
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Dict import Type_Safe__Dict
+
+
+# todo: rename this class to Dict__Fast_API__Service__Clients_By_Type
+class Dict__Clients__By_Type(Type_Safe__Dict):                                  # Maps client type → client instance
+    expected_key_type   = type                                                  # The client class itself
+    expected_value_type = Service__Client__Base                                 # Instance of client