mindtrace-services 0.1.0__tar.gz

mindtrace_services-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   

mindtrace_services-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: mindtrace-services
+Version: 0.1.0
+Summary: Service layer for Mindtrace
+Author: Mindtrace Team
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: mindtrace-core
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: uvicorn>=0.34.3
+Dynamic: license-file

mindtrace_services-0.1.0/mindtrace/services/__init__.py

@@ -0,0 +1,27 @@
+from mindtrace.services.core.connection_manager import ConnectionManager
+from mindtrace.services.core.service import Service
+from mindtrace.services.core.types import (
+    EndpointsSchema,
+    Heartbeat,
+    HeartbeatSchema,
+    PIDFileSchema,
+    ServerIDSchema,
+    ServerStatus,
+    ShutdownSchema,
+    StatusSchema,
+)
+from mindtrace.services.core.utils import generate_connection_manager
+
+__all__ = [
+    "ConnectionManager",
+    "EndpointsSchema",
+    "generate_connection_manager",
+    "Heartbeat",
+    "HeartbeatSchema",
+    "PIDFileSchema",
+    "ServerIDSchema",
+    "Service",
+    "ServerStatus",
+    "ShutdownSchema",
+    "StatusSchema",
+]

mindtrace_services-0.1.0/mindtrace/services/core/connection_manager.py

@@ -0,0 +1,140 @@
+"""Client-side helper class for communicating with any ServerBase server."""
+
+import asyncio
+from urllib.parse import urljoin
+from uuid import UUID
+
+import httpx
+import requests
+from fastapi import HTTPException
+from urllib3.util.url import Url, parse_url
+
+from mindtrace.core import Mindtrace, Timeout, ifnone
+from mindtrace.services.core.types import ServerStatus, ShutdownOutput, StatusOutput
+
+
+class ConnectionManager(Mindtrace):
+    """Client-side helper class for communicating with Mindtrace servers."""
+
+    def __init__(self, url: Url | None = None, server_id: UUID | None = None, server_pid_file: str | None = None):
+        super().__init__()
+        self.url = ifnone(url, default=parse_url(self.config["MINDTRACE_DEFAULT_HOST_URLS"]["Service"]))
+        self._server_id = server_id
+        self._server_pid_file = server_pid_file
+
+    def shutdown(self, block: bool = True):
+        """Shutdown the server.
+
+        This method sends a shutdown request to the server. If block=True, it will also poll the server until it
+        becomes unavailable, ensuring the shutdown process is complete.
+
+        Args:
+            block: If True, waits for the server to actually shut down. If False, returns immediately after sending
+            the shutdown request.
+
+        Example::
+
+            from mindtrace.services import Service, ServerStatus
+
+            cm = Service.launch()
+            assert cm.status == ServerStatus.Available
+
+            # Wait for shutdown to complete
+            cm.shutdown(block=True)
+            assert cm.status == ServerStatus.Down
+
+            # Or send shutdown command and return immediately
+            cm.shutdown(block=False)
+        """
+        # Send the shutdown request
+        response = requests.request("POST", urljoin(str(self.url), "shutdown"), timeout=60)
+        if response.status_code != 200:
+            raise HTTPException(response.status_code, response.content)
+
+        # If not blocking, return immediately after sending the shutdown request
+        if not block:
+            return ShutdownOutput(shutdown=True)
+
+        def check_server_down():
+            """Check if server is down by trying to connect to status endpoint."""
+            try:
+                _ = requests.post(urljoin(str(self.url), "status"), timeout=2)
+                # If we get any response, server is still up - raise exception to retry
+                raise ConnectionError("Server still responding")
+            except requests.exceptions.ConnectionError:
+                # Connection failed - server is down, this is what we want
+                return True
+            except requests.exceptions.Timeout:
+                # Timeout - server might be shutting down, this is what we want
+                return True
+
+        timeout_handler = Timeout(
+            timeout=30,
+            retry_delay=0.2,
+            exceptions=(ConnectionError,),
+            progress_bar=False,  # No progress bar for shutdown
+        )
+        try:
+            timeout_handler.run(check_server_down)
+        except TimeoutError:
+            self.logger.error(f"Server at {self.url} did not shut down within timeout period.")
+            raise TimeoutError(f"Server at {self.url} did not shut down within timeout period.")
+
+        return ShutdownOutput(shutdown=True)
+
+    async def ashutdown(self, block: bool = True):
+        """Async shutdown of the server."""
+        # Run the shutdown in a thread pool to avoid blocking the event loop
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.shutdown, block)
+
+    def status(self):
+        """Get the status of the server.
+
+        Returns ServerStatus.DOWN if the server is unreachable, otherwise returns the actual status.
+
+        Returns:
+            StatusOutput with the current server status.
+        """
+        try:
+            response = requests.post(urljoin(str(self.url), "status"), timeout=10)
+            if response.status_code != 200:
+                return StatusOutput(status=ServerStatus.DOWN)
+
+            result = response.json()
+            return StatusOutput(**result)
+
+        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout, requests.exceptions.RequestException):
+            return StatusOutput(status=ServerStatus.DOWN)
+
+    async def astatus(self):
+        """Async get the status of the server.
+
+        Returns ServerStatus.DOWN if the server is unreachable, otherwise returns the actual status.
+
+        Returns:
+            StatusOutput with the current server status.
+        """
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(urljoin(str(self.url), "status"))
+
+            if response.status_code != 200:
+                return StatusOutput(status=ServerStatus.DOWN)
+
+            result = response.json()
+            return StatusOutput(**result)
+
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.RequestError):
+            return StatusOutput(status=ServerStatus.DOWN)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.logger.debug(f"Shutting down {self.name} Server.")
+        try:
+            self.shutdown()
+        finally:
+            if exc_type is not None:
+                info = (exc_type, exc_val, exc_tb)
+                self.logger.exception("Exception occurred", exc_info=info)
+                return self.suppress
+        return False

