UncountablePythonSDK 0.0.186__tar.gz → 0.0.187__tar.gz

{uncountablepythonsdk-0.0.186/UncountablePythonSDK.egg-info → uncountablepythonsdk-0.0.187}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UncountablePythonSDK
-Version: 0.0.186
+Version: 0.0.187
 Summary: Uncountable SDK
 Project-URL: Homepage, https://github.com/uncountableinc/uncountable-python-sdk
 Project-URL: Repository, https://github.com/uncountableinc/uncountable-python-sdk.git

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187/UncountablePythonSDK.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UncountablePythonSDK
-Version: 0.0.186
+Version: 0.0.187
 Summary: Uncountable SDK
 Project-URL: Homepage, https://github.com/uncountableinc/uncountable-python-sdk
 Project-URL: Repository, https://github.com/uncountableinc/uncountable-python-sdk.git

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/UncountablePythonSDK.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ examples/integration-server/jobs/materials_auto/example_instrument.py
 examples/integration-server/jobs/materials_auto/example_parse.py
 examples/integration-server/jobs/materials_auto/example_predictions.py
 examples/integration-server/jobs/materials_auto/example_runsheet_wh.py
+examples/integration-server/jobs/materials_auto/example_scale_connection.py
 examples/integration-server/jobs/materials_auto/example_wh.py
 examples/integration-server/jobs/materials_auto/profile.yaml
 pkgs/__init__.py
@@ -151,6 +152,8 @@ uncountable/integration/request_context.py
 uncountable/integration/scan_profiles.py
 uncountable/integration/scheduler.py
 uncountable/integration/server.py
+uncountable/integration/service.py
+uncountable/integration/service_runner.py
 uncountable/integration/telemetry.py
 uncountable/integration/webhook_bootstrap.py
 uncountable/integration/webhook_entity.py

uncountablepythonsdk-0.0.187/examples/integration-server/jobs/materials_auto/example_scale_connection.py

