UncountablePythonSDK 0.0.21__py3-none-any.whl → 0.0.22__py3-none-any.whl

{UncountablePythonSDK-0.0.21.dist-info → UncountablePythonSDK-0.0.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: UncountablePythonSDK
-Version: 0.0.21
+Version: 0.0.22
 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.21.dist-info → UncountablePythonSDK-0.0.22.dist-info}/RECORD

@@ -14,6 +14,7 @@ docs/static/favicons/favicon-32x32.png,sha256=U4UU652zGnSeU3P9kUqxPeEnVf6zhtdNdN
 docs/static/favicons/manifest.json,sha256=6q_3nZkcg_x0xut4eE-xpdeMY1TydwiZIcbXlLAq9X8,437
 docs/static/favicons/mstile-150x150.png,sha256=eAK4QdEofhdLtfmjuPTpnX3MJqYnvGXsHYUjlcQekyY,1035
 docs/static/favicons/safari-pinned-tab.svg,sha256=S84fRnz0ZxLnQrKtmmFZytiRyu1xLtMR_RVy5jmwU7k,1926
+examples/async_batch.py,sha256=wpf_3P547375vTIO4pKv5vw6WCkUnzqvw_S3idfhjvM,1122
 examples/create_entity.py,sha256=54AmZt83EpypxGcYZSIMmWlGz2oAgHFOsKuLSZOcHsI,625
 examples/upload_files.py,sha256=ZsMChgOioraVHv207YREpivAOf4dq3IxGIBoROoDX_4,482
 examples/recipe-import/importer.py,sha256=baD71xuNibxDTe3bGHsMEIZEf9Xtb-IumBNpCEV0RZU,1134
@@ -34,16 +35,16 @@ pkgs/strenum_compat/__init__.py,sha256=wXRFeNvBm8RU6dy1PFJ5sRLgUIEeH_DVR95Sv5qpG
 pkgs/strenum_compat/strenum_compat.py,sha256=uOUAgpYTjHs1MX8dG81jRlyTkt3KNbkV_25zp7xTX2s,36
 pkgs/type_spec/__init__.py,sha256=h5DmJTca4QVV10sZR1x0-MlkZfuGYDfapR3zHvXfzto,19
 pkgs/type_spec/__main__.py,sha256=5bJaX9Y_-FavP0qwzhk-z-V97UY7uaezJTa1zhO_HHQ,1048
-pkgs/type_spec/builder.py,sha256=W9VA7JhPkLw3lau3FjYlIiBGzRs5LBPTZr0tTO2KVuU,39570
+pkgs/type_spec/builder.py,sha256=kLiTjVVbtctRfSStI15IZYbyQ4n2KPmvtJIWbizux40,43002
 pkgs/type_spec/config.py,sha256=INfEiDcUsZFUKasHprsE6i33siPB0RnfmTKOsWcGnQ8,5043
 pkgs/type_spec/emit_io_ts.py,sha256=gCEfS81w_ifqjLVJ3_cpy9Gq03o6H5nEsh35WAkqGGE,5606
-pkgs/type_spec/emit_open_api.py,sha256=4ihGO_neLL1A9zdoytQ5YypgBqyM0WKzBHo9wtsBPuE,17772
-pkgs/type_spec/emit_open_api_util.py,sha256=gMUB-fSrnTp6NyK_HbY02SP6cqSRObo-KIojDu4rn44,1900
-pkgs/type_spec/emit_python.py,sha256=CCHlOIMKdGu1VoaP7ly6dZ2cYank9jaAr8NDN50rFiE,42411
+pkgs/type_spec/emit_open_api.py,sha256=xy-nXjkqAZMDd-0qU5eDubRz1Hf8IwZSZj5bZyPSvX4,23328
+pkgs/type_spec/emit_open_api_util.py,sha256=F6qouGVm2-WGYkoubbBtRu00V4e30bWJ0fDBhigBEfg,2248
+pkgs/type_spec/emit_python.py,sha256=hj_5RUnJzjI6W9SmOh8ZUJTWB6F7PB1UFsg3OGSXZg0,42416
 pkgs/type_spec/emit_typescript.py,sha256=KOCcPuwSLRSt3pIp06Nq9exledq-kWtrA4RnUpeGMi8,17505
 pkgs/type_spec/emit_typescript_util.py,sha256=93FzJnpYse4PKFzgdw4DGV4zFTi5tF4WR-CIi7cW498,873
-pkgs/type_spec/load_types.py,sha256=AB334CF-368dpMNXE2QIFT7WxESvuew2RK_GG2MREng,2211
-pkgs/type_spec/open_api_util.py,sha256=88zgI_lHi6SjCaNfKpoiCjd1o0Npysjk-7iCXw0a3Hs,7463
+pkgs/type_spec/load_types.py,sha256=xEHwdB_miR3vNs161Oy1luafE0VC-yk9-utAyCJmbEo,3629
+pkgs/type_spec/open_api_util.py,sha256=TFbK2bkYT6S4qPQGO3_G2mfVgtNB26d31kwaHQ9y99E,6730
 pkgs/type_spec/test.py,sha256=4ueujBq-pEgnX3Z69HyPmD-bullFXmpixcpVzfOkhP4,489
 pkgs/type_spec/util.py,sha256=6m6MPfY-SwjyZf2FWQKclswWB5o7gcdd-3tdpViPYOQ,4844
 pkgs/type_spec/actions_registry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -61,8 +62,8 @@ pkgs/type_spec/value_spec/types.py,sha256=a2zxbbCRWepY1l8OtjeCDKgBKFPFHVgV99oP6p
 type_spec/external/api/batch/execute_batch.yaml,sha256=gpdSev3sLEC_cMVSZdj-9bc_XDFDqdPdOII9Ojme2N8,1170
 type_spec/external/api/batch/execute_batch_load_async.yaml,sha256=gcn51NWLiSvlytz8k3_pDOVJLCGfdivKJPG4I9Q8CZc,435
 type_spec/external/api/chemical/convert_chemical_formats.yaml,sha256=EidTxMCRs-ko5yMFDptJPyAEWYZVruP41OG3cwyBLQQ,1069
-type_spec/external/api/entity/create_entities.yaml,sha256=NVA7I1b4xf81urMKaiaiQPgvykEvjKslfOAN2gOhMIE,1441
-type_spec/external/api/entity/create_entity.yaml,sha256=2itcDpiuZHckhn45ZJyrssMOS9_CgBwFGf-MQyUyImw,1636
+type_spec/external/api/entity/create_entities.yaml,sha256=RKjmb_iY4dVHf3aQUCU-OrlbTLLsCkULQ9uEfa8BMFY,1506
+type_spec/external/api/entity/create_entity.yaml,sha256=Orz-3RZsNy5cWXlA3BKVQDYGnGGXlCXOtsOxDSm_nRY,1701
 type_spec/external/api/entity/get_entities_data.yaml,sha256=3XujG7bOpuBQlfFrYtG3L4fBk7LsmdSekmP9iU0zjF0,796
 type_spec/external/api/entity/list_entities.yaml,sha256=H2YVv6il-XVKd_7IipZqauTDvWCrvHok7z47bDH2sI4,1798
 type_spec/external/api/entity/resolve_entity_ids.yaml,sha256=Zf3OhAohwLJO7wWj0e-sK5lhIsXlD8A5Bu3OGjY4-tA,732