mindtrace_services-0.1.0/mindtrace/services/core/launcher.py

@@ -0,0 +1,72 @@
+import argparse
+import json
+import logging
+from argparse import RawTextHelpFormatter
+from pathlib import Path
+
+from gunicorn.app.base import BaseApplication
+
+from mindtrace.core import instantiate_target, setup_logger
+
+
+class Launcher(BaseApplication):
+    """Gunicorn application launcher for Mindtrace services."""
+
+    def __init__(self, options):
+        self.gunicorn_options = {
+            "bind": options.bind,
+            "workers": options.num_workers,
+            "worker_class": options.worker_class,
+            "pidfile": options.pid,
+        }
+
+        # Parse init params
+        init_params = json.loads(options.init_params) if options.init_params else {}
+
+        # Create server with initialization parameters
+        server = instantiate_target(options.server_class, **init_params)
+        server.logger = setup_logger(
+            name=server.unique_name,
+            stream_level=logging.INFO,
+            file_level=logging.DEBUG,
+            log_dir=Path(server.config["MINDTRACE_LOGGER_DIR"]),
+        )
+        self.application = server.app
+        server.url = options.bind
+        super().__init__()
+
+    def load_config(self):
+        config = {
+            key: value for key, value in self.gunicorn_options.items() if key in self.cfg.settings and value is not None
+        }
+        for key, value in config.items():
+            self.cfg.set(key.lower(), value)
+
+    def load(self):
+        return self.application
+
+
+def main():
+    parser = argparse.ArgumentParser(description="MINDTRACE SERVER LAUNCHER\n", formatter_class=RawTextHelpFormatter)
+    parser.add_argument(
+        "-s",
+        "--server_class",
+        type=str,
+        nargs="?",
+        default="mindtrace.services.core.serve.Service",
+        help="Server class to launch",
+    )
+    parser.add_argument("-w", "--num_workers", type=int, default=1, help="Number of workers")
+    parser.add_argument(
+        "-b", "--bind", type=str, default="127.0.0.1:8080", help="URL address to bind with the application"
+    )
+    parser.add_argument("-p", "--pid", type=str, default=None)
+    parser.add_argument("-k", "--worker_class", type=str, default="uvicorn.workers.UvicornWorker")
+    parser.add_argument("--init-params", type=str, help="JSON string of initialization parameters")
+    args = parser.parse_args()
+
+    Launcher(args).run()
+
+
+if __name__ == "__main__":
+    main()

mindtrace_services-0.1.0/mindtrace/services/core/service.py