@@ -0,0 +1,150 @@
+import asyncio
+import json
+import random
+from dataclasses import dataclass
+from decimal import Decimal
+
+from uncountable.core.client import Client
+from uncountable.integration.service import Service, ServiceArguments, register_service
+from uncountable.types import entity_t, identifier_t, listing_t, sockets_t
+from uncountable.types.base_t import ObjectId
+from uncountable.types.integration_session_t import IntegrationSessionInstrument
+from websockets.asyncio.client import connect
+
+from pkgs.serialization_util import serialize_for_api
+
+SCALE_EQUIPMENT_NAMES = [
+    "Instrument Scale One",
+    "Instrument Scale Two",
+    "Instrument Scale Three",
+]
+EQUIPMENT_ID_COLUMN_REF_NAME = "id"
+EQUIPMENT_NAME_COLUMN_REF_NAME = "name"
+SOCKET_URL = "ws://host.docker.internal:8765"
+READING_INTERVAL_SECONDS = 1.0
+
+
+@dataclass(kw_only=True)
+class InstrumentRoom:
+    equipment_name: str
+    token: str
+    room_key: str
+
+
+@dataclass(kw_only=True)
+class InstrumentReading:
+    equipment_name: str
+    value: Decimal
+
+
+def _build_equipment_column(ref_name: str) -> listing_t.ColumnIdentifierEntityRefName:
+    return listing_t.ColumnIdentifierEntityRefName(
+        entity_type=entity_t.EntityType.EQUIPMENT, ref_name=ref_name
+    )
+
+
+def _resolve_equipment_id(*, client: Client, equipment_name: str) -> ObjectId:
+    id_column = _build_equipment_column(EQUIPMENT_ID_COLUMN_REF_NAME)
+    name_column = _build_equipment_column(EQUIPMENT_NAME_COLUMN_REF_NAME)
+    results = client.fetch_listing(
+        entity_type=entity_t.EntityType.EQUIPMENT,
+        columns=[id_column],
+        filters=listing_t.FilterNodeColumnAnd(
+            filters=(
+                listing_t.FilterSpecEquals(
+                    relation=listing_t.FilterRelation.EQUALS,
+                    column=name_column,
+                    value=equipment_name,
+                ),
+            )
+        ),
+    ).results
+    if len(results) != 1:
+        raise Exception(
+            f"expected exactly one equipment named {equipment_name}, found {len(results)}"
+        )
+    equipment_id = results[0].column_values[0]
+    if not isinstance(equipment_id, int):
+        raise Exception(
+            f"expected an integer id for equipment named {equipment_name}, found {equipment_id!r}"
+        )
+    return ObjectId(equipment_id)
+
+
+@register_service
+class ScaleConnectionService(Service):
+    def run(self, args: ServiceArguments) -> None:
+        rooms = [
+            self._register_room(args=args, equipment_name=equipment_name)
+            for equipment_name in SCALE_EQUIPMENT_NAMES
+        ]
+        asyncio.run(self._stream_readings(args=args, rooms=rooms))
+
+    def _register_room(
+        self, *, args: ServiceArguments, equipment_name: str
+    ) -> InstrumentRoom:
+        equipment_id = _resolve_equipment_id(
+            client=args.client, equipment_name=equipment_name
+        )
+        registration = args.client.register_sockets_token(
+            socket_request=sockets_t.SocketRequestIntegrationSession(
+                integration_session=IntegrationSessionInstrument(
+                    equipment_key=identifier_t.IdentifierKeyId(id=equipment_id)
+                )
+            )
+        ).response
+        return InstrumentRoom(
+            equipment_name=equipment_name,
+            token=registration.token,
+            room_key=registration.room_key,
+        )
+
+    async def _stream_readings(
+        self, *, args: ServiceArguments, rooms: list[InstrumentRoom]
+    ) -> None:
+        rooms_by_name = {room.equipment_name: room for room in rooms}
+        async with connect(
+            SOCKET_URL, additional_headers={"X-UNC-EXTERNAL": "true"}
+        ) as ws:
+            for room in rooms:
+                await ws.send(
+                    json.dumps(
+                        serialize_for_api(
+                            sockets_t.JoinRoomWithTokenSocketClientMessage(
+                                token=room.token
+                            )
+                        )
+                    )
+                )
+                args.logger.log_info(f"Joined room for instrument {room.equipment_name}")
+
+            readings: asyncio.Queue[InstrumentReading] = asyncio.Queue()
+            emit_task = asyncio.create_task(
+                self._emit_readings(rooms=rooms, readings=readings)
+            )
+            try:
+                while True:
+                    reading = await readings.get()
+                    room = rooms_by_name[reading.equipment_name]
+                    await ws.send(
+                        json.dumps(
+                            serialize_for_api(
+                                sockets_t.SendInstrumentReadingClientMessage(
+                                    value=reading.value, room_key=room.room_key
+                                )
+                            )
+                        )
+                    )
+            finally:
+                emit_task.cancel()
+
+    async def _emit_readings(
+        self, *, rooms: list[InstrumentRoom], readings: asyncio.Queue[InstrumentReading]
+    ) -> None:
+        while True:
+            room = random.choice(rooms)
+            value = Decimal(str(round(random.uniform(0, 500), 2)))
+            await readings.put(
+                InstrumentReading(equipment_name=room.equipment_name, value=value)
+            )
+            await asyncio.sleep(READING_INTERVAL_SECONDS)

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/examples/integration-server/jobs/materials_auto/profile.yaml

@@ -117,3 +117,8 @@ jobs:
     executor:
       type: script
       import_path: example_parse
+services:
+  - id: example_scale_connection
+    name: Example Scale Connection
+    import_path: example_scale_connection
+    enabled: true

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/pkgs/argument_parser/parser_inner.py

@@ -5,6 +5,7 @@ import datetime
 import math
 import types
 import typing
+from collections.abc import Mapping
 from datetime import date
 from decimal import Decimal
 from enum import Enum
@@ -140,18 +141,32 @@ def _build_parser_discriminated_union(
         else discriminator_raw
     )
 
+    accepted = ", ".join(sorted(discriminator_map))
+
     def parse(value: typing.Any) -> typing.Any:
         if context.options.allow_direct_type and dataclasses.is_dataclass(value):
             discriminant = getattr(value, discriminator)
-        else:
+        elif isinstance(value, Mapping):
             discriminant = value.get(discriminator)
+        else:
+            raise ParserError(
+                f"expected-object-for-union; found {type(value).__name__} where an "
+                f"object with {discriminator} set to one of: {accepted} was expected",
+                value=value,
+            )
         if discriminant is None:
-            raise ParserError("missing-union-discriminant")
+            raise ParserError(
+                f"missing-union-discriminant; set {discriminator} to one of: {accepted}"
+            )
         if not isinstance(discriminant, str):
             raise ParserError("union-discriminant-is-not-string", value=discriminant)
         parser = discriminator_map.get(discriminant)
         if parser is None:
-            raise ParserError("missing-type-for-union-discriminant", value=discriminant)
+            raise ParserError(
+                f"missing-type-for-union-discriminant; {discriminator} must be one of: "
+                f"{accepted}",
+                value=discriminant,
+            )
         return parser(value)
 
     return parse

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/pkgs/type_spec/non_discriminated_union_exceptions.py

@@ -2,8 +2,6 @@ NON_DISCRIMINATED_UNION_EXCEPTIONS = [
     "audit_log.AuditLogDataValues",
     "generate_tool_parameters.UnionWithoutDiscrim",
     "output_calculation_entities.ConditionParameterFilterCondition",
-    "output_parameters.AnalyticalMethodParameterOptions",
-    "output_parameters.AnalyticalMethodLinkedOptionValue",
     "recipes_redirect.RecipesRedirectResult",
     "value_spec.ResolvedPathAll",
     "deprecated_calculation_types.DeprecatedWeightedSumEntitiesV0",

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/uncountable/integration/scan_profiles.py

@@ -21,7 +21,7 @@ def load_profiles() -> list[job_definition_t.ProfileMetadata]:
         if entry.is_dir() and entry.name not in _IGNORED_PROFILE_FOLDERS
     ]
     profile_details: list[job_definition_t.ProfileMetadata] = []
-    seen_job_ids: set[str] = set()
+    seen_ids: set[str] = set()
     for profile_file in profiles:
         profile_name = profile_file.name
         try:
@@ -30,9 +30,14 @@ def load_profiles() -> list[job_definition_t.ProfileMetadata]:
                 resource="profile.yaml",
             )
             for job in definition.jobs:
-                if job.id in seen_job_ids:
-                    raise Exception(f"multiple jobs with id {job.id}")
-                seen_job_ids.add(job.id)
+                if job.id in seen_ids:
+                    raise Exception(f"multiple jobs or services with id {job.id}")
+                seen_ids.add(job.id)
+            services = definition.services if definition.services is not None else []
+            for service in services:
+                if service.id in seen_ids:
+                    raise Exception(f"multiple jobs or services with id {service.id}")
+                seen_ids.add(service.id)
 
             if definition.environments is not None:
                 for integration_env in integration_envs:
@@ -42,6 +47,7 @@ def load_profiles() -> list[job_definition_t.ProfileMetadata]:
                             job_definition_t.ProfileMetadata(
                                 name=profile_name,
                                 jobs=definition.jobs,
+                                services=services,
                                 base_url=environment_config.base_url,
                                 integration_server_base_url=environment_config.integration_server_base_url,
                                 app_base_url=environment_config.app_base_url,
@@ -58,6 +64,7 @@ def load_profiles() -> list[job_definition_t.ProfileMetadata]:
                     job_definition_t.ProfileMetadata(
                         name=profile_name,
                         jobs=definition.jobs,
+                        services=services,
                         base_url=definition.base_url,
                         integration_server_base_url=definition.integration_server_base_url,
                         app_base_url=definition.app_base_url,

{uncountablepythonsdk-0.0.186 → uncountablepythonsdk-0.0.187}/uncountable/integration/scheduler.py

@@ -19,6 +19,12 @@ from uncountable.integration.queue_runner.command_server import (
 )
 from uncountable.integration.queue_runner.queue_runner import start_queue_runner
 from uncountable.integration.queue_runner.types import RESTART_EXIT_CODE
+from uncountable.integration.scan_profiles import load_profiles
+from uncountable.integration.service_runner import (
+    ServiceToStart,
+    run_service,
+    select_enabled_services,
+)
 from uncountable.integration.telemetry import Logger
 
 SHUTDOWN_TIMEOUT_SECS = 30
@@ -32,9 +38,30 @@ class ProcessName(StrEnum):
     UWSGI = "uwsgi"
 
 
+@dataclass(frozen=True, kw_only=True)
+class CoreProcessKey:
+    name: ProcessName
+
+    @property
+    def label(self) -> str:
+        return self.name
+
+
+@dataclass(frozen=True, kw_only=True)
+class ServiceProcessKey:
+    service_id: str
+
+    @property
+    def label(self) -> str:
+        return f"service:{self.service_id}"
+
+
+ProcessKey = CoreProcessKey | ServiceProcessKey
+
+
 @dataclass(kw_only=True)
 class ProcessInfo:
-    name: ProcessName
+    key: ProcessKey
     process: AnyProcess
 
     @property
@@ -77,16 +104,17 @@ def _wait_for_process(
     start = time.time()
     while time.time() - start < timeout_secs:
         if not proc_info.is_alive:
-            logger.log_debug(f"{proc_info.name} shut down successfully")
+            logger.log_debug(f"{proc_info.key.label} shut down successfully")
             return True
         time.sleep(1)
     return False
 
 
-def handle_shutdown(logger: Logger, processes: dict[ProcessName, ProcessInfo]) -> None:
+def handle_shutdown(logger: Logger, processes: dict[ProcessKey, ProcessInfo]) -> None:
     logger.log_debug("received shutdown command, shutting down sub-processes")
 
-    cron = processes.get(ProcessName.CRON_SERVER)
+    cron_key = CoreProcessKey(name=ProcessName.CRON_SERVER)
+    cron = processes.get(cron_key)
     if cron is not None and cron.is_alive:
         logger.log_debug("stopping cron_server first to prevent new job submissions")
         cron.process.terminate()
@@ -94,7 +122,7 @@ def handle_shutdown(logger: Logger, processes: dict[ProcessName, ProcessInfo]) -
             logger.log_warning("cron_server did not stop in time, killing")
             cron.process.kill()
 
-    remaining = [p for name, p in processes.items() if name != ProcessName.CRON_SERVER]
+    remaining = [p for key, p in processes.items() if key != cron_key]
     for proc_info in remaining:
         if proc_info.is_alive:
             proc_info.process.terminate()
@@ -106,70 +134,62 @@ def handle_shutdown(logger: Logger, processes: dict[ProcessName, ProcessInfo]) -
     ):
         logger.log_debug(
             "waiting for sub-processes to shut down",
-            attributes={"still_living_processes": [p.name for p in still_living]},
+            attributes={"still_living_processes": [p.key.label for p in still_living]},
         )
         still_living = [p for p in still_living if p.is_alive]
         time.sleep(1)
 
     for proc_info in still_living:
         logger.log_warning(
-            f"{proc_info.name} failed to shut down after {SHUTDOWN_TIMEOUT_SECS} seconds, forcefully terminating"
+            f"{proc_info.key.label} failed to shut down after {SHUTDOWN_TIMEOUT_SECS} seconds, forcefully terminating"
         )
         proc_info.process.kill()
 
 
-def restart_process(
-    logger: Logger, proc_info: ProcessInfo, processes: dict[ProcessName, ProcessInfo]
-) -> None:
-    logger.log_error(
-        f"process {proc_info.name} shut down unexpectedly - exit code {proc_info.exitcode}. Restarting..."
-    )
-
-    match proc_info.name:
-        case ProcessName.QUEUE_RUNNER:
-            queue_proc = multiprocessing.Process(target=start_queue_runner)
-            queue_proc.start()
-            new_info = ProcessInfo(name=ProcessName.QUEUE_RUNNER, process=queue_proc)
-            processes[ProcessName.QUEUE_RUNNER] = new_info
-            try:
-                _wait_queue_runner_online()
-                logger.log_debug("queue runner restarted successfully")
-            except Exception as e:
-                logger.log_exception(e)
-                logger.log_error(
-                    "queue runner failed to restart, shutting down scheduler"
-                )
-                handle_shutdown(logger, processes)
-                sys.exit(1)
+class DeadProcessOutcome(StrEnum):
+    RESTART_REQUESTED = "restart_requested"
+    RESTART_AFTER_CRASH = "restart_after_crash"
+    SHUTDOWN_ALL = "shutdown_all"
 
-        case ProcessName.CRON_SERVER:
-            cron_proc = multiprocessing.Process(target=cron_target)
-            cron_proc.start()
-            new_info = ProcessInfo(name=ProcessName.CRON_SERVER, process=cron_proc)
-            processes[ProcessName.CRON_SERVER] = new_info
-            logger.log_debug("cron server restarted successfully")
 
-        case ProcessName.UWSGI:
-            uwsgi_proc: AnyProcess = subprocess.Popen(["uwsgi", "--die-on-term"])
-            new_info = ProcessInfo(name=ProcessName.UWSGI, process=uwsgi_proc)
-            processes[ProcessName.UWSGI] = new_info
-            logger.log_debug("uwsgi restarted successfully")
+def classify_dead_process(key: ProcessKey, exitcode: int | None) -> DeadProcessOutcome:
+    if exitcode == RESTART_EXIT_CODE:
+        return DeadProcessOutcome.RESTART_REQUESTED
+    match key:
+        case ServiceProcessKey():
+            return DeadProcessOutcome.RESTART_AFTER_CRASH
+        case CoreProcessKey():
+            return DeadProcessOutcome.SHUTDOWN_ALL
+        case _:
+            assert_never(key)
 
 
 def check_process_alarms(
-    logger: Logger, processes: dict[ProcessName, ProcessInfo]
+    logger: Logger, processes: dict[ProcessKey, ProcessInfo]
 ) -> ProcessAlarm | None:
     for proc_info in processes.values():
-        if not proc_info.is_alive:
-            if proc_info.exitcode == RESTART_EXIT_CODE:
+        if proc_info.is_alive:
+            continue
+        outcome = classify_dead_process(proc_info.key, proc_info.exitcode)
+        match outcome:
+            case DeadProcessOutcome.RESTART_REQUESTED:
                 logger.log_warning(
-                    f"process {proc_info.name} requested restart! restarting"
+                    f"process {proc_info.key.label} requested restart! restarting"
                 )
-                return ProcessAlarmRestart(process=proc_info)
-            logger.log_error(
-                f"process {proc_info.name} shut down unexpectedly! shutting down scheduler; exit code is {proc_info.exitcode}"
-            )
-            return ProcessAlarmShutdownAll()
+            case DeadProcessOutcome.RESTART_AFTER_CRASH:
+                logger.log_error(
+                    f"process {proc_info.key.label} exited unexpectedly with exit "
+                    f"code {proc_info.exitcode}; cleaning up and restarting"
+                )
+            case DeadProcessOutcome.SHUTDOWN_ALL:
+                logger.log_error(
+                    f"process {proc_info.key.label} shut down unexpectedly! shutting "
+                    f"down scheduler; exit code is {proc_info.exitcode}"
+                )
+                return ProcessAlarmShutdownAll()
+            case _:
+                assert_never(outcome)
+        return ProcessAlarmRestart(process=proc_info)
     return None
 
 
@@ -194,20 +214,20 @@ def _wait_queue_runner_online() -> None:
 
 def main() -> None:
     logger = Logger(get_current_span())
-    processes: dict[ProcessName, ProcessInfo] = {}
+    processes: dict[ProcessKey, ProcessInfo] = {}
 
     multiprocessing.set_start_method("forkserver")
 
     def add_process(process: ProcessInfo) -> None:
-        processes[process.name] = process
-        logger.log_debug(f"started process {process.name}")
+        processes[process.key] = process
+        logger.log_debug(f"started process {process.key.label}")
 
     def _start_queue_runner() -> None:
         runner_process = multiprocessing.Process(target=start_queue_runner)
         runner_process.start()
         add_process(
             ProcessInfo(
-                name=ProcessName.QUEUE_RUNNER,
+                key=CoreProcessKey(name=ProcessName.QUEUE_RUNNER),
                 process=runner_process,
             )
         )
@@ -219,17 +239,46 @@ def main() -> None:
             handle_shutdown(logger, processes=processes)
             return
 
+    def _start_service(service_to_start: ServiceToStart) -> None:
+        service_process = multiprocessing.Process(
+            target=run_service,
+            kwargs={
+                "service": service_to_start.service,
+                "profile_metadata": service_to_start.profile_metadata,
+            },
+        )
+        service_process.start()
+        add_process(
+            ProcessInfo(
+                key=ServiceProcessKey(service_id=service_to_start.service.id),
+                process=service_process,
+            )
+        )
+
     _start_queue_runner()
 
     cron_process = multiprocessing.Process(target=cron_target)
     cron_process.start()
-    add_process(ProcessInfo(name=ProcessName.CRON_SERVER, process=cron_process))
+    add_process(
+        ProcessInfo(
+            key=CoreProcessKey(name=ProcessName.CRON_SERVER), process=cron_process
+        )
+    )
 
     uwsgi_process = subprocess.Popen([
         "uwsgi",
         "--die-on-term",
     ])
-    add_process(ProcessInfo(name=ProcessName.UWSGI, process=uwsgi_process))
+    add_process(
+        ProcessInfo(key=CoreProcessKey(name=ProcessName.UWSGI), process=uwsgi_process)
+    )
+
+    services_by_id: dict[str, ServiceToStart] = {
+        service_to_start.service.id: service_to_start
+        for service_to_start in select_enabled_services(load_profiles())
+    }
+    for service_to_start in services_by_id.values():
+        _start_service(service_to_start)
 
     shutdown_requested = False
 
@@ -244,16 +293,25 @@ def main() -> None:
             process_alarm = check_process_alarms(logger, processes=processes)
             match process_alarm:
                 case ProcessAlarmRestart():
-                    match process_alarm.process.name:
-                        case ProcessName.QUEUE_RUNNER:
-                            del processes[ProcessName.QUEUE_RUNNER]
-                            _start_queue_runner()
-                        case ProcessName.CRON_SERVER | ProcessName.UWSGI:
-                            raise NotImplementedError(
-                                f"restarting {process_alarm.process.name} not yet implemented"
-                            )
+                    match process_alarm.process.key:
+                        case CoreProcessKey() as core_key:
+                            match core_key.name:
+                                case ProcessName.QUEUE_RUNNER:
+                                    del processes[
+                                        CoreProcessKey(name=ProcessName.QUEUE_RUNNER)
+                                    ]
+                                    _start_queue_runner()
+                                case ProcessName.CRON_SERVER | ProcessName.UWSGI:
+                                    raise NotImplementedError(
+                                        f"restarting {core_key.label} not yet implemented"
+                                    )
+                                case _:
+                                    assert_never(core_key.name)
+                        case ServiceProcessKey() as service_key:
+                            del processes[service_key]
+                            _start_service(services_by_id[service_key.service_id])
                         case _:
-                            assert_never(process_alarm.process.name)
+                            assert_never(process_alarm.process.key)
                 case ProcessAlarmShutdownAll():
                     handle_shutdown(logger, processes)
                     sys.exit(1)

uncountablepythonsdk-0.0.187/uncountable/integration/service.py

@@ -0,0 +1,74 @@
+import importlib
+import inspect
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from uncountable.core.client import Client
+from uncountable.integration.telemetry import Logger
+from uncountable.types.job_definition_t import (
+    IntegrationService,
+    ProfileMetadata,
+)
+
+__all__ = [
+    "Service",
+    "ServiceArguments",
+    "register_service",
+    "resolve_service",
+    "resolve_service_class",
+]
+
+
+@dataclass(kw_only=True)
+class ServiceArguments:
+    service_definition: IntegrationService
+    profile_metadata: ProfileMetadata
+    client: Client
+    logger: Logger
+
+
+class Service(ABC):
+    _unc_service_registered: bool = False
+
+    @abstractmethod
+    def run(self, args: ServiceArguments) -> None: ...
+
+
+def register_service[ST: type[Service]](cls: ST) -> ST:
+    if not (isinstance(cls, type) and issubclass(cls, Service)):
+        raise TypeError(
+            f"@register_service can only be applied to Service subclasses, got {cls}"
+        )
+    cls._unc_service_registered = True
+    return cls
+
+
+def resolve_service_class(
+    service: IntegrationService, profile_metadata: ProfileMetadata
+) -> type[Service]:
+    service_module_path = ".".join([
+        os.environ["UNC_PROFILES_MODULE"],
+        profile_metadata.name,
+        service.import_path,
+    ])
+    service_module = importlib.import_module(service_module_path)
+    found_services: list[type[Service]] = []
+    for _, service_class in inspect.getmembers(service_module, inspect.isclass):
+        if (
+            service_class.__module__ == service_module.__name__
+            and getattr(service_class, "_unc_service_registered", False)
+            and issubclass(service_class, Service)
+        ):
+            found_services.append(service_class)
+    assert len(found_services) == 1, (
+        f"expected exactly one registered service class in {service.import_path}, found {len(found_services)}"
+    )
+    return found_services[0]
+
+
+def resolve_service(
+    service: IntegrationService, profile_metadata: ProfileMetadata
+) -> Service:
+    service_class = resolve_service_class(service, profile_metadata)
+    return service_class()