UncountablePythonSDK 0.0.126__py3-none-any.whl → 0.0.142.dev0__py3-none-any.whl

docs/requirements.txt

@@ -1,4 +1,4 @@
-furo==2025.7.19
+furo==2025.9.25
 myst-parser==4.0.1
 sphinx-autoapi==3.6.0
 sphinx-copybutton==0.5.2

examples/integration-server/jobs/materials_auto/example_cron.py

@@ -17,5 +17,5 @@ class MyCronJob(CronJob):
             if field_val.field_ref_name == "name":
                 name = field_val.value
         args.logger.log_info(f"material family found with name: {name}")
-        time.sleep(1.5)
+        time.sleep(20)
         return JobResult(success=True)

examples/integration-server/jobs/materials_auto/example_instrument.py

@@ -1,3 +1,4 @@
+import json
 import time
 from dataclasses import dataclass
 from decimal import Decimal
@@ -5,13 +6,16 @@ from decimal import Decimal
 from uncountable.integration.job import JobArguments, WebhookJob, register_job
 from uncountable.types import (
     base_t,
-    entity_t,
     identifier_t,
-    integrations_t,
     job_definition_t,
-    publish_realtime_data_t,
+    sockets_t,
 )
-from uncountable.types.client_base import APIRequest
+from uncountable.types.integration_session_t import IntegrationSessionInstrument
+from websockets.sync.client import connect
+from websockets.typing import Data
+
+from pkgs.argument_parser.argument_parser import CachedParser
+from pkgs.serialization_util import serialize_for_api
 
 
 @dataclass(kw_only=True)
@@ -24,45 +28,71 @@ class InstrumentExample(WebhookJob[InstrumentPayload]):
     def run(
         self, args: JobArguments, payload: InstrumentPayload
     ) -> job_definition_t.JobResult:
-        equipment_data = args.client.get_entities_data(
-            entity_type=entity_t.EntityType.EQUIPMENT,
-            entity_ids=[payload.equipment_id],
-        ).entity_details[0]
-
-        # Load the instrument's connection details from the entity
-        instrument_id = None
-        for field in equipment_data.field_values:
-            if field.field_ref_name == "ins_instrument_id":
-                instrument_id = field.value
-
-        if instrument_id is None:
-            args.logger.log_error("Could not find instrument ID")
-            return job_definition_t.JobResult(success=False)
+        parser: CachedParser[sockets_t.SocketResponse] = CachedParser(
+            sockets_t.SocketResponse  # type:ignore[arg-type]
+        )
 
-        args.logger.log_info(f"Instrument ID: {instrument_id}")
+        def parse_message(message: Data) -> sockets_t.SocketEventData | None:
+            try:
+                return parser.parse_api(json.loads(message)).data
+            except ValueError:
+                return None
 