@@ -0,0 +1,456 @@
+"""Service base class. Provides unified methods for all Mindtrace (micro)services."""
+
+import atexit
+import json
+import logging
+import os
+import signal
+import subprocess
+import uuid
+from contextlib import asynccontextmanager
+from importlib.metadata import version
+from pathlib import Path
+from typing import Type, TypeVar
+from uuid import UUID
+
+import fastapi
+import psutil
+import requests
+from fastapi import FastAPI, HTTPException
+from urllib3.util.url import Url, parse_url
+
+from mindtrace.core import Mindtrace, TaskSchema, Timeout, ifnone, ifnone_url, named_lambda
+from mindtrace.services.core.connection_manager import ConnectionManager
+from mindtrace.services.core.types import (
+    EndpointsSchema,
+    Heartbeat,
+    HeartbeatSchema,
+    PIDFileSchema,
+    ServerIDSchema,
+    ServerStatus,
+    ShutdownSchema,
+    StatusSchema,
+)
+from mindtrace.services.core.utils import generate_connection_manager
+
+T = TypeVar("T", bound="Service")  # A generic variable that can be 'Service', or any subclass.
+C = TypeVar("C", bound="ConnectionManager")  # '' '' '' 'ConnectionManager', or any subclass.
+
+
+class Service(Mindtrace):
+    """Base class for all Mindtrace services."""
+
+    _status = ServerStatus.DOWN
+    _endpoints: dict[str, TaskSchema] = {}
+    _client_interface: Type[C] | None = None
+    _active_servers: dict[UUID, psutil.Process] = {}
+
+    def __init__(
+        self,
+        *,
+        url: str | Url | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        summary: str | None = None,
+        description: str | None = None,
+        terms_of_service: str | None = None,
+        license_info: str | None = None,
+    ):
+        """Initialize server instance. This is for internal use by the launch() method.
+
+        Args:
+            url: Full URL string or Url object
+            host: Host address (e.g. "localhost" or "192.168.1.100")
+            port: Port number
+            summary: Summary of the server
+            description: Description of the server
+            terms_of_service: Terms of service for the server
+            license_info: License information for the server
+
+        Warning: Services should be created via the ServiceClass.launch() method. The __init__ method here should be
+        considered private internal use.
+        """
+        super().__init__()
+        self._status: ServerStatus = ServerStatus.AVAILABLE
+        self.id, self.pid_file = self._generate_id_and_pid_file()
+
+        # Build URL with the following priority:
+        # 1. Explicit URL parameter
+        # 2. Host/port parameters
+        # 3. Default URL from config
+        self._url = self.build_url(url=url, host=host, port=port)
+
+        """
+        self.logger = default_logger(
+            name=self.unique_name,
+            stream_level=logging.INFO,
+            file_level=logging.DEBUG,
+            file_name=self.default_log_file(),
+        )
+        """
+
+        description = ifnone(description, default=f"{self.name} server.")
+        version_str = "Mindtrace " + version("mindtrace-services")
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            """Lifespan for the FastAPI app."""
+            self.logger.info(f"Server {self.id} starting up.")
+            yield
+            await self.shutdown_cleanup()
+            self.logger.info(f"Server {self.id} shut down.")
+
+        self.app = FastAPI(
+            title=self.name,
+            description=description,
+            summary=summary,
+            version=version_str,
+            terms_of_service=terms_of_service,
+            license_info=license_info,
+            lifespan=lifespan,
+        )
+        self.add_endpoint(
+            path="/endpoints",
+            func=named_lambda("endpoints", lambda: {"endpoints": list(self._endpoints.keys())}),
+            schema=EndpointsSchema(),
+        )
+        self.add_endpoint(
+            path="/status", func=named_lambda("status", lambda: {"status": self.status.value}), schema=StatusSchema()
+        )
+        self.add_endpoint(
+            path="/heartbeat",
+            func=named_lambda("heartbeat", lambda: {"heartbeat": self.heartbeat()}),
+            schema=HeartbeatSchema(),
+        )
+        self.add_endpoint(
+            path="/server_id", func=named_lambda("server_id", lambda: {"server_id": self.id}), schema=ServerIDSchema()
+        )
+        self.add_endpoint(
+            path="/pid_file", func=named_lambda("pid_file", lambda: {"pid_file": self.pid_file}), schema=PIDFileSchema()
+        )
+        self.add_endpoint(
+            path="/shutdown", func=self.shutdown, schema=ShutdownSchema(), autolog_kwargs={"log_level": logging.DEBUG}
+        )
+
+    @classmethod
+    def _generate_id_and_pid_file(cls, unique_id: UUID | None = None, pid_file: str | None = None) -> tuple[UUID, str]:
+        """Generate a unique_id and pid_file for the server.
+
+        The logic used ensures that the pid_file contains the (human-readable) class name as well as the unique_id.
+        """
+
+        # The following logic assures that the pid_file contains the unique_id
+        if unique_id is not None and pid_file is not None:
+            if str(unique_id) not in pid_file:
+                raise ValueError(f"unique_id {unique_id} not found in pid_file {pid_file}")
+        elif unique_id is not None and pid_file is None:
+            unique_id = unique_id
+            pid_file = cls._server_id_to_pid_file(unique_id)
+        elif unique_id is None and pid_file is not None:
+            unique_id = cls._pid_file_to_server_id(pid_file)
+            pid_file = pid_file
+        else:  # unique_id is None and pid_file is None
+            unique_id = uuid.uuid1()
+            pid_file = cls._server_id_to_pid_file(unique_id)
+
+        Path(pid_file).parent.mkdir(parents=True, exist_ok=True)
+        return unique_id, pid_file
+
+    @classmethod
+    def _server_id_to_pid_file(cls, server_id: UUID) -> str:
+        return os.path.join(cls.config["MINDTRACE_SERVER_PIDS_DIR_PATH"], f"{cls.__name__}_{server_id}_pid.txt")
+
+    @classmethod
+    def _pid_file_to_server_id(cls, pid_file: str) -> UUID:
+        return UUID(pid_file.split("_")[-2])
+
+    @classmethod
+    def status_at_host(cls, url: str | Url, timeout: int = 60) -> ServerStatus:
+        """Check the status of the service at the given host url.
+
+        This command may be used to check if a service (including this one) is available at a given host, useful for
+        determining when a service has been successfully launched.
+
+        Args:
+            url: The host URL of the service.
+        """
+        url = parse_url(url) if isinstance(url, str) else url
+        try:
+            response = requests.request("POST", str(url) + "/status", timeout=timeout)
+        except requests.exceptions.ConnectionError:
+            return ServerStatus.DOWN
+        if response.status_code != 200:
+            return ServerStatus.DOWN
+
+        status = ServerStatus(response.json()["status"])
+        return status
+
+    @classmethod
+    def connect(cls: Type[T], url: str | Url | None = None, timeout: int = 60) -> C:
+        """Connect to an existing service.
+
+        The returned connection manager is determined by the registered connection manager for the service. If one has
+        not explicitly been registered, the default connection manager (ConnectionManagerBase) will be used.
+
+        Args:
+            url: The host URL of the service.
+
+        Returns:
+            A connection manager for the service.
+
+        Raises:
+            HTTPException: If the server fails to connect, an HTTPException will be raised with status code 503.
+        """
+        url = ifnone_url(url, default=cls.default_url())
+        host_status = cls.status_at_host(url, timeout=timeout)
+        if host_status == ServerStatus.AVAILABLE:
+            if cls._client_interface is None:
+                return generate_connection_manager(cls)(url=url)
+            else:
+                return cls._client_interface(url=url)
+        raise HTTPException(status_code=503, detail=f"Server failed to connect: {host_status}")
+
+    @classmethod
+    def launch(
+        cls: Type[T],
+        *,
+        url: str | Url | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        block: bool = False,
+        num_workers: int = 1,
+        wait_for_launch: bool = True,
+        timeout: int = 60,
+        progress_bar: bool = True,
+        **kwargs,
+    ):
+        """Launch a new server instance.
+
+        The server can be configured through either explicit URL parameters or through kwargs. All kwargs are passed
+        directly to the server instance's __init__ method.
+
+        Args:
+            url: Full URL string or Url object (highest priority)
+            host: Host address (used if url not provided)
+            port: Port number (used if url not provided)
+            block: If True, blocks the calling process and keeps the server running
+            num_workers: Number of worker processes
+            wait_for_launch: Whether to wait for server startup
+            timeout: Timeout for server startup in seconds
+            progress_bar: Show progress bar during startup
+            **kwargs: Additional parameters passed to the server's __init__ method
+        """
+        # Build the launch URL with priority
+        launch_url = cls.build_url(url=url, host=host, port=port)
+
+        # Check that there is not already a service at the given URL
+        try:
+            existing_status = cls.status_at_host(launch_url)
+            if existing_status != ServerStatus.DOWN:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Server {cls.unique_name} at {launch_url} is already running with status {existing_status}.",
+                )
+        except RuntimeError as e:
+            cls.logger.warning(f"Another service is already running at {launch_url}. New service was NOT launched.")
+            raise e
+
+        # All kwargs (including URL params) go directly to init_params
+        init_params = {"url": str(launch_url), **kwargs}
+
+        # Create launch command
+        server_id = uuid.uuid1()
+        launch_command = [
+            "python",
+            "-m",
+            "mindtrace.services.core.launcher",
+            "-s",
+            cls.unique_name,
+            "-w",
+            str(num_workers),
+            "-b",
+            f"{launch_url.host}:{launch_url.port}",
+            "-p",
+            cls._server_id_to_pid_file(server_id),
+            "-k",
+            "uvicorn.workers.UvicornWorker",
+            "--init-params",
+            json.dumps(init_params),
+        ]
+        cls.logger.warning(f'Launching {cls.unique_name} with command: "{launch_command}"')
+        process = subprocess.Popen(launch_command)
+
+        # Register cleanup if this is the first server
+        cls._active_servers[server_id] = process
+        if len(cls._active_servers) == 1:
+            atexit.register(cls._cleanup_all_servers)
+            signal.signal(signal.SIGTERM, lambda sig, frame: cls._cleanup_all_servers())
+            signal.signal(signal.SIGINT, lambda sig, frame: cls._cleanup_all_servers())
+
+        # Wait for server to be available and get connection manager
+        connection_manager = None
+        if wait_for_launch:
+            timeout_handler = Timeout(
+                timeout=timeout,
+                exceptions=(ConnectionRefusedError, requests.exceptions.ConnectionError, HTTPException),
+                progress_bar=progress_bar,
+                desc=f"Launching {cls.unique_name.split('.')[-1]} at {launch_url}",
+            )
+            try:
+                connection_manager = timeout_handler.run(cls.connect, url=launch_url)
+            except Exception as e:
+                cls._cleanup_server(server_id)
+                raise e
+
+        # If blocking is requested, wait for the process
+        if block:
+            try:
+                process.wait()
+            except KeyboardInterrupt:
+                cls._cleanup_server(server_id)
+                raise
+            finally:
+                cls._cleanup_server(server_id)
+
+        return connection_manager
+
+    @property
+    def endpoints(self) -> dict[str, TaskSchema]:
+        """Return the available commands for the service."""
+        return self._endpoints
+
+    @property
+    def status(self) -> ServerStatus:
+        """Returns the current status of this service."""
+        return self._status
+
+    def heartbeat(self) -> Heartbeat:
+        """Request the server to do a complete heartbeat check."""
+        return Heartbeat(
+            status=self.status,
+            server_id=self.id,
+            message="Heartbeat check successful.",
+            details=None,
+        )
+
+    @classmethod
+    def _cleanup_server(cls, server_id: UUID):
+        if server_id in cls._active_servers:
+            process = cls._active_servers[server_id]
+            try:
+                parent = psutil.Process(process.pid)
+                children = parent.children(recursive=True)
+                for child in children:
+                    try:
+                        child.terminate()
+                    except psutil.NoSuchProcess:
+                        pass
+                try:
+                    parent.terminate()
+                    parent.wait(timeout=5)
+                except psutil.NoSuchProcess:
+                    pass
+            except (psutil.NoSuchProcess, psutil.TimeoutExpired):
+                cls.logger.debug("Process already terminated.")
+            finally:
+                del cls._active_servers[server_id]
+
+    @classmethod
+    def _cleanup_all_servers(cls):
+        """Cleanup the servers."""
+        for server_id in list(cls._active_servers.keys()):
+            cls._cleanup_server(server_id)
+
+    @staticmethod
+    def shutdown() -> fastapi.Response:
+        """HTTP endpoint to shut down the server."""
+        os.kill(os.getppid(), signal.SIGTERM)  # kill the parent gunicorn process as it will respawn us otherwise
+        os.kill(os.getpid(), signal.SIGTERM)  # kill ourselves as well
+        return fastapi.Response(status_code=200, content="Server shutting down...")
+
+    async def shutdown_cleanup(self):
+        """Cleanup the server.
+
+        Override this method in subclasses to shut down any additional resources (e.g. db connections) as necessary."""
+        try:
+            self.logger.debug(f"Successfully released resources for Server {self.id}.")
+        except Exception as e:
+            self.logger.warning(f"Server did not shut down properly: {e}")
+
+    @classmethod
+    def default_url(cls) -> Url:
+        """Get the default URL for this server type from config.
+
+        Priority:
+
+        1. Server-specific URL from config
+        2. Default ServerBase URL from config
+        3. Fallback to localhost:8000
+        """
+        default_urls = cls.config["MINDTRACE_DEFAULT_HOST_URLS"]
+        server_url = default_urls.get(cls.__name__) or default_urls.get("ServerBase", "http://localhost:8000")
+        return parse_url(server_url)
+
+    @classmethod
+    def build_url(cls, url: str | Url | None = None, host: str | None = None, port: int | None = None) -> Url:
+        """Build a URL with consistent priority logic.
+
+        Priority:
+
+        1. Explicit URL parameter
+        2. Host/port parameters
+        3. Default URL from config
+
+        Args:
+            url: Full URL string or Url object
+            host: Host address (e.g. "localhost" or "192.168.1.100")
+            port: Port number
+
+        Returns:
+            Parsed URL object
+        """
+        if url is not None:
+            if isinstance(url, str):
+                url = url + "/" if not url.endswith("/") else url
+            return parse_url(url) if isinstance(url, str) else url
+
+        if host is not None or port is not None:
+            default_url = cls.default_url()
+            final_host = host or default_url.host
+            final_port = port or default_url.port
+            return parse_url(f"http://{final_host}:{final_port}/")
+
+        return cls.default_url()
+
+    @classmethod
+    def register_connection_manager(cls, connection_manager: Type[ConnectionManager]):
+        """Register a connection manager for this server."""
+        cls._client_interface = connection_manager
+
+    @classmethod
+    def default_log_file(cls) -> str:
+        """Get the default log file for this server type."""
+        return os.path.join(cls.config["MINDTRACE_DEFAULT_LOG_DIR"], f"{cls.__name__}_logs.txt")
+
+    def add_endpoint(
+        self,
+        path,
+        func,
+        schema: TaskSchema,
+        api_route_kwargs=None,
+        autolog_kwargs=None,
+        methods: list[str] | None = None,
+        scope: str = "public",
+    ):
+        """Register a new endpoint with optional role."""
+        path = path.removeprefix("/")
+        api_route_kwargs = ifnone(api_route_kwargs, default={})
+        autolog_kwargs = ifnone(autolog_kwargs, default={})
+
+        self._endpoints[path] = schema
+        self.app.add_api_route(
+            "/" + path,
+            endpoint=Mindtrace.autolog(self=self, **autolog_kwargs)(func),
+            methods=ifnone(methods, default=["POST"]),
+            **api_route_kwargs,
+        )

