chore: example util function to construct studio url (#780)

* example on constructing studio url with simple filter

* trim comments

* trim dep

* add ci

Author: nankolena

.circleci/continue_config.yml

@@ -439,7 +439,7 @@ workflows:
             - aws
           matrix:
             parameters:
-              subproject: [ age_estimation, automatic_speech_recognition, classification, keypoint_detection, question_answering, rain_forecast, semantic_segmentation, speaker_diarization, semantic_textual_similarity, person_detection, crossing_pedestrian_detection, named_entity_recognition ]
+              subproject: [ age_estimation, automatic_speech_recognition, classification, keypoint_detection, question_answering, rain_forecast, semantic_segmentation, speaker_diarization, semantic_textual_similarity, person_detection, crossing_pedestrian_detection, named_entity_recognition, construct_studio_url ]
               resource-class: [ small ]
               python-version: [ "3.9.18" ]
       - example-test-workflow:

examples/dataset/construct_studio_url/README.md

@@ -0,0 +1,14 @@
+# Example
+
+Construct a Studio URL from dataset information. Example:
+
+```python
+from construct_studio_url.encode_url import construct_studio_url
+
+tenant = "my-organization"
+dataset_id = 123
+datapoint_field = "locator"
+value = "s3://my-bucket/image_001.jpg"
+
+print(construct_studio_url(tenant, dataset_id, datapoint_field, value))
+```

examples/dataset/construct_studio_url/construct_studio_url/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2021-2025 Kolena Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

examples/dataset/construct_studio_url/construct_studio_url/encode_url.py

@@ -0,0 +1,51 @@
+# Copyright 2021-2025 Kolena Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import json
+from urllib.parse import quote
+
+import lzstring
+
+
+def construct_studio_url(tenant: str, dataset_id: int, datapoint_field: str, value: str) -> str:
+    """
+    Generate a Kolena dataset studio URL with a filter applied.
+
+    Args:
+        tenant: The tenant name (e.g., "try")
+        dataset_id: The ID of the dataset (e.g., 59)
+        datapoint_field: The field name to filter on (e.g., "uuid")
+        value: The value to filter for (e.g., "abc")
+    Returns:
+        A fully formatted URL string with the filter encoded
+    """
+    field_name = f"datapoint.{datapoint_field}"
+    filter_data = {
+        "contains": value,
+        "options": {
+            "regex_match": False,
+            "regex_flags": "",
+            "inverse": False,
+        },
+    }
+    json_string = json.dumps(filter_data, separators=(",", ":"))
+
+    compressor = lzstring.LZString()
+    compressed = compressor.compressToEncodedURIComponent(json_string)
+    filter_string = f"{field_name}:{compressed}:c"
+    encoded_filter = quote(filter_string, safe="")
+
+    base_url = f"https://app.kolena.com/{tenant}/dataset/studio"
+    full_url = f"{base_url}?datasetId={dataset_id}&filters={encoded_filter}"
+
+    return full_url

examples/dataset/construct_studio_url/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "construct_studio_url"
+version = "0.1.0"
+description = "Example generating Kolena studio URL with simple filters"
+authors = [
+    { name = "Kolena Engineering", email = "eng@kolena.com" }
+]
+license = "Apache-2.0"
+requires-python = ">=3.9,<3.12"
+
+dependencies = [
+    "lzstring>=1",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pre-commit>=2.17,<3",
+    "pytest>=7,<8",
+    "pytest-depends>=1.0.1,<2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

examples/dataset/construct_studio_url/tests/test__construct_studio_url.py

@@ -0,0 +1,74 @@
+# Copyright 2021-2025 Kolena Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import pytest
+from construct_studio_url.encode_url import construct_studio_url
+
+
+@pytest.mark.parametrize(
+    "tenant,dataset_id,datapoint_field,value,expected_url",
+    [
+        (
+            "try",
+            14,
+            "locator",
+            "s3://kolena-public-examples/coco-2014-val/data/COCO_val2014_000000000074.jpg",
+            "https://app.kolena.com/try/dataset/studio?datasetId=14&filters=datapoint.locator%3AN4Igxg9gdgLghgSygZxALhMgzGg9LgawgBsBTKOAWgAcBXAI2ITEtIA84Bbas5XSSJQBMABgCMAFkoA3OMVwATOPFwBhAPIaA%2BrOKjJWkUeMmA7BIB0AK2oBzEABoQEajATRUaUACdSt9lqcymAAFugAZnLIpE6%2B-mxa4cRwtp4gjiBI0qTe0RFRpAC%2BhUA%3Ac",  # noqa: E501
+        ),
+        (
+            "try",
+            45,
+            "date_captured",
+            "2013-11-16 12:50:10",
+            "https://app.kolena.com/try/dataset/studio?datasetId=45&filters=datapoint.date_captured%3AN4Igxg9gdgLghgSygZxALhAJgAwEYDMAtLrsQGwAEumaArNmrtiADQgQAOMC0qaoAJwCmAcyEAPAPoBbODDAALdADM4AG2RC2wsVOVq4IviFYgkANyEDNK9ZoC%2B9oA%3Ac",  # noqa: E501
+        ),
+        (
+            "try",
+            21,
+            "Location",
+            "Richmond",
+            "https://app.kolena.com/try/dataset/studio?datasetId=21&filters=datapoint.Location%3AN4Igxg9gdgLghgSygZxALhAJQWAFgW2gBMQAaECABxgWlTVACcBTAc2YA8B9fOGPdADM4AG2TNyLdt0Ei4reiDIgkAN2aNxQ0eIC%2BuoA%3Ac",  # noqa: E501
+        ),
+        (
+            "try",
+            19,
+            "transcription_path",
+            "audio/Bed017/interval3.csv",
+            "https://app.kolena.com/try/dataset/studio?datasetId=19&filters=datapoint.transcription_path%3AN4Igxg9gdgLghgSygZxALhHArgEwRAegCEBTHABgEYB2ApGEgJwDc4AbAZgDoxlmQANCAgAHGPhTpQjEgHMSADwD6AWzgwwAC3QAzdshJCZ85TrZxZqDIJBJmTA7v0kAvi6A%3Ac",  # noqa: E501
+        ),
+        (
+            "try",
+            25,
+            "abstract",
+            "We propose a real-time method to estimate spatially-varying indoor lighting from a single RGB image. Given an image and a 2D location in that image, our CNN estimates a 5th order spherical harmonic representation of the lighting at the given location in less than 20ms on a laptop mobile graphics card. While existing approaches estimate a single, global lighting representation or require depth as input, our method reasons about local lighting without requiring any geometry information. We demonstrate, through quantitative experiments including a user study, that our results achieve lower lighting estimation errors and are preferred by users over the state-of-the-art. Our approach can be used directly for augmented reality applications, where a virtual object is relit realistically at any position in the scene in real-time.",  # noqa: E501
+            "https://app.kolena.com/try/dataset/studio?datasetId=25&filters=datapoint.abstract%3AN4Igxg9gdgLghgSygZxALhAdQKYAIAOAThPhMnnLodnADYC0MCAtnqzABYQAmuMEubMibM4MPMnxiEdWgE96ANziE5SAOa4k3CBEK5aCdRyZRNAM2LNclZBtp4ASgHEAQltHrsAOlzOEithQNsEscF4hvJQATAAiBhBg0tBawZxiHuHYADS4EACu%2BgDCAHIlgsJh4sg2uACsnHmE3Nj6khytCEm0uBwqzNBdVNhEQkHwTCkQ5nwdBkYmGjYws3jqAUEJSZOhwQ7INenB0QAMzDUplLRw%2BPz4uAMARggOuOqENxxdNUnNvphfV7YAAeCEqZhs%2BCIEDgYA6NSEIjEFFwdjMDly6loEEedHmxlMmmoo3IsGSwT0wwAjvkENRcC1bhwbDUkPh8jBcgV9OwuLxqHBkNAanBHgUVtjuvjFhCAO4ITji6m0whLOBQORvbAQdiqVLmPSiHb-PAtAYoGAfcS5TjEfLGXA09VMCYbQTA-CdViwVlQMC0fLcNW4fLkNowQNyG19Fbc4bIfK0GAiuEIbCBBKy1rSwkVJE7QSEYiEEVQKL00bmVrUXiPTWh1oXQL6TgSCbYejTRgdegqGC%2BADyhUh0NhzKSwUeeAbvCD1DAMHkuAN%2Bjg9u94n5NEMME1N3whm2CGFuVlHXplEUdIjeJxACtsAutDVqDvhnQwUxukuMurNaQ7ALJBVlRMAgjwYCBQYEQfBAbIQBIHZUDQUBqC8YEAH0jThdBzDoch4LQkEMPMa51GQkA4JAJBm3IXD8OwABfRigA%3Ac",  # noqa: E501
+        ),
+        (
+            "demo",
+            165,
+            "text_summary",
+            "Andras Janos Vass, 25, found guilty of human trafficking and racketeering. Lured at least two young men to America via Planet Romeo dating site. Thought they would be offered legal escort work, earning $5,000 a month. Victims said they had travel documents taken and were forced into sex. Vass's sex ring, which he allegedly ran with two other men, started in NYC. Moved to Miami in late 2012, where Vass has been standing trial. He faces up to 155 years in prison for his crime - with minimum of 21 years.",  # noqa: E501
+            "https://app.kolena.com/demo/dataset/studio?datasetId=165&filters=datapoint.text_summary%3AN4Igxg9gdgLghgSygZxALhAQSgEwE5zIAEAUnFBMQGqHIA0RATAKwMBmEArrkQOacIANjACeRCGyIALTgFtyRGATZsEYANZJeRcjiIENAUxiHDeLQDoiAGU55DeuDCKDDhZzADuEIiK5RtWUMoRR9MIPMwOCIANwRogAVBcmMiACUIIJ8cJy0iZAQTKwAVKS5eKQ8pQzFvTkE9ACNDcRUzBxdDXjhBIkNkSDxnbzx1Bjc8KDyAElYABgWdIlloGCkrKjUYBFliZEQ9NZrpOEOCGMNenAgwOWCYYnh1YJ0eT3aiDjwwDqQYH2QhgAHhtaAByPbA-RaBieKRqKTSFo9Vy8ByCMQEEKeQqIrw%2BCBHPDLYIMZDwIa-EIAOQAmgBhKwAWQgF0OPiZ8VkCCISBcThajDmAEZGLDqvYiDRkMQpIQiM0XuTdHklPFBFYABItNhwH7ETgAB1CRGFzGYvgmxD5hvMyGgnwgxPhxDA5iCRAAtEQcWtlkgdnJWkxhZa4HhkBYQHQQBBDdtoKg0KB7GigQB9eQwMBSdC6wSAmOp4HptjJXhJkDRkBIC4Rwx5nqAgC%2BzaAA%3Ac",  # noqa: E501
+        ),
+    ],
+)
+def test__construct_studio_url(
+    tenant: str,
+    dataset_id: int,
+    datapoint_field: str,
+    value: str,
+    expected_url: str,
+) -> None:
+    generated = construct_studio_url(tenant, dataset_id, datapoint_field, value)
+    print(generated)
+    assert generated == expected_url