@@ -89,7 +90,7 @@ type_spec/external/api/recipes/associate_recipe_as_lot.yaml,sha256=8wzeJg5njt4qG
 type_spec/external/api/recipes/create_recipe.yaml,sha256=mGLyKJI3pN_7nU4rcSqCO3WjuKhO_odZ2pewVgYcMUU,1322
 type_spec/external/api/recipes/create_recipes.yaml,sha256=eXMlXRpB5TFt1mUTECBa4aAIG3KrxYT2mJ5vxmZ9Q3A,1503
 type_spec/external/api/recipes/disassociate_recipe_as_input.yaml,sha256=qTKQCNBNwLnbr22DQVLA6b80BdBhwnDbX1c4KoCKUm8,477
-type_spec/external/api/recipes/edit_recipe_inputs.yaml,sha256=CmolwyHSGJOQ33nJH7SQUYK-p2CWNEQ9yTstNxALv18,2631
+type_spec/external/api/recipes/edit_recipe_inputs.yaml,sha256=mmRcep8It4UIUmABtLKxwH5fuax_9yb0vvF8_6ROLjY,2591
 type_spec/external/api/recipes/get_curve.yaml,sha256=zQpPwOYqojY-YwmTjbqoGtUxpYm3vne2sYpglWbPnpw,779
 type_spec/external/api/recipes/get_recipe_calculations.yaml,sha256=ZE7PzfWrjS7TiO4q7iyCwEj5In8GwO6fFIYGqUlTEXo,1240
 type_spec/external/api/recipes/get_recipe_links.yaml,sha256=Vwm0OVWl3VvDaI7chY_oZQqD8xZ1u09iFWKkZKn1ITo,766
@@ -103,8 +104,9 @@ type_spec/external/api/recipes/set_recipe_tags.yaml,sha256=IrdkbryxZjNy8n4aMNLRT
 type_spec/external/api/triggers/run_trigger.yaml,sha256=c8xDV3bQRjcRRDG4Y7kdQmMMu1fj3ae5eUi-Sdbsi54,405
 uncountable/__init__.py,sha256=281cC2hs8pbrD0jVKMol-tbWSh7Zcsc8oRT42dKteyE,102
 uncountable/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-uncountable/core/__init__.py,sha256=OYipeBMLl_Mk2LApzJqzvOWSyQ12tdOXURp1GsKSjyE,190
-uncountable/core/client.py,sha256=ebBwERBKbdp7x5y77bFeyyGejIi02fjFZ4AMCJUfMpA,4507
+uncountable/core/__init__.py,sha256=7xUnbSWJzS31sWg0jCe5nIksn5s0PVdwUrUmDttHfCY,258
+uncountable/core/async_batch.py,sha256=0cRmCr6Z9sNxZyfY9Dl8wlCA4anISVZuHGgBegHhUbc,749
+uncountable/core/client.py,sha256=7bLuACxMJZsckSfL2j-p-XThYdvDAUAwm5nND9s-v1o,6946
 uncountable/core/file_upload.py,sha256=zTpAFSd7_-TmEVWxOn1rDznyWE6_AdZyuDQC3LP34iI,2667
 uncountable/core/types.py,sha256=gQtCw1-WSRak_ypFlGI1Ea9iZBP9zDeFq6XQtiXBlZA,459
 uncountable/integration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -119,19 +121,19 @@ uncountable/integration/db/connect.py,sha256=iI9e8a2hfbFP-dvH0MGLsrG-RpM0dHKCL-o
 uncountable/integration/executors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 uncountable/integration/executors/script_executor.py,sha256=6oMPAFe0PUdqt76e8jMi4vXszGVsVHLULob7Qbl3o38,816
 uncountable/types/__init__.py,sha256=fTNNsvFFkjp4acdBA8eS00OZVnDo_Zn7aRwPs8SFnrs,6024
-uncountable/types/async_batch.py,sha256=VMLB3ss1xzsFXovnWIaxgEVb4DWz7Agnf_MUNDaoRQc,1524
-uncountable/types/async_batch_processor.py,sha256=fwzfk0XY0L1ulzNi3dT8Aky5MyWPNK6GDStZ_I8Icoc,5914
+uncountable/types/async_batch.py,sha256=FtIoDCeyt9rF5hknQs6Sw-vjiYBMJbe1re0-4bk_6VY,1578
+uncountable/types/async_batch_processor.py,sha256=YksvTyJaZ3rqpZx4UXofUf7XU1Br4aNBNPZXB3LLtkA,5940
 uncountable/types/base.py,sha256=w3BRf8SAvYPlKrcJtJcQ_WhCU3A9zy0VuRTRWRFKVUA,2709
 uncountable/types/calculations.py,sha256=16J-KKMp-I8ZQUkYNmKCHfAn6DGb99cFinALcDIdGHY,562
 uncountable/types/chemical_structure.py,sha256=zQKl53DGtQQONIUHFXuwjWLQaG7FPZY7x6SBSOzkGV0,758
-uncountable/types/client_base.py,sha256=w-UnuzUSg8l_5kFhxo3w_b0_UC0eT-mtHheoA0f-U58,45967
+uncountable/types/client_base.py,sha256=eAgmDRoHhpsswgqI1q8-eg8joya7qaaFJKH1fyE50PE,46075
 uncountable/types/curves.py,sha256=qYyRntMmFNonEwTrGhquMLbgMqjyP1moQflNTP0FMec,1308
 uncountable/types/entity.py,sha256=NjMZrqBwQ7sZe_oUuJqy9IEG7dWZmFMkQQXJ0_odcnA,11637
 uncountable/types/experiment_groups.py,sha256=ZBEk06F4n98Jz3oEA09WaDmw5rqPs7iVAm_Ysr4gc_o,599
 uncountable/types/field_values.py,sha256=2unBAeBqQPqLQKaL6nGpnDDksZ-5MZepgEF3sgy6oOk,1670
 uncountable/types/fields.py,sha256=eGtZ6axTYGFxLmPAyri2LwlcR4SZ2sX2c6QDX0ybKz0,570
 uncountable/types/id_source.py,sha256=Y3suURq3L1SahZ2oHPD986SU0l3Ik-ZzH38aQKgc1Fg,1341
-uncountable/types/identifier.py,sha256=O_J3sHsG3pFeSIxUKmgIK97FZl6f4qkRDwsNLvY7ymE,1389
+uncountable/types/identifier.py,sha256=94-O3H_qNrA48tf3srwPwdu8HURkLl7_-88kUnwElZg,1455
 uncountable/types/input_attributes.py,sha256=u-JABoZ-Ij1Ynq5g6MxOgRdQeYbM7OnGP2q_N7KuVdw,826
 uncountable/types/inputs.py,sha256=q7fNGaSKIk3R6uXCEhSQpiHvXu82YcK3oZHDI7bxE88,1597
 uncountable/types/outputs.py,sha256=hSUlu41sisYKIZpPrj1G1DRfKm6hsKNcd1eNKFYb-4w,671
@@ -144,7 +146,7 @@ uncountable/types/recipe_links.py,sha256=RldSV7SdeBYa0bx02DzMg4jfPdgrlMRE40T16Fd
 uncountable/types/recipe_metadata.py,sha256=cebGg_lJzqZzGnKnDgmuQFrw4Xhoz6HEiGM6G0az120,1437
 uncountable/types/recipe_output_metadata.py,sha256=XJA8R1r4NTzyR_DhMkmH4ZtYD-vqpvBMji9Be8OcFmo,613
 uncountable/types/recipe_tags.py,sha256=lYpksHAxXCcIjZKR7JoZOTH2cBSovwxZaHwjZy_yqiQ,581