mindtrace_services-0.1.0/mindtrace/services/core/types.py

@@ -0,0 +1,104 @@
+import json
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Type
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from mindtrace.core import TaskSchema
+
+
+class ServerStatus(Enum):
+    DOWN = "Down"
+    LAUNCHING = "Launching"
+    FAILED_TO_LAUNCH = "FailedToLaunch"
+    AVAILABLE = "Available"
+    STOPPING = "Stopping"
+
+
+@dataclass
+class Heartbeat:
+    """Heartbeat status of a server.
+
+    Attributes:
+        status: The current status of the server.
+        server_id: The unique identifier of the server.
+        message: Human-readable message describing the status of the server.
+        details: Additional details about the server status. Individual server subclasses may define their own specific
+            protocol for this field (though always a dict). A GatewayServer, for instance, will return a
+            dict[UUID, Heartbeat], containing the Heartbeats of all connected services, keyed by their unique server
+            IDs.
+    """
+
+    status: ServerStatus = ServerStatus.DOWN
+    server_id: UUID | None = None
+    message: str | None = None
+    details: Any = None
+
+    def __str__(self):
+        if isinstance(self.details, dict):
+            return (
+                f"Server ID: {self.server_id}\n"
+                f"Status: {self.status}\n"
+                f"Message: {self.message}\n"
+                f"Details: {json.dumps(self.details, indent=4)}"
+            )
+        else:
+            return (
+                f"Server ID: {self.server_id}\nStatus: {self.status}\nMessage: {self.message}\nDetails: {self.details}"
+            )
+
+
+class EndpointsOutput(BaseModel):
+    endpoints: list[str]
+
+
+class EndpointsSchema(TaskSchema):
+    name: str = "endpoints"
+    output_schema: Type[EndpointsOutput] = EndpointsOutput
+
+
+class StatusOutput(BaseModel):
+    status: ServerStatus
+
+
+class StatusSchema(TaskSchema):
+    name: str = "status"
+    output_schema: Type[StatusOutput] = StatusOutput
+
+
+class HeartbeatOutput(BaseModel):
+    heartbeat: Heartbeat
+
+
+class HeartbeatSchema(TaskSchema):
+    name: str = "heartbeat"
+    output_schema: Type[HeartbeatOutput] = HeartbeatOutput
+
+
+class ServerIDOutput(BaseModel):
+    server_id: UUID
+
+
+class ServerIDSchema(TaskSchema):
+    name: str = "server_id"
+    output_schema: Type[ServerIDOutput] = ServerIDOutput
+
+
+class PIDFileOutput(BaseModel):
+    pid_file: str
+
+
+class PIDFileSchema(TaskSchema):
+    name: str = "pid_file"
+    output_schema: Type[PIDFileOutput] = PIDFileOutput
+
+
+class ShutdownOutput(BaseModel):
+    shutdown: bool
+
+
+class ShutdownSchema(TaskSchema):
+    name: str = "shutdown"
+    output_schema: Type[ShutdownOutput] = ShutdownOutput

