Merge pull request #696 from UiPath/akshaya/connections_metadata

feat(ConnectionsMetadata): retrieve output schema from connections API

Author: akshaylive

src/uipath/_services/connections_service.py

@@ -7,7 +7,7 @@
 from .._config import Config
 from .._execution_context import ExecutionContext
 from .._utils import Endpoint, RequestSpec, header_folder, infer_bindings
-from ..models import Connection, ConnectionToken, EventArguments
+from ..models import Connection, ConnectionMetadata, ConnectionToken, EventArguments
 from ..models.connections import ConnectionTokenType
 from ..tracing._traced import traced
 from ._base_service import BaseService
@@ -54,6 +54,31 @@ def retrieve(self, key: str) -> Connection:
         response = self.request(spec.method, url=spec.endpoint)
         return Connection.model_validate(response.json())
 
+    @traced(
+        name="connections_metadata",
+        run_type="uipath",
+        hide_output=True,
+    )
+    def metadata(
+        self, element_instance_id: int, tool_path: str, schema_mode: bool = True
+    ) -> ConnectionMetadata:
+        """Synchronously retrieve connection API metadata.
+
+        This method fetches the metadata for a connection,
+        which can be used to establish communication with an external service.
+
+        Args:
+            element_instance_id (int): The element instance ID of the connection.
+            tool_path (str): The tool path to retrieve metadata for.
+            schema_mode (bool): Whether or not to represent the output schema in the response fields.
+
+        Returns:
+            ConnectionMetadata: The connection metadata.
+        """
+        spec = self._metadata_spec(element_instance_id, tool_path, schema_mode)
+        response = self.request(spec.method, url=spec.endpoint, headers=spec.headers)
+        return ConnectionMetadata.model_validate(response.json())
+
     @traced(name="connections_list", run_type="uipath")
     def list(
         self,
@@ -186,6 +211,33 @@ async def retrieve_async(self, key: str) -> Connection:
         response = await self.request_async(spec.method, url=spec.endpoint)
         return Connection.model_validate(response.json())
 
+    @traced(
+        name="connections_metadata",
+        run_type="uipath",
+        hide_output=True,
+    )
+    async def metadata_async(
+        self, element_instance_id: int, tool_path: str, schema_mode: bool = True
+    ) -> ConnectionMetadata:
+        """Asynchronously retrieve connection API metadata.
+
+        This method fetches the metadata for a connection,
+        which can be used to establish communication with an external service.
+
+        Args:
+            element_instance_id (int): The element instance ID of the connection.
+            tool_path (str): The tool path to retrieve metadata for.
+            schema_mode (bool): Whether or not to represent the output schema in the response fields.
+
+        Returns:
+            ConnectionMetadata: The connection metadata.
+        """
+        spec = self._metadata_spec(element_instance_id, tool_path, schema_mode)
+        response = await self.request_async(
+            spec.method, url=spec.endpoint, headers=spec.headers
+        )
+        return ConnectionMetadata.model_validate(response.json())
+
     @traced(
         name="connections_retrieve_token",
         run_type="uipath",
@@ -324,6 +376,20 @@ def _retrieve_spec(self, key: str) -> RequestSpec:
             endpoint=Endpoint(f"/connections_/api/v1/Connections/{key}"),
         )
 
+    def _metadata_spec(
+        self, element_instance_id: int, tool_path: str, schema_mode: bool
+    ) -> RequestSpec:
+        metadata_endpoint_url = f"/elements_/v3/element/instances/{element_instance_id}/elements/{tool_path}/metadata"
+        return RequestSpec(
+            method="GET",
+            endpoint=Endpoint(metadata_endpoint_url),
+            headers={
+                "accept": "application/schema+json"
+                if schema_mode
+                else "application/json"
+            },
+        )
+
     def _retrieve_token_spec(
         self, key: str, token_type: ConnectionTokenType = ConnectionTokenType.DIRECT
     ) -> RequestSpec:

src/uipath/models/__init__.py

@@ -3,7 +3,7 @@
 from .assets import Asset, UserAsset
 from .attachment import Attachment
 from .buckets import Bucket
-from .connections import Connection, ConnectionToken, EventArguments
+from .connections import Connection, ConnectionMetadata, ConnectionToken, EventArguments
 from .context_grounding import ContextGroundingQueryResponse
 from .context_grounding_index import ContextGroundingIndex
 from .errors import BaseUrlMissingError, SecretMissingError
@@ -38,6 +38,7 @@
     "QueueItemPriority",
     "TransactionItemResult",
     "Connection",
+    "ConnectionMetadata",
     "ConnectionToken",
     "EventArguments",
     "Job",

src/uipath/models/connections.py

@@ -4,6 +4,14 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 
+class ConnectionMetadata(BaseModel):
+    """Metadata about a connection."""
+
+    fields: dict[str, Any] = Field(default_factory=dict, alias="fields")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
 class Connection(BaseModel):
     model_config = ConfigDict(
         validate_by_name=True,

src/uipath/utils/dynamic_schema.py

@@ -0,0 +1,111 @@
+"""Json schema to dynamic pydantic model."""
+
+from typing import Any, Dict, List, Optional, Type, Union
+
+from pydantic import BaseModel, Field, create_model
+
+
+def jsonschema_to_pydantic(
+    schema: dict[str, Any],
+    definitions: Optional[dict[str, Any]] = None,
+) -> Type[BaseModel]:
+    """Convert a schema dict to a pydantic model.
+
+    Modified version of https://github.com/kreneskyp/jsonschema-pydantic to account for two unresolved issues.
+
+    Args:
+        schema: JSON schema.
+        definitions: Definitions dict. Defaults to `$def`.
+
+    Returns: Pydantic model.
+    """
+    title = schema.get("title", "DynamicModel")
+    assert isinstance(title, str), "Title of a model must be a string."
+
+    description = schema.get("description", None)
+
+    # top level schema provides definitions
+    if definitions is None:
+        if "$defs" in schema:
+            definitions = schema["$defs"]
+        elif "definitions" in schema:
+            definitions = schema["definitions"]
+        else:
+            definitions = {}
+
+    def convert_type(prop: dict[str, Any]) -> Any:
+        if "$ref" in prop:
+            ref_path = prop["$ref"].split("/")
+            ref = definitions[ref_path[-1]]
+            return jsonschema_to_pydantic(ref, definitions)
+
+        if "type" in prop:
+            type_mapping = {
+                "string": str,
+                "number": float,
+                "integer": int,
+                "boolean": bool,
+                "array": List,
+                "object": Dict[str, Any],
+                "null": None,
+            }
+
+            type_ = prop["type"]
+
+            if type_ == "array":
+                item_type: Any = convert_type(prop.get("items", {}))
+                assert isinstance(item_type, type)
+                return List[item_type]  # noqa F821
+            elif type_ == "object":
+                if "properties" in prop:
+                    return jsonschema_to_pydantic(prop, definitions)
+                else:
+                    return Dict[str, Any]
+            else:
+                return type_mapping.get(type_, Any)
+
+        elif "allOf" in prop:
+            combined_fields = {}
+            for sub_schema in prop["allOf"]:
+                model = jsonschema_to_pydantic(sub_schema, definitions)
+                combined_fields.update(model.__annotations__)
+            return create_model("CombinedModel", **combined_fields)
+
+        elif "anyOf" in prop:
+            unioned_types = tuple(
+                convert_type(sub_schema) for sub_schema in prop["anyOf"]
+            )
+            return Union[unioned_types]
+        elif prop == {} or "type" not in prop:
+            return Any
+        else:
+            raise ValueError(f"Unsupported schema: {prop}")
+
+    fields: dict[str, Any] = {}
+    required_fields = schema.get("required", [])
+
+    for name, prop in schema.get("properties", {}).items():
+        pydantic_type = convert_type(prop)
+        field_kwargs = {}
+        if "default" in prop:
+            field_kwargs["default"] = prop["default"]
+        if name not in required_fields:
+            # Note that we do not make this optional. This is due to a limitation in Pydantic/Python.
+            # If we convert the Optional type back to json schema, it is represented as type | None.
+            # pydantic_type = Optional[pydantic_type]
+
+            if "default" not in field_kwargs:
+                field_kwargs["default"] = None
+        if "description" in prop:
+            field_kwargs["description"] = prop["description"]
+        if "title" in prop:
+            field_kwargs["title"] = prop["title"]
+
+        fields[name] = (pydantic_type, Field(**field_kwargs))
+
+    convert_type(schema.get("properties", {}).get("choices", {}))
+
+    model = create_model(title, **fields)
+    if description:
+        model.__doc__ = description
+    return model

tests/cli/utils/test_dynamic_schema.py

@@ -0,0 +1,95 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from uipath.utils.dynamic_schema import jsonschema_to_pydantic
+
+
+def test_dynamic_schema():
+    # Arrange
+    class InnerSchema(BaseModel):
+        """Inner schema description."""
+
+        pass
+
+    class Schema(BaseModel):
+        """Schema description."""
+
+        string: str = Field(
+            default="", title="String Title", description="String Description"
+        )
+        optional_string: Optional[str] = Field(
+            default=None,
+            title="Optional String Title",
+            description="Optional String Description",
+        )
+        list_str: List[str] = Field(
+            default=[], title="List String", description="List String Description"
+        )
+
+        integer: int = Field(
+            default=0, title="Integer Title", description="Integer Description"
+        )
+        optional_integer: Optional[int] = Field(
+            default=None,
+            title="Option Integer Title",
+            description="Option Integer Description",
+        )
+        list_integer: List[int] = Field(
+            default=[],
+            title="List Integer Title",
+            description="List Integer Description",
+        )
+
+        floating: float = Field(
+            default=0.0, title="Floating Title", description="Floating Description"
+        )
+        optional_floating: Optional[float] = Field(
+            default=None,
+            title="Option Floating Title",
+            description="Option Floating Description",
+        )
+        list_floating: List[float] = Field(
+            default=[],
+            title="List Floating Title",
+            description="List Floating Description",
+        )
+
+        boolean: bool = Field(
+            default=False, title="Boolean Title", description="Boolean Description"
+        )
+        optional_boolean: Optional[bool] = Field(
+            default=None,
+            title="Option Boolean Title",
+            description="Option Boolean Description",
+        )
+        list_boolean: List[bool] = Field(
+            default=[],
+            title="List Boolean Title",
+            description="List Boolean Description",
+        )
+
+        nested_object: InnerSchema = Field(
+            default=InnerSchema(),
+            title="Nested Object Title",
+            description="Nested Object Description",
+        )
+        optional_nested_object: Optional[InnerSchema] = Field(
+            default=None,
+            title="Optional Nested Object Title",
+            description="Optional Nested Object Description",
+        )
+        list_nested_object: List[InnerSchema] = Field(
+            default=[],
+            title="List Nested Object Title",
+            description="List Nested Object Description",
+        )
+
+    schema_json = Schema.model_json_schema()
+
+    # Act
+    dynamic_schema = jsonschema_to_pydantic(schema_json)
+    dynamic_schema_json = dynamic_schema.model_json_schema()
+
+    # Assert
+    assert dynamic_schema_json == schema_json