-uncountable/types/recipe_workflow_steps.py,sha256=bHVkwlsGODLpRFMJ2Ja-5FV1kqYjed8J0J0gU1dmTLQ,2615
+uncountable/types/recipe_workflow_steps.py,sha256=LmyFwWWwJv30vuaQ4qtd0hzDdeJaIxHQZqwRb1Wi_6A,2626
 uncountable/types/response.py,sha256=ZI0CG7ZxBM2k5_W-6mNMU3UlB0p1i-0nrwOvsMaS-vU,620
 uncountable/types/units.py,sha256=_kZ7KkXIbRiY2fOdkTsbJBpWRah5TCC2WWiG05e-1DA,565
 uncountable/types/users.py,sha256=SUjNHBDcImKnnE7IN096Wfr1fmjNjCkQ7yQgKUPffz8,588
@@ -156,8 +158,8 @@ uncountable/types/api/batch/execute_batch_load_async.py,sha256=dcdGFibO8fUDpC__X
 uncountable/types/api/chemical/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
 uncountable/types/api/chemical/convert_chemical_formats.py,sha256=COGzkfpTL_Ermg2cbasoVKGAxDAtJaTFay18IZtrWCA,1305
 uncountable/types/api/entity/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
-uncountable/types/api/entity/create_entities.py,sha256=oZVBovL3pdBfoKpaOXJcPtUyDxjKgFnYEqKfGx_ZcvE,1649
-uncountable/types/api/entity/create_entity.py,sha256=J6eY8b_XEQROFR7FI7In3zmFngaCBY5TcasMi4wy9t8,1819
+uncountable/types/api/entity/create_entities.py,sha256=vzo5hS1qcmjQdfyCMarSu8MRcRGSiholOVSCfjXlA1k,1703
+uncountable/types/api/entity/create_entity.py,sha256=ausozCQ3qPM9YUQ87bOTCKOm-zkhn4CSLJr9jLc9n2U,1873
 uncountable/types/api/entity/get_entities_data.py,sha256=XjrJGZucIn1TYUlDLRnRA0JTQw-vXHIAT-m0H9hk37A,1170
 uncountable/types/api/entity/list_entities.py,sha256=_bIIZJj3N0E6YiHgqzfCOKxD1fQW6biWJQMp5wIVbBw,1514
 uncountable/types/api/entity/resolve_entity_ids.py,sha256=AidGpPmI9ATDv0E7vd9LDOl3n3beGxUlRojh5uZrkl4,1086
@@ -193,7 +195,7 @@ uncountable/types/api/recipes/associate_recipe_as_lot.py,sha256=bTYjbnY3B7GKz4MV
 uncountable/types/api/recipes/create_recipe.py,sha256=Ni00efkcPkQ3WTIgDHzkfu1qoc52ReV9VT0wwwPOT4g,1364
 uncountable/types/api/recipes/create_recipes.py,sha256=qwIYa8hfcjY7_VOFt9lxmVtJ-HOJqQN3GDNSbZsRCZU,1544
 uncountable/types/api/recipes/disassociate_recipe_as_input.py,sha256=L25fpiK1Y5PByPVVgsZy9t4podz3xSSLIwKHj8CUrSg,913
-uncountable/types/api/recipes/edit_recipe_inputs.py,sha256=Ae7YMUsONp1bUVdaznetWiw-THPndnzFI-t4iMWV_eg,3338
+uncountable/types/api/recipes/edit_recipe_inputs.py,sha256=pTw606AgLhb-oJjfj1WPyEcJ4B0tgZsvEKeqP5VZ1gY,3281
 uncountable/types/api/recipes/get_curve.py,sha256=UIWfpqtU5sQokaxwYfQFNFl6HMyzWEF_Sjd8UMz0U88,939
 uncountable/types/api/recipes/get_recipe_calculations.py,sha256=eQmkdZzCEuq8S2f_kf_7GPvDLX1pTnY1CRmkK0SkMCI,1472
 uncountable/types/api/recipes/get_recipe_links.py,sha256=hk5dfQjv7yU2r-S9b8vwWEJLPHqU0-M6SFiTLMR3fVk,985
@@ -206,7 +208,7 @@ uncountable/types/api/recipes/set_recipe_outputs.py,sha256=QYq39TNchQ80ET1C77OE9
 uncountable/types/api/recipes/set_recipe_tags.py,sha256=U710hgq9-t6QZGRB-ZGHskpt4iXwYEjIRb67eh3P518,2453
 uncountable/types/api/triggers/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
 uncountable/types/api/triggers/run_trigger.py,sha256=9m9M8-nlGB_sAU2Qm2lWugp4h4Osqj6QpjNfU8osd1U,901
-UncountablePythonSDK-0.0.21.dist-info/METADATA,sha256=_xqCDeMHkCp6YfUDs-Wr2wc7e2ErYtHzjA1f6YqcGfc,1613
-UncountablePythonSDK-0.0.21.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-UncountablePythonSDK-0.0.21.dist-info/top_level.txt,sha256=HaMiBnH1wA7SG9-RVHIJPBH3l8X5gee2jUf-77Nz-Dk,41
-UncountablePythonSDK-0.0.21.dist-info/RECORD,,
+UncountablePythonSDK-0.0.22.dist-info/METADATA,sha256=o1sddgkTqesJ-3NQ_fm1xSgW1vj8bV-PAXnFW7g6-Hs,1613
+UncountablePythonSDK-0.0.22.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+UncountablePythonSDK-0.0.22.dist-info/top_level.txt,sha256=HaMiBnH1wA7SG9-RVHIJPBH3l8X5gee2jUf-77Nz-Dk,41
+UncountablePythonSDK-0.0.22.dist-info/RECORD,,

examples/async_batch.py

@@ -0,0 +1,36 @@
+from decimal import Decimal
+from uncountable.core import AuthDetailsApiKey, Client
+from uncountable.core import AsyncBatchProcessor
+from uncountable.types import (
+    recipe_metadata,
+)
+from uncountable.types.identifier import IdentifierKeyBatchReference
+from uncountable.types.recipe_identifiers import (
+    RecipeIdentifierEditableName,
+    RecipeIdentifiers,
+)
+
+
+client = Client(
+    base_url="https://app.uncountable.com",
+    auth_details=AuthDetailsApiKey(
+        api_id="X",
+        api_secret_key="X",
+    ),
+)
+batch_loader = AsyncBatchProcessor(client=client)
+recipe_identifiers: RecipeIdentifiers = []
+recipe_identifiers.append(
+    RecipeIdentifierEditableName(editable_name="My recipe from API")
+)
+req = batch_loader.create_recipe(
+    material_family_id=1, workflow_id=1, identifiers=recipe_identifiers
+)
+created_recipe_reference = req.batch_reference
+batch_loader.set_recipe_metadata(
+    recipe_key=IdentifierKeyBatchReference(reference=created_recipe_reference),
+    recipe_metadata=[
+        recipe_metadata.MetadataValue(metadata_id=7, value_numeric=Decimal(38))
+    ],
+)
+job_id = batch_loader.send()

pkgs/type_spec/builder.py

@@ -10,7 +10,7 @@ import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
 from enum import Enum, StrEnum, auto
-from typing import Any, Optional
+from typing import Any, Optional, Self
 
 from . import util
 from .util import parse_type_str, unused
@@ -184,6 +184,34 @@ class SpecTypeInstance(SpecType):
         return defn_type + self.parameters
 
 