mindtrace_services-0.1.0/mindtrace/services/core/utils.py

@@ -0,0 +1,187 @@
+from typing import TYPE_CHECKING, Optional, Type
+
+import httpx
+from fastapi import HTTPException
+
+if TYPE_CHECKING:  # pragma: no cover
+    from mindtrace.services import Service
+from mindtrace.core import Mindtrace
+from mindtrace.services.core.connection_manager import ConnectionManager
+
+
+def add_endpoint(app, path, self: Optional["Service"], **kwargs):
+    """Register a new endpoint.
+
+    This decorator method is functionally identical as calling add_endpoint on a Service instance. It is useful when
+    the endpoints are defined in a separate method, such as grouping api routes in a more complicated FastAPI app.
+
+    Args:
+        app: The FastAPI app.
+        path: The endpoint path.
+        self: The server instance.
+        **kwargs: Additional arguments to pass when creating the FastAPI route.
+
+    Example::
+
+        from fastapi import FastAPI
+        from mindtrace.services import Service
+
+        class MyServer(Service):
+            def __init__(self):
+                super().__init__()
+
+                self.add_endpoint(path="/status_using_method", func=self.status)
+                self.create_app()
+
+            def status(self):
+                return {"status": "Available"}
+
+            def create_app():
+                # May put all the endpoints in a single method, and call the method in __init__.
+
+                @add_endpoint(self.app, "/status_using_decorator", self=self)
+                def status():
+                    return {"status": "Available"}
+
+                @add_endpoint(self.app, "/another_hundred_endpoints", self=self)
+                def another_hundred_endpoints():
+                    return
+
+
+    """
+    self._endpoints.append(path.removeprefix("/"))
+
+    def wrapper(func):
+        app.add_api_route(f"/{path}", endpoint=Mindtrace.autolog(self=self)(func), methods=["POST"], **kwargs)
+
+    return wrapper
+
+
+def register_connection_manager(connection_manager: Type["ConnectionManager"]):
+    """Register a connection manager for a server class.
+
+    This decorator is used to register a connection manager for a server class. The connection manager is used to
+    communicate with the server. The connection manager must be a subclass of ConnectionManager.
+
+    Args:
+        connection_manager: The connection manager class.
+
+    Example::
+
+        import requests
+        from mindtrace.services import ConnectionManager, Service
+
+        class MyConnectionManager(ConnectionManager):
+            def __init__(self, url):
+                super().__init__(url)
+
+            def add(arg1, arg2):
+                response = requests.request("POST", str(self.url) + "add", json={"arg1": arg1, "arg2": arg2})
+                return json.loads(response.content)["sum"]
+
+        @register_connection_manager(MyConnectionManager)
+        class MyService(Service):
+            def __init__(self):
+                super().__init__()
+                self.add_endpoint("add", self.add)
+
+            def add(self, arg1, arg2):
+                return {"sum": arg1 + arg2}
+
+        cm = MyService.launch()  # Returns a MyConnectionManager instance, NOT a MyServer instance
+        sum = cm.add(1, 2)  # Calls add method in MyConnectionManager
+
+    """
+
+    def wrapper(server_class):
+        server_class._client_interface = connection_manager
+        return server_class
+
+    return wrapper
+
+
+def generate_connection_manager(
+    service_cls, protected_methods: list[str] = ["shutdown", "ashutdown", "status", "astatus"]
+):
+    """Generates a dedicated ConnectionManager class with one method per endpoint.
+
+    Args:
+        service_cls: The service class to generate a connection manager for.
+        protected_methods: A list of methods that should not be overridden by dynamic methods.
+
+    Returns:
+        A ConnectionManager class with one method per endpoint.
+    """
+
+    class_name = f"{service_cls.__name__}ConnectionManager"
+
+    class ServiceConnectionManager(ConnectionManager):
+        pass  # Methods will be added dynamically
+
+    # Create a temporary service instance to get the endpoints
+    temp_service = service_cls()
+
+    # Dynamically define one method per endpoint
+    for endpoint_name, endpoint in temp_service._endpoints.items():
+        # Skip if this would override an existing method in ConnectionManager
+        if endpoint_name in protected_methods:
+            continue
+
+        endpoint_path = f"/{endpoint_name}"
+
+        def make_method(endpoint_path, input_schema, output_schema):
+            def method(self, validate_input: bool = True, validate_output: bool = True, **kwargs):
+                if validate_input:
+                    payload = input_schema(**kwargs).model_dump() if input_schema is not None else {}
+                else:
+                    payload = kwargs
+                res = httpx.post(str(self.url).rstrip("/") + endpoint_path, json=payload, timeout=30)
+                if res.status_code != 200:
+                    raise HTTPException(res.status_code, res.text)
+
+                # Handle empty responses (e.g., from shutdown endpoint)
+                try:
+                    result = res.json()
+                except Exception:
+                    result = {"success": True}  # Default response for empty content
+
+                if not validate_output:
+                    return result  # raw result dict
+                return output_schema(**result) if output_schema is not None else result
+
+            async def amethod(self, validate_input: bool = True, validate_output: bool = True, **kwargs):
+                if validate_input:
+                    payload = input_schema(**kwargs).model_dump() if input_schema is not None else {}
+                else:
+                    payload = kwargs
+                async with httpx.AsyncClient(timeout=30) as client:
+                    res = await client.post(str(self.url).rstrip("/") + endpoint_path, json=payload, timeout=30)
+                if res.status_code != 200:
+                    raise HTTPException(res.status_code, res.text)
+
+                # Handle empty responses (e.g., from shutdown endpoint)
+                try:
+                    result = res.json()
+                except Exception:
+                    result = {"success": True}  # Default response for empty content
+
+                if not validate_output:
+                    return result  # raw result dict
+                return output_schema(**result) if output_schema is not None else result
+
+            return method, amethod
+
+        method, amethod = make_method(endpoint_path, endpoint.input_schema, endpoint.output_schema)
+
+        # Set up sync method
+        method.__name__ = endpoint_name
+        method.__doc__ = f"Calls the `{endpoint_name}` pipeline at `{endpoint_path}`"
+        setattr(ServiceConnectionManager, endpoint_name, method)
+
+        # Set up async method
+        amethod.__name__ = f"a{endpoint_name}"
+        amethod.__doc__ = f"Async version: Calls the `{endpoint_name}` pipeline at `{endpoint_path}`"
+        setattr(ServiceConnectionManager, f"a{endpoint_name}", amethod)
+
+    ServiceConnectionManager.__name__ = class_name
+    return ServiceConnectionManager