-        for i in range(10):
-            req_args = publish_realtime_data_t.Arguments(
-                data_package=integrations_t.DataPackageNumericReading(
-                    value=Decimal(i * 15),
-                    target_entity=entity_t.EntityIdentifier(
-                        identifier_key=identifier_t.IdentifierKeyId(
-                            id=payload.equipment_id
-                        ),
-                        type=entity_t.EntityType.EQUIPMENT,
-                    ),
-                ),
+        integration_session = IntegrationSessionInstrument(
+            equipment_key=identifier_t.IdentifierKeyId(id=payload.equipment_id)
+        )
+        registration_info = args.client.register_sockets_token(
+            socket_request=sockets_t.SocketRequestIntegrationSession(
+                integration_session=integration_session
             )
-            api_request = APIRequest(
-                method=publish_realtime_data_t.ENDPOINT_METHOD,
-                endpoint=publish_realtime_data_t.ENDPOINT_PATH,
-                args=req_args,
-            )
-            args.client.do_request(
-                api_request=api_request, return_type=publish_realtime_data_t.Data
+        ).response
+        token = registration_info.token
+        room_key = registration_info.room_key
+        args.logger.log_info(f"Token: {token}")
+
+        with connect(
+            "ws://host.docker.internal:8765",
+            additional_headers={
+                "Authorization": f"Bearer {token}",
+                "X-UNC-EXTERNAL": "true",
+            },
+        ) as ws:
+            ws.send(
+                json.dumps(
+                    serialize_for_api(
+                        sockets_t.JoinRoomWithTokenSocketClientMessage(token=token)
+                    )
+                )
             )
-            time.sleep(0.75)
+            for i in range(10):
+                args.logger.log_info("Sending reading...")
+                ws.send(
+                    json.dumps(
+                        serialize_for_api(
+                            sockets_t.SendInstrumentReadingClientMessage(
+                                value=Decimal(i * 100), room_key=room_key
+                            )
+                        )
+                    )
+                )
+                time.sleep(0.75)
+
+            while True:
+                message = parse_message(ws.recv())
+                match message:
+                    case sockets_t.UsersInRoomUpdatedEventData():
+                        num_users = len(message.user_ids)
+                        if num_users <= 1:
+                            break
+                        else:
+                            args.logger.log_info(
+                                f"Session still open, {num_users} users in room."
+                            )
+                    case _:
+                        args.logger.log_info("Session still open...")
+                        continue
 
+        args.logger.log_info("Session closed.")
         return job_definition_t.JobResult(success=True)
 
     @property

examples/integration-server/jobs/materials_auto/example_parse.py

@@ -0,0 +1,140 @@
+from dataclasses import dataclass
+from decimal import Decimal
+
+from uncountable.integration.job import JobArguments, WebhookJob, register_job
+from uncountable.types import (
+    base_t,
+    entity_t,
+    generic_upload_t,
+    identifier_t,
+    job_definition_t,
+    notifications_t,
+    uploader_t,
+)
+
+
+@dataclass(kw_only=True)
+class ParsePayload:
+    async_job_id: base_t.ObjectId
+
+
+@register_job
+class ParseExample(WebhookJob[ParsePayload]):
+    def run(
+        self, args: JobArguments, payload: ParsePayload
+    ) -> job_definition_t.JobResult:
+        user_id: base_t.ObjectId | None = None
+        recipe_id: base_t.ObjectId | None = None
+        file_name: str | None = None
+        data = args.client.get_entities_data(
+            entity_ids=[payload.async_job_id], entity_type=entity_t.EntityType.ASYNC_JOB
+        )
+        for field_value in data.entity_details[0].field_values:
+            if field_value.field_ref_name == "core_async_job_jobData":
+                assert isinstance(field_value.value, dict)
+                assert isinstance(field_value.value["user_id"], int)
+                user_id = field_value.value["user_id"]
+            elif (
+                field_value.field_ref_name
+                == "unc_async_job_custom_parser_recipe_ids_in_view"
+            ):
+                if field_value.value is None:
+                    continue
+                assert isinstance(field_value.value, list)
+                if len(field_value.value) > 0:
+                    assert isinstance(field_value.value[0], int)
+                    recipe_id = field_value.value[0]
+            elif field_value.field_ref_name == "unc_async_job_custom_parser_input_file":
+                assert isinstance(field_value.value, list)
+                assert len(field_value.value) == 1
+                assert isinstance(field_value.value[0], dict)
+                assert isinstance(field_value.value[0]["name"], str)
+                file_name = field_value.value[0]["name"]
+
+        assert user_id is not None
+        assert file_name is not None
+
+        dummy_parsed_file_data: list[uploader_t.ParsedFileData] = [
+            uploader_t.ParsedFileData(
+                file_name=file_name,
+                file_structures=[
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column1",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value1"),
+                                uploader_t.StringValue(value="value4"),
+                                uploader_t.StringValue(value="value7"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column2",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value2"),
+                                uploader_t.StringValue(value="value5"),
+                                uploader_t.StringValue(value="value8"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column3",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value3"),
+                                uploader_t.StringValue(value="value6"),
+                                uploader_t.StringValue(value="value9"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.HeaderEntry(
+                        type=uploader_t.StructureElementType.HEADER,
+                        value=uploader_t.TextHeaderData(
+                            name="file_source",
+                            type=uploader_t.HeaderType.TEXT_HEADER,
+                            data=uploader_t.StringValue(value="my_file_to_upload.xlsx"),
+                        ),
+                    ),
+                    uploader_t.HeaderEntry(
+                        type=uploader_t.StructureElementType.HEADER,
+                        value=uploader_t.NumericHeaderData(
+                            name="file structure number",
+                            data=uploader_t.DecimalValue(value=Decimal(99)),
+                        ),
+                    ),
+                ],
+            )
+        ]
+
+        complete_async_parse_req = args.batch_processor.complete_async_parse(
+            parsed_file_data=dummy_parsed_file_data,
+            async_job_key=identifier_t.IdentifierKeyId(id=payload.async_job_id),
+            upload_destination=generic_upload_t.UploadDestinationRecipe(
+                recipe_key=identifier_t.IdentifierKeyId(id=recipe_id or 1)
+            ),
+        )
+
+        args.batch_processor.push_notification(
+            depends_on=[complete_async_parse_req.batch_reference],
+            notification_targets=[
+                notifications_t.NotificationTargetUser(
+                    user_key=identifier_t.IdentifierKeyId(id=user_id)
+                )
+            ],
+            subject="Upload complete",
+            message="Your file has been uploaded",
+            display_notice=True,
+        )
+
+        return job_definition_t.JobResult(success=True)
+
+    @property
+    def webhook_payload_type(self) -> type:
+        return ParsePayload

examples/integration-server/jobs/materials_auto/example_predictions.py

@@ -0,0 +1,61 @@
+import random
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from decimal import Decimal
+
+from uncountable.integration.job import JobArguments, WebhookJob, register_job
+from uncountable.types import (
+    base_t,
+    identifier_t,
+    job_definition_t,
+    recipe_links_t,
+    set_recipe_outputs_t,
+)
+
+
+@dataclass(kw_only=True)
+class PredictionsPayload:
+    output_id: base_t.ObjectId
+    recipe_ids: list[base_t.ObjectId]
+
+
+@register_job
+class PredictionsExample(WebhookJob[PredictionsPayload]):
+    def run(
+        self, args: JobArguments, payload: PredictionsPayload
+    ) -> job_definition_t.JobResult:
+        recipe_data = args.client.get_recipes_data(recipe_ids=payload.recipe_ids)
+        formatted_datetime = datetime.now(UTC).strftime("%Y-%m-%d %H:%M:%S")
+
+        for recipe in recipe_data.recipes:
+            test_sample_name = f"Predictions Model ({formatted_datetime})"
+            created_recipe_id = args.client.create_recipe(
+                name=test_sample_name,
+                material_family_id=1,
+                workflow_id=1,
+                definition_key=identifier_t.IdentifierKeyRefName(
+                    ref_name="unc_test_sample"
+                ),
+            ).result_id
+            args.client.set_recipe_outputs(
+                output_data=[
+                    set_recipe_outputs_t.RecipeOutputValue(
+                        recipe_id=created_recipe_id,
+                        output_id=payload.output_id,
+                        experiment_num=1,
+                        value_numeric=Decimal(random.random() * 10),
+                    )
+                ]
+            )
+            args.client.create_recipe_link(
+                recipe_from_key=identifier_t.IdentifierKeyId(id=recipe.recipe_id),
+                recipe_to_key=identifier_t.IdentifierKeyId(id=created_recipe_id),
+                link_type=recipe_links_t.RecipeLinkType.CHILD,
+                name=test_sample_name,
+            )
+
+        return job_definition_t.JobResult(success=True)
+
+    @property
+    def webhook_payload_type(self) -> type:
+        return PredictionsPayload

examples/integration-server/jobs/materials_auto/example_runsheet_wh.py

@@ -1,8 +1,19 @@
 from io import BytesIO
 
+from openpyxl import Workbook, load_workbook
 from uncountable.core.file_upload import DataFileUpload, FileUpload
 from uncountable.integration.job import JobArguments, RunsheetWebhookJob, register_job
-from uncountable.types import entity_t
+from uncountable.types import (
+    download_file_t,
+    entity_t,
+    export_default_runsheet_t,
+    identifier_t,
+    webhook_job_t,
+)
+from uncountable.types.client_base import APIRequest
+
+RUNSHEET_REF_NAME = "recipe_export_runsheet"
+RUNSHEET_REF_NAME_2 = "recipe_export_runsheet_2"
 
 
 @register_job
@@ -11,25 +22,55 @@ class StandardRunsheetGenerator(RunsheetWebhookJob):
         self,
         *,
         args: JobArguments,
-        entities: list[entity_t.Entity],
+        payload: webhook_job_t.RunsheetWebhookPayload,
     ) -> FileUpload:
-        args.logger.log_info(f"Generating runsheet for {len(entities)} entities")
+        args.logger.log_info("Exporting default runsheets")
+
+        entity_identifiers: list[identifier_t.IdentifierKey] = [
+            identifier_t.IdentifierKeyId(id=entity.id) for entity in payload.entities
+        ]
+
+        combined_wb = Workbook()
+        combined_sheet = combined_wb.active or combined_wb.create_sheet(
+            title="Combined Runsheet"
+        )
+        combined_sheet.title = "Combined Runsheet"
+
+        for ref_name in [RUNSHEET_REF_NAME, RUNSHEET_REF_NAME_2]:
+            api_request = APIRequest(
+                method=export_default_runsheet_t.ENDPOINT_METHOD,
+                endpoint=export_default_runsheet_t.ENDPOINT_PATH,
+                args=export_default_runsheet_t.Arguments(
+                    entities=entity_identifiers,
+                    runsheet_key=identifier_t.IdentifierKeyRefName(ref_name=ref_name),
+                    entity_type=payload.entities[0].type
+                    if payload.entities
+                    else entity_t.EntityType.RECIPE,
+                ),
+            )
 
-        content = []
-        content.append("STANDARD LAB RUNSHEET\n")
-        content.append("=" * 30 + "\n\n")
+            response = args.client.do_request(
+                api_request=api_request,
+                return_type=export_default_runsheet_t.Data,
+            )
 
-        for entity in entities:
-            content.append(f"Type: {entity.type}\n")
-            content.append(f"ID: {entity.id}\n")
+            file_query = download_file_t.FileDownloadQueryTextDocumentId(
+                text_document_id=response.text_document_id,
+            )
 
-            if hasattr(entity, "field_values") and entity.field_values:
-                content.append("Field Values:\n")
-                for field in entity.field_values:
-                    content.append(f"  - {field.name}: {field.value}\n")
+            downloaded_files = args.client.download_files(file_query=file_query)
+            file_data = downloaded_files[0].data.read()
 
-            content.append("\n")
+            wb = load_workbook(filename=BytesIO(file_data))
+            for sheet_name in wb.sheetnames:
+                for row in wb[sheet_name].iter_rows(values_only=True):
+                    combined_sheet.append(row)
 
-        runsheet_data = "".join(content).encode("utf-8")
+        output = BytesIO()
+        combined_wb.save(output)
+        output.seek(0)
 
-        return DataFileUpload(name="lab_runsheet.txt", data=BytesIO(runsheet_data))
+        return DataFileUpload(
+            data=output,
+            name="combined_runsheet.xlsx",
+        )

examples/integration-server/jobs/materials_auto/profile.yaml

@@ -84,3 +84,21 @@ jobs:
     executor:
       type: script
       import_path: example_instrument
+  - id: example_predictions
+    type: webhook
+    name: Webook Predictions
+    signature_key_secret:
+      type: env
+      env_key: WH_PREDICTIONS_SIGNATURE_KEY
+    executor:
+      type: script
+      import_path: example_predictions
+  - id: example_parse
+    type: webhook
+    name: Webhook Parse
+    signature_key_secret:
+      type: env
+      env_key: WH_PARSE_SIGNATURE_KEY
+    executor:
+      type: script
+      import_path: example_parse

examples/integration-server/pyproject.toml

@@ -9,7 +9,7 @@ dependencies = [
   "ruff == 0.*",
   "openpyxl == 3.*",
   "more_itertools == 10.*",
-  "types-paramiko ==4.0.0.20250806",
+  "types-paramiko ==4.0.0.20250822",
   "types-openpyxl == 3.*",
   "types-pysftp == 0.*",
   "types-pytz ==2025.*",
@@ -17,7 +17,8 @@ dependencies = [
   "types-simplejson == 3.*",
   "pandas-stubs",
   "xlrd == 2.*",
-  "msgspec == 0.19.*"
+  "msgspec == 0.19.*",
+  "websockets==15.0.1",
 ]
 
 [tool.mypy]
@@ -114,7 +115,6 @@ lint.ignore = [
     "PD010", # .pivottable.  Should add
     "PD011", # use .to_numpy.  Skip
     "PD015", # use .merge.  Should add
-    "PD901", # avoid generic df name.  Skip
     "PERF203", # avoid try except in loop. Skip
     "PERF401", # use list comprehension. Skip
     "PERF402", # use list.copy.  Skip
@@ -194,7 +194,6 @@ lint.ignore = [
     "RUF022",  # __all__ is not sorted.  skip due to isort complication
     "UP017", # use datetime.UTC, TODO add back in
     "UP035", # replacing List with list, TODO add back in
-    "UP038", # isinstance X | Y instead of (X, Y), TODO add back in
     # ## FROM RUFF UPGRADE
     "PLC2701",  # private name imports.  should add
     "PLR1702",  # too many nested blocks -- add with config.  skip
@@ -213,6 +212,7 @@ exclude = [
 
 [tool.ruff.lint.isort]
 split-on-trailing-comma = true
+known-first-party = ["pkgs"]
 
 [tool.ruff.lint.mccabe]
 max-complexity = 130 # goal would be to bring this down to ~50 or so

pkgs/argument_parser/argument_parser.py

@@ -168,6 +168,23 @@ def _invoke_membership_parser(
     raise ValueError(f"Expected value from {expected_values} but got value {value}")
 
 
+# Uses `is` to compare
+def _build_identity_parser(
+    identity_value: T,
+) -> ParserFunction[T]:
+    def parse(value: typing.Any) -> T:
+        if value is identity_value:
+            return identity_value
+        raise ValueError(
+            f"Expected value {identity_value} (type: {type(identity_value)}) but got value {value} (type: {type(value)})"
+        )
+
+    return parse
+
+
+NONE_IDENTITY_PARSER = _build_identity_parser(None)
+
+
 def _build_parser_discriminated_union(
     context: ParserContext,
     discriminator_raw: str,
@@ -243,8 +260,10 @@ def _build_parser_inner(
             for field_name, field_parser in field_parsers
         })
 
+    # IMPROVE: unclear why we need == here
     if parsed_type == type(None):  # noqa: E721
-        return lambda value: _invoke_membership_parser({None}, value)
+        # Need to convince type checker that parsed_type is type(None)
+        return typing.cast(ParserFunction[T], NONE_IDENTITY_PARSER)
 
     origin = typing.get_origin(parsed_type)
     if origin is tuple:

pkgs/serialization_util/serialization_helpers.py

@@ -85,7 +85,9 @@ def _serialize_dataclass(d: Any) -> dict[str, JsonValue]:
 
 
 def _to_string_value(value: Any) -> str:
-    assert isinstance(value, (Decimal, int))
+    assert isinstance(value, (Decimal, int)), (
+        f"Expecting decimal or int, received: {value} (type={type(value)})"
+    )
     return str(value)