+@dataclass(kw_only=True)
+class SpecEndpointExample:
+    summary: str
+    description: str
+    arguments: dict[str, object]
+    data: dict[str, object]
+
+
+@dataclass(kw_only=True)
+class SpecGuide:
+    title: str
+    markdown_content: str
+    html_content: str
+
+
+@dataclass(kw_only=True, frozen=True)
+class RootGuideKey:
+    pass
+
+
+@dataclass(kw_only=True, frozen=True)
+class EndpointGuideKey:
+    path: str
+
+
+SpecGuideKey = RootGuideKey | EndpointGuideKey
+
+
 class SpecTypeLiteralWrapper(SpecType):
     def __init__(
         self,
@@ -672,6 +700,32 @@ class ResultType(StrEnum):
 RE_ENDPOINT_ROOT = re.compile(r"\${([_a-z]+)}")
 
 
+@dataclass(kw_only=True, frozen=True)
+class _EndpointPathDetails:
+    root: str
+    root_path: str
+    resolved_path: str
+
+
+def _resolve_endpoint_path(
+    path: str, api_endpoints: dict[str, str]
+) -> _EndpointPathDetails:
+    root_path_source = path.split("/")[0]
+    root_match = RE_ENDPOINT_ROOT.fullmatch(root_path_source)
+    if root_match is None:
+        raise Exception(f"invalid-api-path-root:{root_path_source}")
+
+    root_var = root_match.group(1)
+    root_path = api_endpoints[root_var]
+
+    _, *rest_path = path.split("/", 1)
+    resolved_path = "/".join([root_path] + rest_path)
+
+    return _EndpointPathDetails(
+        root=root_var, root_path=root_path, resolved_path=resolved_path
+    )
+
+
 class SpecEndpoint:
     method: RouteMethod
     root: str
@@ -748,14 +802,10 @@ class SpecEndpoint:
 
         self.result_type = ResultType(data.get("result_type", ResultType.json.value))
 
+        path_details = _resolve_endpoint_path(data["path"], builder.api_endpoints)
+        self.root = path_details.root
+        self.path_root = path_details.root_path
         self.desc = data.get("desc")
-
-        root_match = RE_ENDPOINT_ROOT.fullmatch(path[0])
-        if root_match is None:
-            raise Exception(f"invalid-api-path-root:{path[0]}")
-
-        self.root = root_match.group(1)
-        self.path_root = builder.api_endpoints[self.root]
         # IMPROVE: remove need for is_external flag
         self.is_external = self.path_root == "api/external"
         self.has_attachment = data.get("has_attachment", False)
@@ -764,6 +814,10 @@ class SpecEndpoint:
             not is_sdk or self.desc is not None
         ), f"Endpoint description required for SDK endpoints, missing: {path}"
 