mindtrace_services-0.1.0/mindtrace/services/sample/echo_service.py

@@ -0,0 +1,35 @@
+import time
+
+from pydantic import BaseModel
+
+from mindtrace.core import TaskSchema
+from mindtrace.services import Service
+
+
+class EchoInput(BaseModel):
+    message: str
+    delay: float = 0.0
+
+
+class EchoOutput(BaseModel):
+    echoed: str
+
+
+class EchoTaskSchema(TaskSchema):
+    name: str = "echo"
+    input_schema: type[EchoInput] = EchoInput
+    output_schema: type[EchoOutput] = EchoOutput
+
+
+echo_task = EchoTaskSchema()
+
+
+class EchoService(Service):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.add_endpoint("echo", self.echo, schema=echo_task)
+
+    def echo(self, payload: EchoInput) -> EchoOutput:
+        if payload.delay > 0:
+            time.sleep(payload.delay)
+        return EchoOutput(echoed=payload.message)

mindtrace_services-0.1.0/mindtrace_services.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: mindtrace-services
+Version: 0.1.0
+Summary: Service layer for Mindtrace
+Author: Mindtrace Team
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE
+Requires-Dist: gunicorn>=23.0.0
+Requires-Dist: mindtrace-core
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: uvicorn>=0.34.3
+Dynamic: license-file

mindtrace_services-0.1.0/mindtrace_services.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+pyproject.toml
+mindtrace/services/__init__.py
+mindtrace/services/core/__init__.py
+mindtrace/services/core/connection_manager.py
+mindtrace/services/core/launcher.py
+mindtrace/services/core/service.py
+mindtrace/services/core/types.py
+mindtrace/services/core/utils.py
+mindtrace/services/sample/echo_service.py
+mindtrace_services.egg-info/PKG-INFO
+mindtrace_services.egg-info/SOURCES.txt
+mindtrace_services.egg-info/dependency_links.txt
+mindtrace_services.egg-info/requires.txt
+mindtrace_services.egg-info/top_level.txt

mindtrace_services-0.1.0/mindtrace_services.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mindtrace_services-0.1.0/mindtrace_services.egg-info/requires.txt

@@ -0,0 +1,4 @@
+gunicorn>=23.0.0
+mindtrace-core
+structlog>=24.4.0
+uvicorn>=0.34.3

mindtrace_services-0.1.0/mindtrace_services.egg-info/top_level.txt

@@ -0,0 +1 @@
+mindtrace

mindtrace_services-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mindtrace-services"
+version = "0.1.0"
+description = "Service layer for Mindtrace"
+license = "Apache-2.0"
+authors = [
+    {name = "Mindtrace Team"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "gunicorn>=23.0.0",
+    "mindtrace-core",
+    "structlog>=24.4.0",
+    "uvicorn>=0.34.3",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

mindtrace_services-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+