+    @property
+    def resolved_path(self: Self) -> str:
+        return f"{self.path_root}/{self.path_dirname}/{self.path_basename}"
+
 
 def _parse_const(
     builder: SpecBuilder,
@@ -1014,6 +1068,8 @@ class SpecBuilder:
         self.pending: list[NamespaceDataPair] = []
         self.parts: dict[str, dict[str, str]] = defaultdict(dict)
         self.preparts: dict[str, dict[str, str]] = defaultdict(dict)
+        self.examples: dict[str, list[SpecEndpointExample]] = defaultdict(list)
+        self.guides: dict[SpecGuideKey, list[SpecGuide]] = defaultdict(list)
         self.api_endpoints = api_endpoints
         base_namespace = SpecNamespace(name=base_namespace_name)
         for base_type in BaseTypeName:
@@ -1198,5 +1254,53 @@ class SpecBuilder:
     def add_prepart_file(self, target: str, name: str, data: str) -> None:
         self.preparts[target][name] = data
 
+    def add_example_file(self, data: dict[str, object]) -> None:
+        path_details = _resolve_endpoint_path(str(data["path"]), self.api_endpoints)
+
+        examples_data = data["examples"]
+        if not isinstance(examples_data, list):
+            raise Exception(
+                f"'examples' in example files are expected to be a list, endpoint_path={path_details.resolved_path}"
+            )
+        for example in examples_data:
+            arguments = example["arguments"]
+            data_example = example["data"]
+            if not isinstance(arguments, dict) or not isinstance(data_example, dict):
+                raise Exception(
+                    f"'arguments' and 'data' fields must be dictionaries for each endpoint example, endpoint={path_details.resolved_path}"
+                )
+            self.examples[path_details.resolved_path].append(
+                SpecEndpointExample(
+                    summary=str(example["summary"]),
+                    description=str(example["description"]),
+                    arguments=arguments,
+                    data=data_example,
+                )
+            )
+
+    def add_guide_file(self, file_content: str) -> None:
+        import markdown
+
+        md = markdown.Markdown(extensions=["meta"])
+        html = md.convert(file_content)
+        meta: dict[str, list[str]] = md.Meta  # type: ignore[attr-defined]
+        title_meta: list[str] | None = meta.get("title")
+        if title_meta is None:
+            raise Exception("guides requier a title in the meta section")
+
+        path_meta: list[str] | None = meta.get("path")
+        guide_key: SpecGuideKey = RootGuideKey()
+        if path_meta is not None:
+            path_details = _resolve_endpoint_path("".join(path_meta), self.api_endpoints)
+            guide_key = EndpointGuideKey(path=path_details.resolved_path)
+
+        self.guides[guide_key].append(
+            SpecGuide(
+                title="".join(title_meta),
+                html_content=html,
+                markdown_content=file_content,
+            )
+        )
+
     def resolve_proper_name(self, stype: SpecTypeDefn) -> str:
         return f"{'.'.join(stype.namespace.path)}.{stype.name}"

pkgs/type_spec/emit_open_api.py

@@ -5,18 +5,22 @@ WORK-IN-PROGRESS, DON'T USE!
 """
 
 import dataclasses
+import json
 import re
-from typing import cast
+from typing import Collection, cast
 
 import yaml
 
 from . import builder, util
+from .builder import EndpointGuideKey, RootGuideKey
 from .config import OpenAPIConfig
 from .emit_open_api_util import (
     MODIFY_NOTICE,
     EmitOpenAPIContext,
     EmitOpenAPIEndpoint,
+    EmitOpenAPIEndpointExample,
     EmitOpenAPIGlobalContext,
+    EmitOpenAPIGuide,
     EmitOpenAPIPath,
     EmitOpenAPIServer,
     EmitOpenAPITag,
@@ -74,12 +78,23 @@ def _rewrite_with_notice(
     return util.rewrite_file(file_path, f"{notice}\n{modified_file_content}")
 
 
-def _open_api_info(config: OpenAPIConfig) -> GlobalContextInfo:
-    description = config.description
+def _write_guide_as_html(guide: EmitOpenAPIGuide) -> str:
+    return f"""
+        <details>
+        <summary>{guide.title}</summary>
+        {guide.html_content}
+        </details>"""
+
+
+def _open_api_info(
+    config: OpenAPIConfig, guides: list[EmitOpenAPIGuide]
+) -> GlobalContextInfo:
+    full_guides = "<br/>".join([_write_guide_as_html(guide) for guide in guides])
+    full_description = f"{config.description}<br/>{full_guides}"
     info: GlobalContextInfo = dict()
     info["version"] = "1.0.0"
     info["title"] = "Uncountable API Documentation"
-    info["description"] = description
+    info["description"] = full_description
     info["x-logo"] = {"url": "../static/images/logo_blue.png", "altText": "Logo"}
     return info
 
@@ -90,9 +105,14 @@ def _open_api_servers(config: OpenAPIConfig) -> list[EmitOpenAPIServer]:
 
 
 def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> None:
+    root_guides = builder.guides.get(RootGuideKey(), [])
+    openapi_guides = [
+        EmitOpenAPIGuide(title=guide.title, html_content=guide.html_content)
+        for guide in root_guides
+    ]
     gctx = EmitOpenAPIGlobalContext(
         version="3.0.0",
-        info=_open_api_info(config),
+        info=_open_api_info(config, openapi_guides),
         servers=_open_api_servers(config),
     )
 
@@ -112,6 +132,8 @@ def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> Non
             ctx,
             namespace=namespace,
             config=config,
+            examples=builder.examples,
+            guides=builder.guides,
         )
 
     _rewrite_with_notice(
@@ -144,52 +166,183 @@ def _serialize_global_context(ctx: EmitOpenAPIGlobalContext) -> str:
     return yaml.dump(oa_root, sort_keys=False)
 
 
-def _emit_endpoint_parameters(typ: OpenAPIType | None) -> dict[str, list[dict[str, str]]]:
+def _is_empty_object_type(typ: OpenAPIType) -> bool:
     if not isinstance(typ, OpenAPIObjectType):
+        return False
+    return len(typ.properties) == 0
+
+
+_QUERY_PARM_METHODS = ("get", "head", "options")
+_REQUEST_BODY_METHODS = ("put", "post", "patch", "delete")
+
+ApiSchema = dict[str, "ApiSchema"] | Collection["ApiSchema"] | str | bool
+DictApiSchema = dict[str, ApiSchema]
+
+
+def _emit_endpoint_argument_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if len(examples) == 0:
+        return {}
+
+    response_examples = {}
+    for example in examples:
+        response_examples[example.ref_name] = {
+            "summary": example.summary,
+            "description": example.description,
+            "value": example.arguments,
+        }
+    return {"examples": response_examples}
+
+
+def _emit_endpoint_parameter_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if len(examples) == 0:
+        return {}
+
+    paramater_examples = []
+    comment_new_line = "\n// "
+    new_line = "\n"
+    for example in examples:
+        javascript_description = (
+            f"// {comment_new_line.join(example.description.split(new_line))}"
+        )
+        javascript_json_payload = f"{json.dumps(example.arguments, indent=2)}"
+        paramater_examples.append({
+            "lang": "JavaScript",
+            "label": f"Payload - {example.summary}",
+            "source": f"{javascript_description}\n{javascript_json_payload}",
+        })
+    return {"x-codeSamples": paramater_examples}
+
+
+def _emit_endpoint_parameters(
+    endpoint: EmitOpenAPIEndpoint,
+    argument_type: OpenAPIType | None,
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if (
+        endpoint.method.lower() not in _QUERY_PARM_METHODS
+        or argument_type is None
+        or _is_empty_object_type(argument_type)
+    ):
         return {}
 
     return {
         "parameters": [
-            {"$ref": f"#/components/schema/Arguments/{prop_name}"}
-            for prop_name in typ.properties
+            {
+                "name": "data",
+                "required": True,
+                "in": "query",
+                "content": {
+                    "application/json": {
+                        "schema": {"$ref": "#/components/schema/Arguments"}
+                    }
+                },
+            }
         ]
-    }
+    } | _emit_endpoint_parameter_examples(examples)
 
 
-def _emit_is_beta(is_beta: bool) -> dict[str, bool]:
+def _emit_is_beta(is_beta: bool) -> DictApiSchema:
     if is_beta:
         return {"x-beta": True}
     return {}
 
 
+def _emit_endpoint_request_body(
+    endpoint: EmitOpenAPIEndpoint,
+    arguments_type: OpenAPIType | None,
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if (
+        endpoint.method.lower() not in _REQUEST_BODY_METHODS
+        or arguments_type is None
+        or _is_empty_object_type(arguments_type)
+    ):
+        return {}
+
+    return {
+        "requestBody": {
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "title": "Body",
+                        "required": ["data"],
+                        "properties": {"data": {"$ref": "#/components/schema/Arguments"}},
+                    }
+                }
+                | _emit_endpoint_argument_examples(examples)
+            },
+        }
+    }
+
+
+def _emit_endpoint_response_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> dict[str, dict[str, object]]:
+    if len(examples) == 0:
+        return {}
+
+    response_examples: dict[str, object] = {}
+    for example in examples:
+        response_examples[example.ref_name] = {
+            "summary": example.summary,
+            "description": example.description,
+            "value": example.data,
+        }
+    return {"examples": response_examples}
+
+
+def _emit_endpoint_description(
+    description: str, guides: list[EmitOpenAPIGuide]
+) -> dict[str, str]:
+    full_guides = "<br/>".join([_write_guide_as_html(guide) for guide in guides])
+    return {
+        "description": description
+        if len(guides) == 0
+        else f"{description}<br/>{full_guides}"
+    }
+
+
 def _emit_namespace(
     gctx: EmitOpenAPIGlobalContext,
     ctx: EmitOpenAPIContext,
     namespace: builder.SpecNamespace,
     *,
     config: OpenAPIConfig,
+    examples: dict[str, list[builder.SpecEndpointExample]],
+    guides: dict[builder.SpecGuideKey, list[builder.SpecGuide]],
 ) -> None:
     for stype in namespace.types.values():
         _emit_type(ctx, stype, config=config)
 
     if namespace.endpoint is not None:
-        _emit_endpoint(gctx, ctx, namespace, namespace.endpoint)
+        endpoint_examples = examples.get(namespace.endpoint.resolved_path, [])
+        endpoint_guides = guides.get(
+            EndpointGuideKey(path=namespace.endpoint.resolved_path), []
+        )
+        _emit_endpoint(
+            gctx, ctx, namespace, namespace.endpoint, endpoint_examples, endpoint_guides
+        )
 
     oa_components: dict[str, object] = dict()
 
     if ctx.endpoint is not None:
         endpoint = ctx.endpoint
-
         argument_type = ctx.types.get("Arguments")
         oa_endpoint = dict()
         oa_endpoint[endpoint.method] = (
             {
                 "tags": endpoint.tags,
                 "summary": endpoint.summary,
-                "description": endpoint.description,
             }
+            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
             | _emit_is_beta(endpoint.is_beta)
-            | _emit_endpoint_parameters(argument_type)
+            | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
+            | _emit_endpoint_request_body(endpoint, argument_type, ctx.endpoint.examples)
             | {
                 "responses": {
                     "200": {
@@ -198,6 +351,7 @@ def _emit_namespace(
                             "application/json": {
                                 "schema": {"$ref": "#/components/schema/Data"}
                             }
+                            | _emit_endpoint_response_examples(ctx.endpoint.examples)
                         },
                     }
                 },
@@ -236,10 +390,7 @@ def _emit_namespace(
 
     oa_components["schema"] = cast(
         object,
-        {
-            name: (value.asdict() if name != "Arguments" else value.asarguments())
-            for name, value in types.items()
-        },
+        {name: value.asdict() for name, value in types.items()},
     )
 
     path = f"{config.types_output}/common/{'/'.join(namespace.path)}.yaml"
@@ -348,6 +499,8 @@ def _emit_endpoint(
     ctx: EmitOpenAPIContext,
     namespace: builder.SpecNamespace,
     endpoint: builder.SpecEndpoint,
+    endpoint_examples: list[builder.SpecEndpointExample],
+    endpoint_guides: list[builder.SpecGuide],
 ) -> None:
     assert namespace.endpoint is not None
     assert namespace.path[0] == "api"
@@ -397,6 +550,23 @@ def _emit_endpoint(
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
         is_beta=namespace.endpoint.is_beta,
+        examples=[
+            EmitOpenAPIEndpointExample(
+                ref_name=f"ex_{i}",
+                summary=example.summary,
+                description=example.description,
+                arguments=example.arguments,
+                data=example.data,
+            )
+            for i, example in enumerate(endpoint_examples)
+        ],
+        guides=[
+            EmitOpenAPIGuide(
+                title=guide.title,
+                html_content=guide.html_content,
+            )
+            for guide in endpoint_guides
+        ],
     )
 
 

pkgs/type_spec/emit_open_api_util.py

@@ -43,6 +43,12 @@ class EmitOpenAPIServer:
     url: str
 
 
+@dataclass(kw_only=True)
+class EmitOpenAPIGuide:
+    title: str
+    html_content: str
+
+
 @dataclass
 class EmitOpenAPIGlobalContext:
     version: str
@@ -56,6 +62,15 @@ class EmitOpenAPIGlobalContext:
     paths: list[EmitOpenAPIPath] = field(default_factory=list)
 
 
+@dataclass(kw_only=True)
+class EmitOpenAPIEndpointExample:
+    ref_name: str
+    summary: str
+    description: str
+    arguments: dict[str, object]
+    data: dict[str, object]
+
+
 @dataclass
 class EmitOpenAPIEndpoint:
     method: str
@@ -63,6 +78,8 @@ class EmitOpenAPIEndpoint:
     summary: str
     description: str
     is_beta: bool
+    examples: list[EmitOpenAPIEndpointExample]
+    guides: list[EmitOpenAPIGuide]
 
 
 @dataclass

pkgs/type_spec/emit_python.py

@@ -29,7 +29,7 @@ ASYNC_BATCH_REQUEST_STYPE = builder.SpecTypeDefnObject(
     namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="AsyncBatchRequest"
 )
 QUEUED_BATCH_REQUEST_STYPE = builder.SpecTypeDefnObject(
-    namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="QueuedBatchRequest"
+    namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="QueuedAsyncBatchRequest"
 )
 
 

pkgs/type_spec/load_types.py

@@ -1,5 +1,6 @@
 import os
 from collections.abc import Callable
+from io import StringIO
 from typing import Optional
 
 import yaml
@@ -13,11 +14,28 @@ ext_map = {
     ".py": "python",
 }
 
+_DOC_FILE_REFEX = ".*/docs/(examples|guides)/.*yaml"
+_EXAMPLE_FILE_REGEX = ".*/docs/examples/.*yaml"
+_GUIDE_FILE_REGEX = ".*/docs/guides/.*md"
+
 
 def find_and_handle_files(
-    root_folder: str, name_regex: str, handler: Callable[[str, str], None]
+    *,
+    root_folder: str,
+    handler: Callable[[str, str], None],
+    name_regex: str | None = None,
+    not_name_regex: str | None = None,
+    whole_name_regex: str | None = None,
+    not_whole_name_regex: str | None = None,
 ) -> None:
-    for file_name in fs.find(root_folder, name_regex=name_regex, relative=True):
+    for file_name in fs.find(
+        root_folder,
+        name_regex=name_regex,
+        not_name_regex=not_name_regex,
+        whole_name_regex=whole_name_regex,
+        not_whole_name_regex=not_whole_name_regex,
+        relative=True,
+    ):
         with open(os.path.join(root_folder, file_name), encoding="utf-8") as file:
             handler(file_name, file.read())
 
@@ -32,9 +50,16 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
         name, ext = os.path.splitext(by_name)
         handler(ext_map[ext], name, file_content)
 
+    def handle_builder_example_add(file_name: str, file_content: str) -> None:
+        yaml_content = yaml.safe_load(StringIO(file_content))
+        builder.add_example_file(yaml_content)
+
+    def handle_builder_guide_add(file_name: str, file_content: str) -> None:
+        builder.add_guide_file(file_content)
+
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder,
+            root_folder=folder,
             name_regex=".*\\.(ts|py)\\.part",
             handler=lambda file_name, file_content: handle_builder_add(
                 file_name, file_content, builder.add_part_file
@@ -43,7 +68,7 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
 
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder,
+            root_folder=folder,
             name_regex=".*\\.(ts|py)\\.prepart",
             handler=lambda file_name, file_content: handle_builder_add(
                 file_name, file_content, builder.add_prepart_file
@@ -64,9 +89,27 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
 
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder, name_regex=".*\\.yaml", handler=builder_prescan_file
+            root_folder=folder,
+            name_regex=".*\\.yaml",
+            not_whole_name_regex=_DOC_FILE_REFEX,
+            handler=builder_prescan_file,
         )
 
+    if config.open_api is not None:
+        for folder in config.type_spec_types:
+            find_and_handle_files(
+                root_folder=folder,
+                whole_name_regex=_EXAMPLE_FILE_REGEX,
+                handler=handle_builder_example_add,
+            )
+
+        for folder in config.type_spec_types:
+            find_and_handle_files(
+                root_folder=folder,
+                whole_name_regex=_GUIDE_FILE_REGEX,
+                handler=handle_builder_guide_add,
+            )
+
     if not builder.process():
         return None
 

pkgs/type_spec/open_api_util.py

@@ -1,6 +1,5 @@
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from io import UnsupportedOperation
 from typing import Optional
 
 
@@ -16,9 +15,6 @@ class OpenAPIType(ABC):
     def asdict(self) -> dict[str, object]:
         pass
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        raise UnsupportedOperation
-
     def add_addl_info(self, emitted: dict[str, object]) -> dict[str, object]:
         if self.description is not None:
             emitted["description"] = self.description
@@ -148,9 +144,6 @@ class OpenAPIFreeFormObjectType(OpenAPIType):
     def asdict(self) -> dict[str, object]:
         return self.add_addl_info({"type": "object"})
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        return {}
-
 
 class OpenAPIObjectType(OpenAPIType):
     """
@@ -174,31 +167,30 @@ class OpenAPIObjectType(OpenAPIType):
             self.property_desc = property_desc
         super().__init__(description=description, nullable=nullable)
 
+    def _emit_property_desc(self, property_name: str) -> dict[str, str]:
+        desc = self.property_desc.get(property_name)
+        if desc is None or desc.strip() == "":
+            return {}
+
+        return {"description": desc}
+
     def asdict(self) -> dict[str, object]:
         return self.add_addl_info({
             "type": "object",
+            "required": [
+                property_name
+                for property_name, property_type in self.properties.items()
+                if not property_type.nullable
+            ],
             "properties": {
                 property_name: {
                     **property_type.asdict(),
-                    "description": self.property_desc.get(property_name),
                 }
+                | self._emit_property_desc(property_name)
                 for property_name, property_type in self.properties.items()
             },
         })
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        argument_types: dict[str, dict[str, object]] = {}
-        for property_name, property_type in self.properties.items():
-            desc = self.property_desc.get(property_name)
-            argument_types[property_name] = {
-                "name": property_name,
-                "in": "query",
-                "schema": property_type.asdict(),
-                "required": not property_type.nullable,
-                "description": desc or "",
-            }
-        return argument_types
-
 
 class OpenAPIUnionType(OpenAPIType):
     """
@@ -220,12 +212,6 @@ class OpenAPIUnionType(OpenAPIType):
         # TODO: use parents description and nullable
         return {"oneOf": [base_type.asdict() for base_type in self.base_types]}
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return {}
-
 
 class OpenAPIIntersectionType(OpenAPIType):
     """
@@ -246,9 +232,3 @@ class OpenAPIIntersectionType(OpenAPIType):
     def asdict(self) -> dict[str, object]:
         # TODO: use parents description and nullable
         return {"allOf": [base_type.asdict() for base_type in self.base_types]}
-
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return {}

type_spec/external/api/entity/create_entities.yaml

@@ -24,6 +24,7 @@ Arguments:
                     Literal<entity.EntityType.lab_request>,
                     Literal<entity.EntityType.approval>,
                     Literal<entity.EntityType.custom_entity>,
+                    Literal<entity.EntityType.inventory_amount>,
                     Literal<entity.EntityType.task>,
                     Literal<entity.EntityType.project>,
                     Literal<entity.EntityType.equipment>,

type_spec/external/api/entity/create_entity.yaml

@@ -31,6 +31,7 @@ Arguments:
                     Literal<entity.EntityType.lab_request>,
                     Literal<entity.EntityType.approval>,
                     Literal<entity.EntityType.custom_entity>,
+                    Literal<entity.EntityType.inventory_amount>,
                     Literal<entity.EntityType.task>,
                     Literal<entity.EntityType.project>,
                     Literal<entity.EntityType.equipment>,

type_spec/external/api/recipes/edit_recipe_inputs.yaml

@@ -77,12 +77,10 @@ Arguments:
             type: identifier.IdentifierKey
             desc: "Identifier for the recipe"
         recipe_workflow_step_identifier:
-            type: recipe_workflow_steps.RecipeWorkflowStepIdentifierType
+            type: recipe_workflow_steps.RecipeWorkflowStepIdentifier
         edits:
             type: List<RecipeInputEdit>
 
 Data:
   type: Object
   properties:
-    result_id:
-      type: ObjectId

uncountable/core/__init__.py

@@ -1,4 +1,5 @@
 from .client import AuthDetailsApiKey, Client
 from .file_upload import MediaFileUpload, UploadedFile
+from .async_batch import AsyncBatchProcessor
 
-__all__: list[str] = ["AuthDetailsApiKey", "Client", "MediaFileUpload", "UploadedFile"]
+__all__: list[str] = ["AuthDetailsApiKey", "AsyncBatchProcessor", "Client", "MediaFileUpload", "UploadedFile"]

uncountable/core/async_batch.py

@@ -0,0 +1,22 @@
+from uncountable.core.client import Client
+from uncountable.types.async_batch import AsyncBatchRequest
+from uncountable.types.async_batch_processor import AsyncBatchProcessorBase
+from uncountable.types import async_batch_t, base_t
+
+
+class AsyncBatchProcessor(AsyncBatchProcessorBase):
+    _client: Client
+    _queue: list[AsyncBatchRequest]
+
+    def __init__(self, *, client: Client) -> None:
+        super().__init__()
+        self._client = client
+        self._queue = []
+
+    def _enqueue(self, req: async_batch_t.AsyncBatchRequest) -> None:
+        self._queue.append(req)
+
+    def send(self) -> base_t.ObjectId:
+        job_id = self._client.execute_batch_load_async(requests=self._queue).job_id
+        self._queue = []
+        return job_id

uncountable/core/client.py

@@ -6,9 +6,11 @@ from enum import StrEnum
 from urllib.parse import urljoin
 
 import requests
+from requests.exceptions import JSONDecodeError
 
 from pkgs.argument_parser import CachedParser
 from pkgs.serialization_util import serialize_for_api
+from pkgs.serialization_util.serialization_helpers import JsonValue
 from uncountable.types.client_base import APIRequest, ClientMethods
 
 from .file_upload import FileUpload, FileUploader, UploadedFile
@@ -46,16 +48,77 @@ class HTTPPostRequest(HTTPRequestBase):
 HTTPRequest = HTTPPostRequest | HTTPGetRequest
 
 
+
+@dataclass(kw_only=True)
+class ClientConfig():
+    allow_insecure_tls: bool = False
+      
+
+class APIResponseError(BaseException):
+    status_code: int
+    message: str
+    extra_details: dict[str, JsonValue] | None
+
+    def __init__(
+        self, status_code: int, message: str, extra_details: dict[str, JsonValue] | None
+    ) -> None:
+        super().__init__(status_code, message, extra_details)
+        self.status_code = status_code
+        self.message = message
+        self.extra_details = extra_details
+
+    @classmethod
+    def construct_error(
+        cls, status_code: int, extra_details: dict[str, JsonValue] | None
+    ) -> "APIResponseError":
+        message: str
+        match status_code:
+            case 403:
+                message = "unexpected: unauthorized"
+            case 410:
+                message = "unexpected: not found"
+            case 400:
+                message = "unexpected: bad arguments"
+            case 501:
+                message = "unexpected: unimplemented"
+            case 504:
+                message = "unexpected: timeout"
+            case 404:
+                message = "not found"
+            case 409:
+                message = "bad arguments"
+            case 422:
+                message = "unprocessable"
+            case _:
+                message = "unknown error"
+        return APIResponseError(
+            status_code=status_code, message=message, extra_details=extra_details
+        )
+
+
+class SDKError(BaseException):
+    message: str
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"internal SDK error, please contact Uncountable support: {self.message}"
+
+
 class Client(ClientMethods):
     _parser_map: dict[type, CachedParser] = {}
     _auth_details: AuthDetails
     _base_url: str
     _file_uploader: FileUploader
+    _cfg: ClientConfig
 
-    def __init__(self, *, base_url: str, auth_details: AuthDetails):
+    def __init__(self, *, base_url: str, auth_details: AuthDetails, config: ClientConfig | None = None):
         self._auth_details = auth_details
         self._base_url = base_url
         self._file_uploader = FileUploader(self._base_url, self._auth_details)
+        self._cfg = config or ClientConfig()
 
     def do_request(self, *, api_request: APIRequest, return_type: type[DT]) -> DT:
         http_request = self._build_http_request(api_request=api_request)
@@ -65,6 +128,7 @@ class Client(ClientMethods):
                     http_request.url,
                     headers=http_request.headers,
                     params=http_request.query_params,
+                    verify=not self._cfg.allow_insecure_tls
                 )
             case HTTPPostRequest():
                 response = requests.post(
@@ -72,19 +136,27 @@ class Client(ClientMethods):
                     headers=http_request.headers,
                     data=http_request.body,
                     params=http_request.query_params,
+                    verify=not self._cfg.allow_insecure_tls
                 )
             case _:
                 typing.assert_never(http_request)
         if response.status_code < 200 or response.status_code > 299:
-            # TODO: handle_error
-            pass
+            extra_details: dict[str, JsonValue] | None = None
+            try:
+                data = response.json()
+                if "error" in data:
+                    extra_details = data["error"]
+            except JSONDecodeError:
+                pass
+            raise APIResponseError.construct_error(
+                status_code=response.status_code, extra_details=extra_details
+            )
         cached_parser = self._get_cached_parser(return_type)
         try:
             data = response.json()["data"]
             return cached_parser.parse_api(data)
-        except ValueError as err:
-            # TODO: handle parse error
-            raise err
+        except ValueError | JSONDecodeError:
+            raise SDKError("unable to process response")
 
     def _get_cached_parser(self, data_type: type[DT]) -> CachedParser[DT]:
         if data_type not in self._parser_map:

uncountable/types/api/entity/create_entities.py

@@ -34,7 +34,7 @@ class EntityToCreate:
 @dataclass(kw_only=True)
 class Arguments:
     definition_id: base_t.ObjectId
-    entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]]
+    entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.INVENTORY_AMOUNT], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]]
     entities_to_create: list[EntityToCreate]
 
 

uncountable/types/api/entity/create_entity.py

@@ -40,7 +40,7 @@ class EntityFieldInitialValue:
 @dataclass(kw_only=True)
 class Arguments:
     definition_id: base_t.ObjectId
-    entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]]
+    entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.INVENTORY_AMOUNT], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]]
     field_values: typing.Optional[typing.Optional[list[field_values_t.FieldRefNameValue]]] = None
 
 

uncountable/types/api/recipes/edit_recipe_inputs.py

@@ -10,7 +10,6 @@ from decimal import Decimal  # noqa: F401
 from pkgs.strenum_compat import StrEnum
 from dataclasses import dataclass
 from pkgs.serialization import serial_class
-from ... import base as base_t
 from ... import identifier as identifier_t
 from ... import recipe_inputs as recipe_inputs_t
 from ... import recipe_workflow_steps as recipe_workflow_steps_t
@@ -96,12 +95,12 @@ RecipeInputEdit = typing.Union[RecipeInputEditClearInputs, RecipeInputEditUpsert
 @dataclass(kw_only=True)
 class Arguments:
     recipe_key: identifier_t.IdentifierKey
-    recipe_workflow_step_identifier: recipe_workflow_steps_t.RecipeWorkflowStepIdentifierType
+    recipe_workflow_step_identifier: recipe_workflow_steps_t.RecipeWorkflowStepIdentifier
     edits: list[RecipeInputEdit]
 
 
 # DO NOT MODIFY -- This file is generated by type_spec
 @dataclass(kw_only=True)
 class Data:
-    result_id: base_t.ObjectId
+    pass
 # DO NOT MODIFY -- This file is generated by type_spec

uncountable/types/async_batch.py

@@ -25,6 +25,7 @@ class AsyncBatchRequestPath(StrEnum):
     CREATE_RECIPE = "recipes/create_recipe"
     SET_RECIPE_METADATA = "recipes/set_recipe_metadata"
     SET_RECIPE_TAGS = "recipes/set_recipe_tags"
+    EDIT_RECIPE_INPUTS = "recipes/edit_recipe_inputs"
 
 
 # DO NOT MODIFY -- This file is generated by type_spec

uncountable/types/async_batch_processor.py

@@ -43,7 +43,7 @@ class AsyncBatchProcessorBase(ABC):
         identifiers: typing.Optional[recipe_identifiers_t.RecipeIdentifiers] = None,
         definition_key: typing.Optional[identifier_t.IdentifierKey] = None,
         depends_on: typing.Optional[list[str]] = None,
-    ) -> async_batch_t.QueuedBatchRequest:
+    ) -> async_batch_t.QueuedAsyncBatchRequest:
         """Returns the id of the recipe being created.
 
         :param name: The name for the recipe
@@ -77,7 +77,7 @@ class AsyncBatchProcessorBase(ABC):
 
         self._enqueue(req)
 
-        return async_batch_t.QueuedBatchRequest(
+        return async_batch_t.QueuedAsyncBatchRequest(
             path=req.path,
             batch_reference=req.batch_reference,
         )
@@ -86,10 +86,10 @@ class AsyncBatchProcessorBase(ABC):
         self,
         *,
         recipe_key: identifier_t.IdentifierKey,
-        recipe_workflow_step_identifier: recipe_workflow_steps_t.RecipeWorkflowStepIdentifierType,
+        recipe_workflow_step_identifier: recipe_workflow_steps_t.RecipeWorkflowStepIdentifier,
         edits: list[edit_recipe_inputs_t.RecipeInputEdit],
         depends_on: typing.Optional[list[str]] = None,
-    ) -> async_batch_t.QueuedBatchRequest:
+    ) -> async_batch_t.QueuedAsyncBatchRequest:
         """Clear, update, or add inputs on a recipe
 
         :param recipe_key: Identifier for the recipe
@@ -113,7 +113,7 @@ class AsyncBatchProcessorBase(ABC):
 
         self._enqueue(req)
 
-        return async_batch_t.QueuedBatchRequest(
+        return async_batch_t.QueuedAsyncBatchRequest(
             path=req.path,
             batch_reference=req.batch_reference,
         )
@@ -124,7 +124,7 @@ class AsyncBatchProcessorBase(ABC):
         recipe_key: identifier_t.IdentifierKey,
         recipe_metadata: list[recipe_metadata_t.MetadataValue],
         depends_on: typing.Optional[list[str]] = None,
-    ) -> async_batch_t.QueuedBatchRequest:
+    ) -> async_batch_t.QueuedAsyncBatchRequest:
         """Set metadata values on a recipe
 
         :param recipe_key: Identifier for the recipe
@@ -148,7 +148,7 @@ class AsyncBatchProcessorBase(ABC):
 
         self._enqueue(req)
 
-        return async_batch_t.QueuedBatchRequest(
+        return async_batch_t.QueuedAsyncBatchRequest(
             path=req.path,
             batch_reference=req.batch_reference,
         )

uncountable/types/client_base.py

@@ -147,7 +147,7 @@ class ClientMethods(ABC):
         self,
         *,
         definition_id: base_t.ObjectId,
-        entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]],
+        entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.INVENTORY_AMOUNT], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]],
         entities_to_create: list[create_entities_t.EntityToCreate],
     ) -> create_entities_t.Data:
         """Creates new Uncountable entities
@@ -172,7 +172,7 @@ class ClientMethods(ABC):
         self,
         *,
         definition_id: base_t.ObjectId,
-        entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]],
+        entity_type: typing.Union[typing.Literal[entity_t.EntityType.LAB_REQUEST], typing.Literal[entity_t.EntityType.APPROVAL], typing.Literal[entity_t.EntityType.CUSTOM_ENTITY], typing.Literal[entity_t.EntityType.INVENTORY_AMOUNT], typing.Literal[entity_t.EntityType.TASK], typing.Literal[entity_t.EntityType.PROJECT], typing.Literal[entity_t.EntityType.EQUIPMENT], typing.Literal[entity_t.EntityType.INV_LOCAL_LOCATIONS], typing.Literal[entity_t.EntityType.FIELD_OPTION_SET], typing.Literal[entity_t.EntityType.WEBHOOK]],
         field_values: typing.Optional[typing.Optional[list[field_values_t.FieldRefNameValue]]] = None,
     ) -> create_entity_t.Data:
         """Creates a new Uncountable entity

uncountable/types/identifier.py

@@ -23,7 +23,7 @@ __all__: list[str] = [
 @serial_class(
     parse_require={"type"},
 )
-@dataclass(kw_only=True)
+@dataclass(kw_only=True, frozen=True, eq=True)
 class IdentifierKeyId:
     type: typing.Literal["id"] = "id"
     id: base_t.ObjectId
@@ -33,7 +33,7 @@ class IdentifierKeyId:
 @serial_class(
     parse_require={"type"},
 )
-@dataclass(kw_only=True)
+@dataclass(kw_only=True, frozen=True, eq=True)
 class IdentifierKeyRefName:
     type: typing.Literal["ref_name"] = "ref_name"
     ref_name: str
@@ -43,7 +43,7 @@ class IdentifierKeyRefName:
 @serial_class(
     parse_require={"type"},
 )
-@dataclass(kw_only=True)
+@dataclass(kw_only=True, frozen=True, eq=True)
 class IdentifierKeyBatchReference:
     type: typing.Literal["batch_reference"] = "batch_reference"
     reference: str

uncountable/types/recipe_workflow_steps.py

@@ -59,7 +59,7 @@ class RecipeWorkflowStepPosition(StrEnum):
 class RecipeWorkflowStepIdentifierWorkflowStep(RecipeWorkflowStepIdentifierBase):
     type: typing.Literal[RecipeWorkflowStepIdentifierType.WORKFLOW_STEP] = RecipeWorkflowStepIdentifierType.WORKFLOW_STEP
     workflow_step_key: identifier_t.IdentifierKey
-    position: typing.Optional[RecipeWorkflowStepPosition] = None
+    position: RecipeWorkflowStepPosition = RecipeWorkflowStepPosition.FIRST
 
 
 # DO NOT MODIFY -- This file is generated by type_spec