From f55a9649397d67968d3aac494fcc76df68ba3302 Mon Sep 17 00:00:00 2001 From: Mani337 Date: Wed, 18 Nov 2026 15:17:36 +0530 Subject: [PATCH 1/4] feat(ontology): add an Ontology service client to uipath-platform [DS-9950] Add sdk.ontology (OntologyService) for the Ontology service: an ontology by id, its artifact manifest and files, its object graph, and SQL over its objects. Add the ontology binding type, and deprecate the Data Fabric ontology file fetch in EntitiesService. Co-Authored-By: Claude Opus 5.5 --- packages/uipath-platform/CLAUDE.md | 2 + packages/uipath-platform/pyproject.toml | 2 +- .../src/uipath/platform/_uipath.py | 5 + .../src/uipath/platform/common/_bindings.py | 1 + .../platform/entities/_entities_service.py | 7 + .../entities/_entity_ontology_service.py | 9 +- .../src/uipath/platform/ontology/__init__.py | 34 + .../platform/ontology/_ontology_service.py | 601 ++++++++++++++++++ .../src/uipath/platform/ontology/ontology.py | 120 ++++ .../tests/common/test_resource_override.py | 14 + .../tests/services/test_ontology_service.py | 396 ++++++++++++ packages/uipath-platform/uv.lock | 2 +- packages/uipath/uv.lock | 2 +- 13 files changed, 1190 insertions(+), 5 deletions(-) create mode 100644 packages/uipath-platform/src/uipath/platform/ontology/__init__.py create mode 100644 packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py create mode 100644 packages/uipath-platform/src/uipath/platform/ontology/ontology.py create mode 100644 packages/uipath-platform/tests/services/test_ontology_service.py diff --git a/packages/uipath-platform/CLAUDE.md b/packages/uipath-platform/CLAUDE.md index adbb1525b..f695ef911 100644 --- a/packages/uipath-platform/CLAUDE.md +++ b/packages/uipath-platform/CLAUDE.md @@ -50,6 +50,7 @@ sdk.mcp # McpService sdk.resource_catalog # ResourceCatalogService sdk.automation_tracker # AutomationTrackerService sdk.business_rules # BusinessRulesService +sdk.ontology # OntologyService ``` ### Authentication @@ -103,6 +104,7 @@ Services provide both sync and async variants (e.g., `.invoke()` and `.invoke_as | `context_grounding/` | RAG services (DeepRAG, batch RAG, ephemeral indexes) | | `documents/` | Document Understanding (IXP) | | `entities/` | Data Service entity management | +| `ontology/` | Ontology service: an ontology by id, its artifact files, its graph, SQL over its objects | | `guardrails/` | LLM output guardrails | | `resource_catalog/` | Resource discovery and metadata | | `resume_triggers/` | HITL trigger creation/reading protocols | diff --git a/packages/uipath-platform/pyproject.toml b/packages/uipath-platform/pyproject.toml index 0d2970dae..77038932b 100644 --- a/packages/uipath-platform/pyproject.toml +++ b/packages/uipath-platform/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-platform" -version = "0.3.10" +version = "0.3.11" description = "HTTP client library for programmatic access to UiPath Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/packages/uipath-platform/src/uipath/platform/_uipath.py b/packages/uipath-platform/src/uipath/platform/_uipath.py index e65f7bf3a..dddbc2c37 100644 --- a/packages/uipath-platform/src/uipath/platform/_uipath.py +++ b/packages/uipath-platform/src/uipath/platform/_uipath.py @@ -26,6 +26,7 @@ from .governance import GovernanceService from .guardrails import GuardrailsService from .memory import MemoryService +from .ontology import OntologyService from .orchestrator import ( AssetsService, AttachmentsService, @@ -166,6 +167,10 @@ def entities(self) -> EntitiesService: self._config, self._execution_context, folders_service=self.folders ) + @cached_property + def ontology(self) -> OntologyService: + return OntologyService(self._config, self._execution_context) + @cached_property def resource_catalog(self) -> ResourceCatalogService: return ResourceCatalogService( diff --git a/packages/uipath-platform/src/uipath/platform/common/_bindings.py b/packages/uipath-platform/src/uipath/platform/common/_bindings.py index 73d80fe38..8363e3b8a 100644 --- a/packages/uipath-platform/src/uipath/platform/common/_bindings.py +++ b/packages/uipath-platform/src/uipath/platform/common/_bindings.py @@ -62,6 +62,7 @@ class GenericResourceOverwrite(ResourceOverwrite): "remoteA2aAgent", "memorySpace", "businessRule", + "ontology", ] name: str = Field(alias="name") folder_path: str = Field(alias="folderPath") diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py index 042691a5f..311438ebd 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entities_service.py @@ -1442,6 +1442,10 @@ async def delete_record_v3_async(self, entity_key: str, record_id: str) -> None: """Async variant of `delete_record_v3()`.""" await self._data.delete_record_async(entity_key, record_id, use_v3=True) + @deprecated( + "Deprecated; ontologies live in the Ontology service. Use " + "UiPath().ontology.download_artifacts_async(ontology_id, artifact_type)." + ) async def get_ontology_file_async( self, ontology_name: str, @@ -1450,6 +1454,9 @@ async def get_ontology_file_async( ) -> Dict[str, Any]: """Fetch one file of an ontology from Data Fabric. + Deprecated: ontologies are served by the Ontology service by id; use + :class:`uipath.platform.ontology.OntologyService` instead. + !!! warning "Preview Feature" This method is currently experimental. Behavior and parameters are subject to change in future versions. diff --git a/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py b/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py index 48a649c2e..b30879977 100644 --- a/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py +++ b/packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py @@ -1,8 +1,13 @@ """Ontology-side operations for the Data Fabric entities surface. +Deprecated: ontologies are served by the Ontology service (``ontology_/api/v1``) +and addressed by id; use :class:`uipath.platform.ontology.OntologyService`. This +module stays for callers of ``EntitiesService.get_ontology_file_async`` until they +move. + Handles retrieval of ontology component files (OWL schema, R2RML mapping, and -other typed files). Entity schema and record operations are managed by -`EntitySchemaService` / `EntityDataService` and exposed alongside +other typed files) from Data Fabric. Entity schema and record operations are +managed by `EntitySchemaService` / `EntityDataService` and exposed alongside ontology operations through `EntitiesService`. """ diff --git a/packages/uipath-platform/src/uipath/platform/ontology/__init__.py b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py new file mode 100644 index 000000000..592ee27eb --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py @@ -0,0 +1,34 @@ +"""Ontology service package. + +Provides the ``OntologyService`` client for reading a deployed ontology by id, +downloading the artifact files it was installed from, reading its graph and +running SQL over its objects, plus the Pydantic models for those answers. +""" + +from ._ontology_service import ( + DEFAULT_MAX_ARTIFACT_BYTES, + MAX_SQL_LIMIT, + OntologyService, +) +from .ontology import ( + ONTOLOGY_DEPLOYED_STATE, + OntologyArtifact, + OntologyArtifactContent, + OntologyArtifactIntegrityError, + OntologyDetails, + SqlColumn, + SqlResult, +) + +__all__ = [ + "DEFAULT_MAX_ARTIFACT_BYTES", + "MAX_SQL_LIMIT", + "ONTOLOGY_DEPLOYED_STATE", + "OntologyArtifact", + "OntologyArtifactContent", + "OntologyArtifactIntegrityError", + "OntologyDetails", + "OntologyService", + "SqlColumn", + "SqlResult", +] diff --git a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py new file mode 100644 index 000000000..36edbc8a2 --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py @@ -0,0 +1,601 @@ +"""Ontology service: an ontology by id, its artifacts, its graph and SQL over it. + +Backend target: ``ontology_/api/v1``. The ontology id is its key in the Resource +Catalog and in Solutions; the routes also accept the ontology's name, which is +folder-scoped, so an ``ontology`` binding can re-point a call to a name in a folder. + +Honors ``UIPATH_SERVICE_URL_ONTOLOGY`` for local development, as every service +does: ``BaseService.request`` redirects the call and injects the routing headers. +""" + +import logging +import re +from typing import Any, Dict, List, Optional +from urllib.parse import quote + +from uipath.core.tracing import traced + +from ..common._base_service import BaseService +from ..common._bindings import resource_override +from ..common._config import UiPathApiConfig +from ..common._execution_context import UiPathExecutionContext +from ..common._folder_context import header_folder +from ..common._models import Endpoint, RequestSpec +from .ontology import ( + OntologyArtifact, + OntologyArtifactContent, + OntologyArtifactIntegrityError, + OntologyDetails, + SqlResult, +) + +logger = logging.getLogger(__name__) + +_BASE = "ontology_/api/v1/ontology" + +#: What ``download_artifacts`` puts in a prompt at most, per file. +DEFAULT_MAX_ARTIFACT_BYTES = 256_000 + +#: The service reads 50 rows without a LIMIT and caps a LIMIT at 200. +MAX_SQL_LIMIT = 200 + +_HAS_LIMIT = re.compile(r"\blimit\b", re.IGNORECASE) +_HAS_OFFSET = re.compile(r"\boffset\b", re.IGNORECASE) + + +def _segment(value: str, what: str) -> str: + """One URL path segment, encoded so an id or file name can never add a path.""" + if not value or not value.strip(): + raise ValueError(f"{what} must be a non-empty string") + return quote(value, safe="") + + +class OntologyService(BaseService): + """Service for reading a deployed ontology and querying its objects. + + Every method takes the ontology's id. An ``ontology`` binding can replace that + id with an ontology name and a folder; names are folder-scoped on the service, + so the folder travels as the folder header. + + !!! warning "Preview Feature" + This service is currently experimental. Behavior and parameters are + subject to change in future versions. + + Examples: + ```python + from uipath.platform import UiPath + + sdk = UiPath() + details = await sdk.ontology.get_async(ontology_id) + if details.is_deployed: + files = await sdk.ontology.download_artifacts_async(ontology_id, "schema") + answer = await sdk.ontology.execute_sql_async( + ontology_id, "SELECT name FROM Supplier WHERE country = :c", {"c": "RO"} + ) + ``` + """ + + def __init__( + self, + config: UiPathApiConfig, + execution_context: UiPathExecutionContext, + ) -> None: + super().__init__(config=config, execution_context=execution_context) + + # ── details ────────────────────────────────────────────────────────── + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get", run_type="uipath") + def get( + self, + ontology_id: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyDetails: + """Read an ontology's catalog details. + + Args: + ontology_id: The ontology's id (its Resource Catalog key), or its name + together with the folder it lives in. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + OntologyDetails: identifier, label, description, folder and state. + """ + spec = self._details_spec(ontology_id, folder_key, folder_path) + response = self.request(spec.method, url=spec.endpoint, headers=spec.headers) + return OntologyDetails.model_validate(response.json()) + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get", run_type="uipath") + async def get_async( + self, + ontology_id: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyDetails: + """Read an ontology's catalog details. See :meth:`get`.""" + spec = self._details_spec(ontology_id, folder_key, folder_path) + response = await self.request_async( + spec.method, url=spec.endpoint, headers=spec.headers + ) + return OntologyDetails.model_validate(response.json()) + + # ── artifacts ──────────────────────────────────────────────────────── + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_list_artifacts", run_type="uipath") + def list_artifacts( + self, + ontology_id: str, + artifact_type: Optional[str] = None, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> List[OntologyArtifact]: + """List an ontology's artifacts: the manifest, without content. + + Args: + ontology_id: The ontology's id, or its name with a folder. + artifact_type: Keep one type only: ``schema``, ``mapping``, + ``business-rules``, ``summary``, ``context`` (or ``constraints``). + The service answers 400 for an unknown type. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + List[OntologyArtifact]: one entry per file, with size and SHA-256. + """ + spec = self._manifest_spec(ontology_id, artifact_type, folder_key, folder_path) + response = self.request( + spec.method, url=spec.endpoint, params=spec.params, headers=spec.headers + ) + return [OntologyArtifact.model_validate(item) for item in response.json()] + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_list_artifacts", run_type="uipath") + async def list_artifacts_async( + self, + ontology_id: str, + artifact_type: Optional[str] = None, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> List[OntologyArtifact]: + """List an ontology's artifacts. See :meth:`list_artifacts`.""" + spec = self._manifest_spec(ontology_id, artifact_type, folder_key, folder_path) + response = await self.request_async( + spec.method, url=spec.endpoint, params=spec.params, headers=spec.headers + ) + return [OntologyArtifact.model_validate(item) for item in response.json()] + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_artifact", run_type="uipath") + def get_artifact( + self, + ontology_id: str, + file_name: str, + *, + expected: Optional[OntologyArtifact] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyArtifactContent: + """Download one artifact's bytes. + + Args: + ontology_id: The ontology's id, or its name with a folder. + file_name: The artifact's file name, as the manifest lists it. + expected: The manifest entry to verify the download against. When given, + a size or SHA-256 mismatch raises before the content is returned. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + OntologyArtifactContent: the bytes, their media type and the ETag. + + Raises: + OntologyArtifactIntegrityError: If ``expected`` is given and the bytes + do not match it. + """ + spec = self._download_spec(ontology_id, file_name, folder_key, folder_path) + response = self.request(spec.method, url=spec.endpoint, headers=spec.headers) + return self._to_content(file_name, response, expected) + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_artifact", run_type="uipath") + async def get_artifact_async( + self, + ontology_id: str, + file_name: str, + *, + expected: Optional[OntologyArtifact] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyArtifactContent: + """Download one artifact's bytes. See :meth:`get_artifact`.""" + spec = self._download_spec(ontology_id, file_name, folder_key, folder_path) + response = await self.request_async( + spec.method, url=spec.endpoint, headers=spec.headers + ) + return self._to_content(file_name, response, expected) + + @traced(name="ontology_download_artifacts", run_type="uipath") + def download_artifacts( + self, + ontology_id: str, + artifact_type: Optional[str] = None, + *, + max_bytes: int = DEFAULT_MAX_ARTIFACT_BYTES, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> List[OntologyArtifactContent]: + """Download every artifact of a type, verified against the manifest. + + Files larger than ``max_bytes`` are skipped with a warning, since they are + meant for a prompt and would not fit. + + Args: + ontology_id: The ontology's id, or its name with a folder. + artifact_type: Keep one type only; every type when omitted. + max_bytes: The largest file to download, by its manifest size. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + List[OntologyArtifactContent]: the verified files, in manifest order. + """ + manifest = self.list_artifacts( + ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path + ) + contents: List[OntologyArtifactContent] = [] + for entry in self._within_budget(manifest, max_bytes): + contents.append( + self.get_artifact( + ontology_id, + entry.file_name, + expected=entry, + folder_key=folder_key, + folder_path=folder_path, + ) + ) + return contents + + @traced(name="ontology_download_artifacts", run_type="uipath") + async def download_artifacts_async( + self, + ontology_id: str, + artifact_type: Optional[str] = None, + *, + max_bytes: int = DEFAULT_MAX_ARTIFACT_BYTES, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> List[OntologyArtifactContent]: + """Download every artifact of a type. See :meth:`download_artifacts`.""" + manifest = await self.list_artifacts_async( + ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path + ) + contents: List[OntologyArtifactContent] = [] + for entry in self._within_budget(manifest, max_bytes): + contents.append( + await self.get_artifact_async( + ontology_id, + entry.file_name, + expected=entry, + folder_key=folder_key, + folder_path=folder_path, + ) + ) + return contents + + # ── graph ──────────────────────────────────────────────────────────── + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_graph", run_type="uipath") + def get_graph( + self, + ontology_id: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> Dict[str, Any]: + """Read the ontology's graph: objects, properties, relationships, operations. + + Returned as the service sends it, since its shape is still evolving. + + Args: + ontology_id: The ontology's id, or its name with a folder. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + Dict[str, Any]: the graph view. + """ + spec = self._graph_spec(ontology_id, folder_key, folder_path) + response = self.request(spec.method, url=spec.endpoint, headers=spec.headers) + return response.json() + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_graph", run_type="uipath") + async def get_graph_async( + self, + ontology_id: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> Dict[str, Any]: + """Read the ontology's graph. See :meth:`get_graph`.""" + spec = self._graph_spec(ontology_id, folder_key, folder_path) + response = await self.request_async( + spec.method, url=spec.endpoint, headers=spec.headers + ) + return response.json() + + # ── SQL ────────────────────────────────────────────────────────────── + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_execute_sql", run_type="uipath") + def execute_sql( + self, + ontology_id: str, + statement: str, + params: Optional[Dict[str, Any]] = None, + *, + limit: Optional[int] = None, + offset: Optional[int] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> SqlResult: + """Run one SELECT over the ontology's objects. + + The statement is written over business objects and their properties, with + ``:name`` parameters bound from ``params``; the service translates it onto + the mapped entities and runs it with the caller's permissions. Values go in + ``params``, never in the statement text. + + Args: + ontology_id: The ontology's id, or its name with a folder. + statement: The SELECT, with ``:name`` placeholders. + params: Values for the placeholders. + limit: Rows to read, at most 200. Without one the service reads 50. + Appended as a LIMIT clause; the statement must not have one already. + offset: Rows to skip, for a later page; pair with ORDER BY. Appended as + an OFFSET clause; the statement must not have one already. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + SqlResult: columns, rows as objects, and the row count. + + Raises: + ValueError: If the statement is blank, a bound is out of range, or a + bound is given for a statement that already has that clause. + """ + spec = self._sql_spec( + ontology_id, statement, params, limit, offset, folder_key, folder_path + ) + response = self.request( + spec.method, url=spec.endpoint, json=spec.json, headers=spec.headers + ) + return SqlResult.model_validate(response.json()) + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_execute_sql", run_type="uipath") + async def execute_sql_async( + self, + ontology_id: str, + statement: str, + params: Optional[Dict[str, Any]] = None, + *, + limit: Optional[int] = None, + offset: Optional[int] = None, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> SqlResult: + """Run one SELECT over the ontology's objects. See :meth:`execute_sql`.""" + spec = self._sql_spec( + ontology_id, statement, params, limit, offset, folder_key, folder_path + ) + response = await self.request_async( + spec.method, url=spec.endpoint, json=spec.json, headers=spec.headers + ) + return SqlResult.model_validate(response.json()) + + # ── specs ──────────────────────────────────────────────────────────── + + @staticmethod + def _details_spec( + ontology_id: str, folder_key: Optional[str], folder_path: Optional[str] + ) -> RequestSpec: + return RequestSpec( + method="GET", + endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}"), + headers=header_folder(folder_key, folder_path), + ) + + @staticmethod + def _manifest_spec( + ontology_id: str, + artifact_type: Optional[str], + folder_key: Optional[str], + folder_path: Optional[str], + ) -> RequestSpec: + params: Dict[str, Any] = {} + if artifact_type: + params["type"] = artifact_type + return RequestSpec( + method="GET", + endpoint=Endpoint( + f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/artifact" + ), + params=params, + headers=header_folder(folder_key, folder_path), + ) + + @staticmethod + def _download_spec( + ontology_id: str, + file_name: str, + folder_key: Optional[str], + folder_path: Optional[str], + ) -> RequestSpec: + return RequestSpec( + method="GET", + endpoint=Endpoint( + f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/artifact/" + f"{_segment(file_name, 'file_name')}" + ), + headers=header_folder(folder_key, folder_path), + ) + + @staticmethod + def _graph_spec( + ontology_id: str, folder_key: Optional[str], folder_path: Optional[str] + ) -> RequestSpec: + return RequestSpec( + method="GET", + endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/graph"), + headers=header_folder(folder_key, folder_path), + ) + + @staticmethod + def _sql_spec( + ontology_id: str, + statement: str, + params: Optional[Dict[str, Any]], + limit: Optional[int], + offset: Optional[int], + folder_key: Optional[str], + folder_path: Optional[str], + ) -> RequestSpec: + return RequestSpec( + method="POST", + endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/sql"), + json={ + "statement": _bounded_statement(statement, limit, offset), + "params": params or {}, + }, + headers=header_folder(folder_key, folder_path), + ) + + # ── helpers ────────────────────────────────────────────────────────── + + @staticmethod + def _within_budget( + manifest: List[OntologyArtifact], max_bytes: int + ) -> List[OntologyArtifact]: + kept: List[OntologyArtifact] = [] + for entry in manifest: + if entry.size_bytes > max_bytes: + logger.warning( + "Skipping ontology artifact %s: %d bytes is over the %d byte cap", + entry.file_name, + entry.size_bytes, + max_bytes, + ) + continue + kept.append(entry) + return kept + + @staticmethod + def _to_content( + file_name: str, response: Any, expected: Optional[OntologyArtifact] + ) -> OntologyArtifactContent: + content = OntologyArtifactContent( + file_name=file_name, + content=response.content, + media_type=response.headers.get("content-type", ""), + etag=response.headers.get("etag"), + type=expected.type if expected else None, + ) + if expected is not None: + _verify(content, expected) + return content + + +def _verify(content: OntologyArtifactContent, expected: OntologyArtifact) -> None: + """Refuse content whose size or SHA-256 differs from the manifest entry.""" + if len(content.content) != expected.size_bytes: + raise OntologyArtifactIntegrityError( + f"Artifact '{expected.file_name}' is {len(content.content)} bytes, " + f"the manifest says {expected.size_bytes}" + ) + digest = content.sha256() + if digest != expected.checksum.lower(): + raise OntologyArtifactIntegrityError( + f"Artifact '{expected.file_name}' checksum {digest} does not match " + f"the manifest's {expected.checksum}" + ) + + +def _bounded_statement( + statement: str, limit: Optional[int], offset: Optional[int] +) -> str: + """The statement with LIMIT and OFFSET appended as integers, never as text. + + The service takes paging from the statement itself, so the bounds become + clauses; they are validated integers, so nothing from the caller is spliced in + as SQL text. + """ + if not statement or not statement.strip(): + raise ValueError("statement must be a non-empty SELECT") + bounded = statement.rstrip().rstrip(";") + if limit is not None: + if isinstance(limit, bool) or not isinstance(limit, int): + raise ValueError("limit must be an int") + if not 1 <= limit <= MAX_SQL_LIMIT: + raise ValueError(f"limit must be between 1 and {MAX_SQL_LIMIT}") + if _HAS_LIMIT.search(bounded): + raise ValueError("statement already has a LIMIT; pass one or the other") + bounded = f"{bounded} LIMIT {int(limit)}" + if offset is not None: + if isinstance(offset, bool) or not isinstance(offset, int): + raise ValueError("offset must be an int") + if offset < 0: + raise ValueError("offset must be 0 or more") + if _HAS_OFFSET.search(bounded): + raise ValueError("statement already has an OFFSET; pass one or the other") + bounded = f"{bounded} OFFSET {int(offset)}" + return bounded diff --git a/packages/uipath-platform/src/uipath/platform/ontology/ontology.py b/packages/uipath-platform/src/uipath/platform/ontology/ontology.py new file mode 100644 index 000000000..2e3fabbca --- /dev/null +++ b/packages/uipath-platform/src/uipath/platform/ontology/ontology.py @@ -0,0 +1,120 @@ +"""Models for the UiPath Ontology service. + +An ontology is a deployed model of a business domain: its objects, properties and +relationships, with a mapping onto Data Fabric entities. The service exposes it by +id (also its key in the Resource Catalog): a details record, the artifact files it +was installed from, a graph view, and a SQL surface over its objects. +""" + +import hashlib +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, ConfigDict, Field + +ONTOLOGY_DEPLOYED_STATE = "DEPLOYED" +"""The state an ontology must be in for the runtime to use it.""" + + +class OntologyDetails(BaseModel): + """An ontology as the catalog describes it. + + ``name`` is the service identifier the runtime addresses; ``display_name`` is the + label people know it by in the Resource Catalog. + """ + + model_config = ConfigDict( + validate_by_name=True, validate_by_alias=True, extra="allow" + ) + + id: str + name: str + display_name: Optional[str] = Field(default=None, alias="displayName") + description: Optional[str] = None + folder_id: Optional[str] = Field(default=None, alias="folderId") + state: Optional[str] = None + + @property + def is_deployed(self) -> bool: + """Whether the runtime may use this ontology.""" + return self.state == ONTOLOGY_DEPLOYED_STATE + + +class OntologyArtifact(BaseModel): + """One file of an ontology, as the artifact manifest lists it. + + ``checksum`` is the SHA-256 of the file's UTF-8 bytes, lower-case hex; a download + is verified against it and ``size_bytes`` before its content is trusted. + """ + + model_config = ConfigDict( + validate_by_name=True, validate_by_alias=True, extra="allow" + ) + + file_name: str = Field(alias="fileName") + type: str + media_type: str = Field(alias="mediaType") + size_bytes: int = Field(alias="sizeBytes") + checksum: str + created_by: Optional[str] = Field(default=None, alias="createdBy") + create_time: Optional[str] = Field(default=None, alias="createTime") + updated_by: Optional[str] = Field(default=None, alias="updatedBy") + update_time: Optional[str] = Field(default=None, alias="updateTime") + + +class OntologyArtifactContent(BaseModel): + """The bytes of one downloaded artifact, with what the response said about them.""" + + model_config = ConfigDict(arbitrary_types_allowed=True) + + file_name: str + content: bytes + media_type: str + etag: Optional[str] = None + type: Optional[str] = None + + @property + def text(self) -> str: + """The content decoded as UTF-8, which is how every artifact is stored.""" + return self.content.decode("utf-8") + + def sha256(self) -> str: + """The lower-case hex SHA-256 of the content, as the manifest records it.""" + return hashlib.sha256(self.content).hexdigest() + + +class OntologyArtifactIntegrityError(ValueError): + """A downloaded artifact does not match its manifest entry.""" + + +class SqlColumn(BaseModel): + """A column of a SQL answer: its name and the ontology's declared type.""" + + model_config = ConfigDict(extra="allow") + + name: str + type: Optional[str] = None + + +class SqlResult(BaseModel): + """The answer to one SELECT over an ontology's objects. + + Rows are objects keyed by column name, as the service writes them. ``row_count`` + is the number of rows in this answer: without a LIMIT the service reads 50, a + LIMIT is at most 200, and OFFSET reads a later page. + """ + + model_config = ConfigDict( + validate_by_name=True, validate_by_alias=True, extra="allow" + ) + + columns: List[SqlColumn] = Field(default_factory=list) + rows: List[Dict[str, Any]] = Field(default_factory=list) + row_count: int = Field(alias="rowCount") + generated_sql: Optional[str] = Field(default=None, alias="generatedSql") + + @property + def column_names(self) -> List[str]: + """The column names in declared order, or those of the first row.""" + if self.columns: + return [column.name for column in self.columns] + return list(self.rows[0].keys()) if self.rows else [] diff --git a/packages/uipath-platform/tests/common/test_resource_override.py b/packages/uipath-platform/tests/common/test_resource_override.py index fb148124e..284a4bd5e 100644 --- a/packages/uipath-platform/tests/common/test_resource_override.py +++ b/packages/uipath-platform/tests/common/test_resource_override.py @@ -105,3 +105,17 @@ def create( ) finally: _resource_overwrites.reset(token) + + +def test_ontology_binding_parses_as_a_generic_name_and_folder_override() -> None: + from uipath.platform.common._bindings import ResourceOverwriteParser + + overwrite = ResourceOverwriteParser.parse( + "ontology.c0d9f850-ba58-443e-8c54-0bc4bd68f202", + {"name": "nxorders", "folderPath": "Shared/NxOrdersSolution"}, + ) + + assert isinstance(overwrite, GenericResourceOverwrite) + assert overwrite.resource_type == "ontology" + assert overwrite.resource_identifier == "nxorders" + assert overwrite.folder_identifier == "Shared/NxOrdersSolution" diff --git a/packages/uipath-platform/tests/services/test_ontology_service.py b/packages/uipath-platform/tests/services/test_ontology_service.py new file mode 100644 index 000000000..7454e9275 --- /dev/null +++ b/packages/uipath-platform/tests/services/test_ontology_service.py @@ -0,0 +1,396 @@ +import hashlib +import json +from typing import Any + +import pytest +from pytest_httpx import HTTPXMock + +from uipath.platform import UiPath, UiPathApiConfig, UiPathExecutionContext +from uipath.platform.common._bindings import ( + GenericResourceOverwrite, + ResourceOverwriteParser, + _resource_overwrites, +) +from uipath.platform.constants import ( + HEADER_FOLDER_KEY, + HEADER_INTERNAL_ACCOUNT_ID, + HEADER_INTERNAL_TENANT_ID, + HEADER_USER_AGENT, +) +from uipath.platform.ontology import ( + OntologyArtifact, + OntologyArtifactIntegrityError, + OntologyService, + SqlResult, +) +from uipath.platform.ontology._ontology_service import _bounded_statement + +ONTOLOGY_ID = "c0d9f850-ba58-443e-8c54-0bc4bd68f202" +FOLDER_KEY = "f65ca4a9-5c89-49f5-a144-78e510f6ea6c" +SCHEMA = b"Prefix(:=)\nOntology()\n" + + +def _sha(content: bytes) -> str: + return hashlib.sha256(content).hexdigest() + + +def _manifest_entry( + file_name: str, artifact_type: str, content: bytes +) -> dict[str, Any]: + return { + "fileName": file_name, + "type": artifact_type, + "mediaType": "text/owl-functional", + "sizeBytes": len(content), + "checksum": _sha(content), + "createdBy": "someone", + "createTime": "2026-11-18T06:00:00Z", + } + + +@pytest.fixture +def service( + config: UiPathApiConfig, execution_context: UiPathExecutionContext +) -> OntologyService: + return OntologyService(config=config, execution_context=execution_context) + + +@pytest.fixture +def api(base_url: str, org: str, tenant: str) -> str: + return f"{base_url}{org}{tenant}/ontology_/api/v1/ontology" + + +class TestOntologyService: + def test_exposed_on_the_client(self, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("UIPATH_URL", "https://test.uipath.com/org/tenant") + monkeypatch.setenv("UIPATH_ACCESS_TOKEN", "secret") + sdk = UiPath() + assert isinstance(sdk.ontology, OntologyService) + + async def test_get_reads_details_by_id( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}", + json={ + "id": ONTOLOGY_ID, + "name": "nxorders", + "displayName": "Orders (fresh e2e)", + "folderId": FOLDER_KEY, + "state": "DEPLOYED", + "somethingNew": True, + }, + ) + + details = await service.get_async(ONTOLOGY_ID) + + assert details.name == "nxorders" + assert details.display_name == "Orders (fresh e2e)" + assert details.folder_id == FOLDER_KEY + assert details.is_deployed + request = httpx_mock.get_request() + assert request is not None + assert request.method == "GET" + assert HEADER_USER_AGENT in request.headers + assert HEADER_FOLDER_KEY not in request.headers + + async def test_name_lookup_carries_the_folder_header( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/nxorders", + json={"id": ONTOLOGY_ID, "name": "nxorders", "state": "DRAFT"}, + ) + + details = await service.get_async("nxorders", folder_key=FOLDER_KEY) + + assert not details.is_deployed + request = httpx_mock.get_request() + assert request is not None + assert request.headers[HEADER_FOLDER_KEY] == FOLDER_KEY + + def test_sync_get( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}", json={"id": ONTOLOGY_ID, "name": "nxorders"} + ) + assert service.get(ONTOLOGY_ID).id == ONTOLOGY_ID + + async def test_ids_and_file_names_are_path_encoded( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/a%2F..%2Fb/artifact/x%2F..%2Fy.ofn", content=b"x" + ) + + content = await service.get_artifact_async("a/../b", "x/../y.ofn") + + assert content.content == b"x" + + @pytest.mark.parametrize("bad", ["", " "]) + async def test_blank_id_is_refused_before_any_request( + self, service: OntologyService, bad: str + ) -> None: + with pytest.raises(ValueError, match="ontology_id"): + await service.get_async(bad) + + async def test_list_artifacts_returns_the_manifest( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact", + json=[ + _manifest_entry("nxorders.ofn", "schema", SCHEMA), + _manifest_entry("nxorders-summary.json", "summary", b"{}"), + ], + ) + + manifest = await service.list_artifacts_async(ONTOLOGY_ID) + + assert [a.file_name for a in manifest] == [ + "nxorders.ofn", + "nxorders-summary.json", + ] + assert manifest[0].size_bytes == len(SCHEMA) + assert manifest[0].checksum == _sha(SCHEMA) + assert manifest[0].created_by == "someone" + + async def test_list_artifacts_filters_by_type( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact?type=schema", + json=[_manifest_entry("nxorders.ofn", "schema", SCHEMA)], + ) + + manifest = await service.list_artifacts_async(ONTOLOGY_ID, "schema") + + assert len(manifest) == 1 + request = httpx_mock.get_request() + assert request is not None + assert request.url.params["type"] == "schema" + + async def test_get_artifact_returns_bytes_media_type_and_etag( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", + content=SCHEMA, + headers={ + "content-type": "text/owl-functional", + "etag": f'"{_sha(SCHEMA)}"', + }, + ) + + content = await service.get_artifact_async(ONTOLOGY_ID, "nxorders.ofn") + + assert content.content == SCHEMA + assert content.text.startswith("Prefix(") + assert content.media_type == "text/owl-functional" + assert content.etag == f'"{_sha(SCHEMA)}"' + assert content.sha256() == _sha(SCHEMA) + + async def test_get_artifact_verifies_against_the_manifest( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + expected = OntologyArtifact.model_validate( + _manifest_entry("nxorders.ofn", "schema", SCHEMA) + ) + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", content=SCHEMA + ) + + content = await service.get_artifact_async( + ONTOLOGY_ID, "nxorders.ofn", expected=expected + ) + + assert content.type == "schema" + + async def test_get_artifact_refuses_a_checksum_mismatch( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + tampered = SCHEMA[:-1] + b"!" + expected = OntologyArtifact.model_validate( + _manifest_entry("nxorders.ofn", "schema", SCHEMA) + ) + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", content=tampered + ) + + with pytest.raises(OntologyArtifactIntegrityError, match="checksum"): + await service.get_artifact_async( + ONTOLOGY_ID, "nxorders.ofn", expected=expected + ) + + async def test_get_artifact_refuses_a_size_mismatch( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + expected = OntologyArtifact.model_validate( + _manifest_entry("nxorders.ofn", "schema", SCHEMA) + ) + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", content=SCHEMA + b"\n" + ) + + with pytest.raises(OntologyArtifactIntegrityError, match="bytes"): + await service.get_artifact_async( + ONTOLOGY_ID, "nxorders.ofn", expected=expected + ) + + async def test_download_artifacts_verifies_each_file_and_skips_oversize( + self, + httpx_mock: HTTPXMock, + service: OntologyService, + api: str, + caplog: pytest.LogCaptureFixture, + ) -> None: + huge = b"x" * 300 + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact?type=schema", + json=[ + _manifest_entry("nxorders.ofn", "schema", SCHEMA), + _manifest_entry("huge.ofn", "schema", huge), + ], + ) + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", content=SCHEMA + ) + + with caplog.at_level("WARNING"): + contents = await service.download_artifacts_async( + ONTOLOGY_ID, "schema", max_bytes=200 + ) + + assert [c.file_name for c in contents] == ["nxorders.ofn"] + assert contents[0].type == "schema" + assert "huge.ofn" in caplog.text + # the oversize file was never requested + assert len(httpx_mock.get_requests()) == 2 + + async def test_get_graph_returns_the_raw_view( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + graph = {"objects": [{"name": "SalesOrder"}], "relationships": []} + httpx_mock.add_response(url=f"{api}/{ONTOLOGY_ID}/graph", json=graph) + + assert await service.get_graph_async(ONTOLOGY_ID) == graph + + async def test_execute_sql_posts_statement_and_params( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/sql", + json={ + "columns": [{"name": "name", "type": "xsd:string"}], + "rows": [{"name": "Ana"}, {"name": "Bo"}], + "rowCount": 2, + }, + ) + + result = await service.execute_sql_async( + ONTOLOGY_ID, + "SELECT name FROM Supplier WHERE country = :c", + {"c": "RO"}, + limit=2, + offset=4, + ) + + assert isinstance(result, SqlResult) + assert result.row_count == 2 + assert result.column_names == ["name"] + assert result.rows[1]["name"] == "Bo" + request = httpx_mock.get_request() + assert request is not None + assert request.method == "POST" + body = json.loads(request.content) + assert body["params"] == {"c": "RO"} + assert body["statement"] == ( + "SELECT name FROM Supplier WHERE country = :c LIMIT 2 OFFSET 4" + ) + + async def test_execute_sql_without_declared_columns( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/sql", + json={"rows": [{"anything": "at all"}], "rowCount": 1}, + ) + + result = await service.execute_sql_async(ONTOLOGY_ID, "SELECT 1") + + assert result.column_names == ["anything"] + + async def test_local_override_redirects_and_injects_routing_headers( + self, + httpx_mock: HTTPXMock, + service: OntologyService, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setenv("UIPATH_SERVICE_URL_ONTOLOGY", "http://localhost:5002") + monkeypatch.setenv("UIPATH_TENANT_ID", "tenant-id") + monkeypatch.setenv("UIPATH_ORGANIZATION_ID", "org-id") + httpx_mock.add_response( + url=f"http://localhost:5002/api/v1/ontology/{ONTOLOGY_ID}", + json={"id": ONTOLOGY_ID, "name": "nxorders"}, + ) + + await service.get_async(ONTOLOGY_ID) + + request = httpx_mock.get_request() + assert request is not None + assert request.headers[HEADER_INTERNAL_TENANT_ID] == "tenant-id" + assert request.headers[HEADER_INTERNAL_ACCOUNT_ID] == "org-id" + + async def test_an_ontology_binding_repoints_the_call( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + overwrite = ResourceOverwriteParser.parse( + f"ontology.{ONTOLOGY_ID}", + {"name": "nxorders-prod", "folderPath": "Finance/Prod"}, + ) + assert isinstance(overwrite, GenericResourceOverwrite) + httpx_mock.add_response( + url=f"{api}/nxorders-prod", + json={"id": "other", "name": "nxorders-prod", "state": "DEPLOYED"}, + ) + token = _resource_overwrites.set({f"ontology.{ONTOLOGY_ID}": overwrite}) + try: + details = await service.get_async(ONTOLOGY_ID) + finally: + _resource_overwrites.reset(token) + + assert details.name == "nxorders-prod" + request = httpx_mock.get_request() + assert request is not None + assert "x-uipath-folderpath" in {k.lower() for k in request.headers.keys()} + + +class TestBoundedStatement: + def test_no_bounds_leaves_the_statement_alone(self) -> None: + assert _bounded_statement("SELECT 1;", None, None) == "SELECT 1" + + def test_appends_limit_and_offset_as_integers(self) -> None: + assert ( + _bounded_statement("SELECT a FROM B ORDER BY a", 10, 20) + == "SELECT a FROM B ORDER BY a LIMIT 10 OFFSET 20" + ) + + @pytest.mark.parametrize("limit", [0, 201, True, "5"]) + def test_rejects_a_limit_out_of_range_or_not_an_int(self, limit: Any) -> None: + with pytest.raises(ValueError, match="limit"): + _bounded_statement("SELECT 1", limit, None) + + def test_rejects_a_negative_offset(self) -> None: + with pytest.raises(ValueError, match="offset"): + _bounded_statement("SELECT 1", None, -1) + + def test_refuses_to_double_a_clause(self) -> None: + with pytest.raises(ValueError, match="already has a LIMIT"): + _bounded_statement("SELECT 1 LIMIT 5", 10, None) + with pytest.raises(ValueError, match="already has an OFFSET"): + _bounded_statement("SELECT 1 OFFSET 5", None, 10) + + def test_rejects_a_blank_statement(self) -> None: + with pytest.raises(ValueError, match="non-empty"): + _bounded_statement(" ", None, None) diff --git a/packages/uipath-platform/uv.lock b/packages/uipath-platform/uv.lock index fb0a677d2..7e1f56d9b 100644 --- a/packages/uipath-platform/uv.lock +++ b/packages/uipath-platform/uv.lock @@ -1095,7 +1095,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.3.10" +version = "0.3.11" source = { editable = "." } dependencies = [ { name = "anyio" }, diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock index 2134be71c..7c61a7798 100644 --- a/packages/uipath/uv.lock +++ b/packages/uipath/uv.lock @@ -2762,7 +2762,7 @@ wheels = [ [[package]] name = "uipath-platform" -version = "0.3.10" +version = "0.3.11" source = { editable = "../uipath-platform" } dependencies = [ { name = "anyio" }, From 36c47ee1116a20587550d93925c2855dc8d70e85 Mon Sep 17 00:00:00 2001 From: Mani337 Date: Wed, 18 Nov 2026 16:01:56 +0530 Subject: [PATCH 2/4] refactor(ontology): drop the limit and offset arguments from execute_sql Paging is written in the statement itself; the service reads 50 rows without a LIMIT and caps a LIMIT at 200. Appending clauses to raw SQL could match :limit parameters or literals and could land inside a trailing comment. Co-Authored-By: Claude Opus 5.5 --- .../src/uipath/platform/ontology/__init__.py | 2 - .../platform/ontology/_ontology_service.py | 62 ++++--------------- .../tests/services/test_ontology_service.py | 39 +++--------- 3 files changed, 20 insertions(+), 83 deletions(-) diff --git a/packages/uipath-platform/src/uipath/platform/ontology/__init__.py b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py index 592ee27eb..bab614a60 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/__init__.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py @@ -7,7 +7,6 @@ from ._ontology_service import ( DEFAULT_MAX_ARTIFACT_BYTES, - MAX_SQL_LIMIT, OntologyService, ) from .ontology import ( @@ -22,7 +21,6 @@ __all__ = [ "DEFAULT_MAX_ARTIFACT_BYTES", - "MAX_SQL_LIMIT", "ONTOLOGY_DEPLOYED_STATE", "OntologyArtifact", "OntologyArtifactContent", diff --git a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py index 36edbc8a2..a431539fa 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py @@ -9,7 +9,6 @@ """ import logging -import re from typing import Any, Dict, List, Optional from urllib.parse import quote @@ -36,12 +35,6 @@ #: What ``download_artifacts`` puts in a prompt at most, per file. DEFAULT_MAX_ARTIFACT_BYTES = 256_000 -#: The service reads 50 rows without a LIMIT and caps a LIMIT at 200. -MAX_SQL_LIMIT = 200 - -_HAS_LIMIT = re.compile(r"\blimit\b", re.IGNORECASE) -_HAS_OFFSET = re.compile(r"\boffset\b", re.IGNORECASE) - def _segment(value: str, what: str) -> str: """One URL path segment, encoded so an id or file name can never add a path.""" @@ -379,8 +372,6 @@ def execute_sql( statement: str, params: Optional[Dict[str, Any]] = None, *, - limit: Optional[int] = None, - offset: Optional[int] = None, folder_key: Optional[str] = None, folder_path: Optional[str] = None, ) -> SqlResult: @@ -391,14 +382,13 @@ def execute_sql( the mapped entities and runs it with the caller's permissions. Values go in ``params``, never in the statement text. + Paging is part of the statement: without a LIMIT the service reads 50 rows, + a LIMIT is at most 200, and OFFSET with ORDER BY reads a later page. + Args: ontology_id: The ontology's id, or its name with a folder. statement: The SELECT, with ``:name`` placeholders. params: Values for the placeholders. - limit: Rows to read, at most 200. Without one the service reads 50. - Appended as a LIMIT clause; the statement must not have one already. - offset: Rows to skip, for a later page; pair with ORDER BY. Appended as - an OFFSET clause; the statement must not have one already. folder_key: The key of the ontology's folder; needed when addressing by name. folder_path: The path of the ontology's folder; exclusive with ``folder_key``. @@ -406,12 +396,9 @@ def execute_sql( SqlResult: columns, rows as objects, and the row count. Raises: - ValueError: If the statement is blank, a bound is out of range, or a - bound is given for a statement that already has that clause. + ValueError: If the statement is blank. """ - spec = self._sql_spec( - ontology_id, statement, params, limit, offset, folder_key, folder_path - ) + spec = self._sql_spec(ontology_id, statement, params, folder_key, folder_path) response = self.request( spec.method, url=spec.endpoint, json=spec.json, headers=spec.headers ) @@ -429,15 +416,11 @@ async def execute_sql_async( statement: str, params: Optional[Dict[str, Any]] = None, *, - limit: Optional[int] = None, - offset: Optional[int] = None, folder_key: Optional[str] = None, folder_path: Optional[str] = None, ) -> SqlResult: """Run one SELECT over the ontology's objects. See :meth:`execute_sql`.""" - spec = self._sql_spec( - ontology_id, statement, params, limit, offset, folder_key, folder_path - ) + spec = self._sql_spec(ontology_id, statement, params, folder_key, folder_path) response = await self.request_async( spec.method, url=spec.endpoint, json=spec.json, headers=spec.headers ) @@ -505,8 +488,6 @@ def _sql_spec( ontology_id: str, statement: str, params: Optional[Dict[str, Any]], - limit: Optional[int], - offset: Optional[int], folder_key: Optional[str], folder_path: Optional[str], ) -> RequestSpec: @@ -514,7 +495,7 @@ def _sql_spec( method="POST", endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/sql"), json={ - "statement": _bounded_statement(statement, limit, offset), + "statement": _checked_statement(statement), "params": params or {}, }, headers=header_folder(folder_key, folder_path), @@ -570,32 +551,11 @@ def _verify(content: OntologyArtifactContent, expected: OntologyArtifact) -> Non ) -def _bounded_statement( - statement: str, limit: Optional[int], offset: Optional[int] -) -> str: - """The statement with LIMIT and OFFSET appended as integers, never as text. +def _checked_statement(statement: str) -> str: + """The statement without trailing whitespace or ``;``, once it is known not blank. - The service takes paging from the statement itself, so the bounds become - clauses; they are validated integers, so nothing from the caller is spliced in - as SQL text. + Nothing is appended, so a trailing comment cannot swallow any clause. """ if not statement or not statement.strip(): raise ValueError("statement must be a non-empty SELECT") - bounded = statement.rstrip().rstrip(";") - if limit is not None: - if isinstance(limit, bool) or not isinstance(limit, int): - raise ValueError("limit must be an int") - if not 1 <= limit <= MAX_SQL_LIMIT: - raise ValueError(f"limit must be between 1 and {MAX_SQL_LIMIT}") - if _HAS_LIMIT.search(bounded): - raise ValueError("statement already has a LIMIT; pass one or the other") - bounded = f"{bounded} LIMIT {int(limit)}" - if offset is not None: - if isinstance(offset, bool) or not isinstance(offset, int): - raise ValueError("offset must be an int") - if offset < 0: - raise ValueError("offset must be 0 or more") - if _HAS_OFFSET.search(bounded): - raise ValueError("statement already has an OFFSET; pass one or the other") - bounded = f"{bounded} OFFSET {int(offset)}" - return bounded + return statement.rstrip().rstrip(";") diff --git a/packages/uipath-platform/tests/services/test_ontology_service.py b/packages/uipath-platform/tests/services/test_ontology_service.py index 7454e9275..b7cd311e8 100644 --- a/packages/uipath-platform/tests/services/test_ontology_service.py +++ b/packages/uipath-platform/tests/services/test_ontology_service.py @@ -23,7 +23,7 @@ OntologyService, SqlResult, ) -from uipath.platform.ontology._ontology_service import _bounded_statement +from uipath.platform.ontology._ontology_service import _checked_statement ONTOLOGY_ID = "c0d9f850-ba58-443e-8c54-0bc4bd68f202" FOLDER_KEY = "f65ca4a9-5c89-49f5-a144-78e510f6ea6c" @@ -292,8 +292,6 @@ async def test_execute_sql_posts_statement_and_params( ONTOLOGY_ID, "SELECT name FROM Supplier WHERE country = :c", {"c": "RO"}, - limit=2, - offset=4, ) assert isinstance(result, SqlResult) @@ -305,9 +303,7 @@ async def test_execute_sql_posts_statement_and_params( assert request.method == "POST" body = json.loads(request.content) assert body["params"] == {"c": "RO"} - assert body["statement"] == ( - "SELECT name FROM Supplier WHERE country = :c LIMIT 2 OFFSET 4" - ) + assert body["statement"] == "SELECT name FROM Supplier WHERE country = :c" async def test_execute_sql_without_declared_columns( self, httpx_mock: HTTPXMock, service: OntologyService, api: str @@ -366,31 +362,14 @@ async def test_an_ontology_binding_repoints_the_call( assert "x-uipath-folderpath" in {k.lower() for k in request.headers.keys()} -class TestBoundedStatement: - def test_no_bounds_leaves_the_statement_alone(self) -> None: - assert _bounded_statement("SELECT 1;", None, None) == "SELECT 1" - - def test_appends_limit_and_offset_as_integers(self) -> None: - assert ( - _bounded_statement("SELECT a FROM B ORDER BY a", 10, 20) - == "SELECT a FROM B ORDER BY a LIMIT 10 OFFSET 20" - ) - - @pytest.mark.parametrize("limit", [0, 201, True, "5"]) - def test_rejects_a_limit_out_of_range_or_not_an_int(self, limit: Any) -> None: - with pytest.raises(ValueError, match="limit"): - _bounded_statement("SELECT 1", limit, None) - - def test_rejects_a_negative_offset(self) -> None: - with pytest.raises(ValueError, match="offset"): - _bounded_statement("SELECT 1", None, -1) +class TestCheckedStatement: + def test_leaves_paging_words_and_comments_alone(self) -> None: + statement = "SELECT n FROM Supplier WHERE n < :limit ORDER BY n -- page" + assert _checked_statement(statement + "\n") == statement - def test_refuses_to_double_a_clause(self) -> None: - with pytest.raises(ValueError, match="already has a LIMIT"): - _bounded_statement("SELECT 1 LIMIT 5", 10, None) - with pytest.raises(ValueError, match="already has an OFFSET"): - _bounded_statement("SELECT 1 OFFSET 5", None, 10) + def test_drops_a_trailing_semicolon(self) -> None: + assert _checked_statement("SELECT 1; ") == "SELECT 1" def test_rejects_a_blank_statement(self) -> None: with pytest.raises(ValueError, match="non-empty"): - _bounded_statement(" ", None, None) + _checked_statement(" ") From c143bab5c803cdc8c587551e32f83851caf86886 Mon Sep 17 00:00:00 2001 From: Mani337 Date: Thu, 19 Nov 2026 03:17:33 +0530 Subject: [PATCH 3/4] fix(ontology): report skipped artifacts, download in parallel, send a GUID folder as the key download_artifacts now returns the files and the entries skipped for size, and the async variant fetches files concurrently in manifest order. A binding folder that is a GUID (the packager's folder key) is sent as the folder key header instead of a path. Co-Authored-By: Claude Opus 5.5 --- .../src/uipath/platform/common/_bindings.py | 2 + .../src/uipath/platform/ontology/__init__.py | 4 + .../platform/ontology/_ontology_service.py | 113 +++++++++++++----- .../src/uipath/platform/ontology/ontology.py | 21 ++++ .../tests/services/test_ontology_service.py | 73 ++++++++++- 5 files changed, 178 insertions(+), 35 deletions(-) diff --git a/packages/uipath-platform/src/uipath/platform/common/_bindings.py b/packages/uipath-platform/src/uipath/platform/common/_bindings.py index 8363e3b8a..ac3ebe59c 100644 --- a/packages/uipath-platform/src/uipath/platform/common/_bindings.py +++ b/packages/uipath-platform/src/uipath/platform/common/_bindings.py @@ -62,6 +62,8 @@ class GenericResourceOverwrite(ResourceOverwrite): "remoteA2aAgent", "memorySpace", "businessRule", + # The Agents packager fills an ontology binding's folderPath with the folder + # key (a GUID); OntologyService sends a GUID folder as the key, not a path. "ontology", ] name: str = Field(alias="name") diff --git a/packages/uipath-platform/src/uipath/platform/ontology/__init__.py b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py index bab614a60..b5700bef9 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/__init__.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/__init__.py @@ -11,15 +11,18 @@ ) from .ontology import ( ONTOLOGY_DEPLOYED_STATE, + ArtifactDownload, OntologyArtifact, OntologyArtifactContent, OntologyArtifactIntegrityError, OntologyDetails, + SkippedArtifact, SqlColumn, SqlResult, ) __all__ = [ + "ArtifactDownload", "DEFAULT_MAX_ARTIFACT_BYTES", "ONTOLOGY_DEPLOYED_STATE", "OntologyArtifact", @@ -27,6 +30,7 @@ "OntologyArtifactIntegrityError", "OntologyDetails", "OntologyService", + "SkippedArtifact", "SqlColumn", "SqlResult", ] diff --git a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py index a431539fa..d8aab5278 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py @@ -8,8 +8,10 @@ does: ``BaseService.request`` redirects the call and injects the routing headers. """ +import asyncio import logging -from typing import Any, Dict, List, Optional +import uuid +from typing import Any, Dict, List, Optional, Tuple from urllib.parse import quote from uipath.core.tracing import traced @@ -21,10 +23,12 @@ from ..common._folder_context import header_folder from ..common._models import Endpoint, RequestSpec from .ontology import ( + ArtifactDownload, OntologyArtifact, OntologyArtifactContent, OntologyArtifactIntegrityError, OntologyDetails, + SkippedArtifact, SqlResult, ) @@ -35,6 +39,32 @@ #: What ``download_artifacts`` puts in a prompt at most, per file. DEFAULT_MAX_ARTIFACT_BYTES = 256_000 +#: How many artifacts ``download_artifacts_async`` fetches at once. +MAX_CONCURRENT_DOWNLOADS = 4 + + +def _folder_headers( + folder_key: Optional[str], folder_path: Optional[str] +) -> Dict[str, str]: + """Folder headers for a call, sending a folder key that arrived as a path. + + A deploy-time override carries the ontology's folder in ``folderPath``, and the + Agents packager fills it with the folder key, a GUID. Sent as a path, the service + would look up a folder by that name and answer 404, so a GUID goes as the key, + as the entity planner does for the same binding shape. + """ + if folder_key is None and folder_path and _is_guid(folder_path): + return header_folder(folder_path, None) + return header_folder(folder_key, folder_path) + + +def _is_guid(value: str) -> bool: + try: + uuid.UUID(value) + except ValueError: + return False + return True + def _segment(value: str, what: str) -> str: """One URL path segment, encoded so an id or file name can never add a path.""" @@ -248,11 +278,12 @@ def download_artifacts( max_bytes: int = DEFAULT_MAX_ARTIFACT_BYTES, folder_key: Optional[str] = None, folder_path: Optional[str] = None, - ) -> List[OntologyArtifactContent]: + ) -> ArtifactDownload: """Download every artifact of a type, verified against the manifest. - Files larger than ``max_bytes`` are skipped with a warning, since they are - meant for a prompt and would not fit. + Files larger than ``max_bytes`` are not downloaded. They come back in + ``skipped`` with their size, so a caller can tell a file that was too large + from one the ontology does not have. Args: ontology_id: The ontology's id, or its name with a folder. @@ -262,23 +293,24 @@ def download_artifacts( folder_path: The path of the ontology's folder; exclusive with ``folder_key``. Returns: - List[OntologyArtifactContent]: the verified files, in manifest order. + ArtifactDownload: the verified files in manifest order, and the entries + skipped for size. """ manifest = self.list_artifacts( ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path ) - contents: List[OntologyArtifactContent] = [] - for entry in self._within_budget(manifest, max_bytes): - contents.append( - self.get_artifact( - ontology_id, - entry.file_name, - expected=entry, - folder_key=folder_key, - folder_path=folder_path, - ) + kept, skipped = self._split_by_size(manifest, max_bytes) + files = [ + self.get_artifact( + ontology_id, + entry.file_name, + expected=entry, + folder_key=folder_key, + folder_path=folder_path, ) - return contents + for entry in kept + ] + return ArtifactDownload(files=files, skipped=skipped) @traced(name="ontology_download_artifacts", run_type="uipath") async def download_artifacts_async( @@ -289,23 +321,31 @@ async def download_artifacts_async( max_bytes: int = DEFAULT_MAX_ARTIFACT_BYTES, folder_key: Optional[str] = None, folder_path: Optional[str] = None, - ) -> List[OntologyArtifactContent]: - """Download every artifact of a type. See :meth:`download_artifacts`.""" + ) -> ArtifactDownload: + """Download every artifact of a type. See :meth:`download_artifacts`. + + The files are fetched concurrently, at most ``MAX_CONCURRENT_DOWNLOADS`` at a + time, and keep manifest order. Any failed or mismatched download fails the + call, as in the sync variant. + """ manifest = await self.list_artifacts_async( ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path ) - contents: List[OntologyArtifactContent] = [] - for entry in self._within_budget(manifest, max_bytes): - contents.append( - await self.get_artifact_async( + kept, skipped = self._split_by_size(manifest, max_bytes) + limit = asyncio.Semaphore(MAX_CONCURRENT_DOWNLOADS) + + async def fetch(entry: OntologyArtifact) -> OntologyArtifactContent: + async with limit: + return await self.get_artifact_async( ontology_id, entry.file_name, expected=entry, folder_key=folder_key, folder_path=folder_path, ) - ) - return contents + + files = await asyncio.gather(*(fetch(entry) for entry in kept)) + return ArtifactDownload(files=list(files), skipped=skipped) # ── graph ──────────────────────────────────────────────────────────── @@ -435,7 +475,7 @@ def _details_spec( return RequestSpec( method="GET", endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}"), - headers=header_folder(folder_key, folder_path), + headers=_folder_headers(folder_key, folder_path), ) @staticmethod @@ -454,7 +494,7 @@ def _manifest_spec( f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/artifact" ), params=params, - headers=header_folder(folder_key, folder_path), + headers=_folder_headers(folder_key, folder_path), ) @staticmethod @@ -470,7 +510,7 @@ def _download_spec( f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/artifact/" f"{_segment(file_name, 'file_name')}" ), - headers=header_folder(folder_key, folder_path), + headers=_folder_headers(folder_key, folder_path), ) @staticmethod @@ -480,7 +520,7 @@ def _graph_spec( return RequestSpec( method="GET", endpoint=Endpoint(f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/graph"), - headers=header_folder(folder_key, folder_path), + headers=_folder_headers(folder_key, folder_path), ) @staticmethod @@ -498,16 +538,17 @@ def _sql_spec( "statement": _checked_statement(statement), "params": params or {}, }, - headers=header_folder(folder_key, folder_path), + headers=_folder_headers(folder_key, folder_path), ) # ── helpers ────────────────────────────────────────────────────────── @staticmethod - def _within_budget( + def _split_by_size( manifest: List[OntologyArtifact], max_bytes: int - ) -> List[OntologyArtifact]: + ) -> Tuple[List[OntologyArtifact], List[SkippedArtifact]]: kept: List[OntologyArtifact] = [] + skipped: List[SkippedArtifact] = [] for entry in manifest: if entry.size_bytes > max_bytes: logger.warning( @@ -516,9 +557,17 @@ def _within_budget( entry.size_bytes, max_bytes, ) + skipped.append( + SkippedArtifact( + file_name=entry.file_name, + type=entry.type, + size_bytes=entry.size_bytes, + reason=f"over the {max_bytes} byte cap", + ) + ) continue kept.append(entry) - return kept + return kept, skipped @staticmethod def _to_content( diff --git a/packages/uipath-platform/src/uipath/platform/ontology/ontology.py b/packages/uipath-platform/src/uipath/platform/ontology/ontology.py index 2e3fabbca..762b83159 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/ontology.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/ontology.py @@ -86,6 +86,27 @@ class OntologyArtifactIntegrityError(ValueError): """A downloaded artifact does not match its manifest entry.""" +class SkippedArtifact(BaseModel): + """A manifest entry ``download_artifacts`` left out, and why.""" + + file_name: str + type: str + size_bytes: int + reason: str + + +class ArtifactDownload(BaseModel): + """What ``download_artifacts`` fetched and what it skipped. + + ``files`` are verified against the manifest and keep its order. ``skipped`` lists + the entries over the size cap, so a caller can tell a missing file from one that + was too large and say so in its trace. + """ + + files: List[OntologyArtifactContent] = Field(default_factory=list) + skipped: List[SkippedArtifact] = Field(default_factory=list) + + class SqlColumn(BaseModel): """A column of a SQL answer: its name and the ontology's declared type.""" diff --git a/packages/uipath-platform/tests/services/test_ontology_service.py b/packages/uipath-platform/tests/services/test_ontology_service.py index b7cd311e8..2cf22254a 100644 --- a/packages/uipath-platform/tests/services/test_ontology_service.py +++ b/packages/uipath-platform/tests/services/test_ontology_service.py @@ -18,6 +18,7 @@ HEADER_USER_AGENT, ) from uipath.platform.ontology import ( + ArtifactDownload, OntologyArtifact, OntologyArtifactIntegrityError, OntologyService, @@ -258,16 +259,59 @@ async def test_download_artifacts_verifies_each_file_and_skips_oversize( ) with caplog.at_level("WARNING"): - contents = await service.download_artifacts_async( + result = await service.download_artifacts_async( ONTOLOGY_ID, "schema", max_bytes=200 ) - assert [c.file_name for c in contents] == ["nxorders.ofn"] - assert contents[0].type == "schema" + assert isinstance(result, ArtifactDownload) + assert [c.file_name for c in result.files] == ["nxorders.ofn"] + assert result.files[0].type == "schema" + assert [(s.file_name, s.size_bytes) for s in result.skipped] == [ + ("huge.ofn", 300) + ] + assert "200 byte cap" in result.skipped[0].reason assert "huge.ofn" in caplog.text # the oversize file was never requested assert len(httpx_mock.get_requests()) == 2 + async def test_download_artifacts_keeps_manifest_order_across_files( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + files = {f"part{i}.ofn": f"Ontology()".encode() for i in range(6)} + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact?type=schema", + json=[_manifest_entry(n, "schema", c) for n, c in files.items()], + ) + for name, content in files.items(): + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/{name}", content=content + ) + + result = await service.download_artifacts_async(ONTOLOGY_ID, "schema") + + assert [c.file_name for c in result.files] == list(files) + assert [c.content for c in result.files] == list(files.values()) + assert result.skipped == [] + + def test_sync_download_artifacts_reports_skipped( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact", + json=[ + _manifest_entry("nxorders.ofn", "schema", SCHEMA), + _manifest_entry("mapping.yml", "mapping", b"y" * 500), + ], + ) + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/nxorders.ofn", content=SCHEMA + ) + + result = service.download_artifacts(ONTOLOGY_ID, max_bytes=200) + + assert [c.file_name for c in result.files] == ["nxorders.ofn"] + assert [s.type for s in result.skipped] == ["mapping"] + async def test_get_graph_returns_the_raw_view( self, httpx_mock: HTTPXMock, service: OntologyService, api: str ) -> None: @@ -361,6 +405,29 @@ async def test_an_ontology_binding_repoints_the_call( assert request is not None assert "x-uipath-folderpath" in {k.lower() for k in request.headers.keys()} + async def test_a_binding_folder_key_goes_as_the_key_not_a_path( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + # The Agents packager writes the ontology's folder key into folderPath. + overwrite = ResourceOverwriteParser.parse( + f"ontology.{ONTOLOGY_ID}", + {"name": "nxorders-prod", "folderPath": FOLDER_KEY}, + ) + httpx_mock.add_response( + url=f"{api}/nxorders-prod", + json={"id": "other", "name": "nxorders-prod", "state": "DEPLOYED"}, + ) + token = _resource_overwrites.set({f"ontology.{ONTOLOGY_ID}": overwrite}) + try: + await service.get_async(ONTOLOGY_ID) + finally: + _resource_overwrites.reset(token) + + request = httpx_mock.get_request() + assert request is not None + assert request.headers[HEADER_FOLDER_KEY] == FOLDER_KEY + assert "x-uipath-folderpath" not in {k.lower() for k in request.headers.keys()} + class TestCheckedStatement: def test_leaves_paging_words_and_comments_alone(self) -> None: From 255913b3b45038b8bbda510170f7a5bb0f47ea5c Mon Sep 17 00:00:00 2001 From: Mani337 Date: Thu, 19 Nov 2026 12:41:56 +0530 Subject: [PATCH 4/4] feat(ontology): download a single-file artifact by type in one request get_artifact_by_type(_async) calls GET /ontology/{id}/artifact/type/{type}, so a caller gets the schema without listing the manifest first. The content is verified against the checksum in the ETag. Co-Authored-By: Claude Opus 5.5 --- .../platform/ontology/_ontology_service.py | 103 ++++++++++++++++++ .../tests/services/test_ontology_service.py | 49 +++++++++ 2 files changed, 152 insertions(+) diff --git a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py index d8aab5278..0d134255d 100644 --- a/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py +++ b/packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py @@ -11,6 +11,7 @@ import asyncio import logging import uuid +from email.message import Message from typing import Any, Dict, List, Optional, Tuple from urllib.parse import quote @@ -269,6 +270,64 @@ async def get_artifact_async( ) return self._to_content(file_name, response, expected) + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_artifact_by_type", run_type="uipath") + def get_artifact_by_type( + self, + ontology_id: str, + artifact_type: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyArtifactContent: + """Download the one artifact of a single-file type, such as the schema. + + One request, no manifest: the service answers the type's file as a download by + name does, and the content is verified against the checksum in its ETag. + + Args: + ontology_id: The ontology's id, or its name with a folder. + artifact_type: A single-file type: ``schema``, ``mapping``, ``summary`` or + ``context``. A type that can hold several files is refused by the + service; list those with :meth:`list_artifacts`. + folder_key: The key of the ontology's folder; needed when addressing by name. + folder_path: The path of the ontology's folder; exclusive with ``folder_key``. + + Returns: + OntologyArtifactContent: the bytes, their media type, file name and ETag. + + Raises: + OntologyArtifactIntegrityError: If the bytes do not match the ETag checksum. + """ + spec = self._by_type_spec(ontology_id, artifact_type, folder_key, folder_path) + response = self.request(spec.method, url=spec.endpoint, headers=spec.headers) + return self._to_typed_content(artifact_type, response) + + @resource_override( + resource_type="ontology", + resource_identifier="ontology_id", + folder_identifier="folder_path", + ) + @traced(name="ontology_get_artifact_by_type", run_type="uipath") + async def get_artifact_by_type_async( + self, + ontology_id: str, + artifact_type: str, + *, + folder_key: Optional[str] = None, + folder_path: Optional[str] = None, + ) -> OntologyArtifactContent: + """Download the one artifact of a single-file type. See :meth:`get_artifact_by_type`.""" + spec = self._by_type_spec(ontology_id, artifact_type, folder_key, folder_path) + response = await self.request_async( + spec.method, url=spec.endpoint, headers=spec.headers + ) + return self._to_typed_content(artifact_type, response) + @traced(name="ontology_download_artifacts", run_type="uipath") def download_artifacts( self, @@ -513,6 +572,22 @@ def _download_spec( headers=_folder_headers(folder_key, folder_path), ) + @staticmethod + def _by_type_spec( + ontology_id: str, + artifact_type: str, + folder_key: Optional[str], + folder_path: Optional[str], + ) -> RequestSpec: + return RequestSpec( + method="GET", + endpoint=Endpoint( + f"{_BASE}/{_segment(ontology_id, 'ontology_id')}/artifact/type/" + f"{_segment(artifact_type, 'artifact_type')}" + ), + headers=_folder_headers(folder_key, folder_path), + ) + @staticmethod def _graph_spec( ontology_id: str, folder_key: Optional[str], folder_path: Optional[str] @@ -584,6 +659,25 @@ def _to_content( _verify(content, expected) return content + @staticmethod + def _to_typed_content(artifact_type: str, response: Any) -> OntologyArtifactContent: + etag = response.headers.get("etag") + content = OntologyArtifactContent( + file_name=_attachment_file_name(response.headers.get("content-disposition")) + or artifact_type, + content=response.content, + media_type=response.headers.get("content-type", ""), + etag=etag, + type=artifact_type, + ) + checksum = (etag or "").strip().removeprefix("W/").strip('"').lower() + if checksum and content.sha256() != checksum: + raise OntologyArtifactIntegrityError( + f"Artifact '{content.file_name}' checksum {content.sha256()} does not " + f"match its ETag {checksum}" + ) + return content + def _verify(content: OntologyArtifactContent, expected: OntologyArtifact) -> None: """Refuse content whose size or SHA-256 differs from the manifest entry.""" @@ -600,6 +694,15 @@ def _verify(content: OntologyArtifactContent, expected: OntologyArtifact) -> Non ) +def _attachment_file_name(disposition: Optional[str]) -> Optional[str]: + """The file name a ``Content-Disposition`` names, preferring the UTF-8 form.""" + if not disposition: + return None + message = Message() + message["content-disposition"] = disposition + return message.get_filename() + + def _checked_statement(statement: str) -> str: """The statement without trailing whitespace or ``;``, once it is known not blank. diff --git a/packages/uipath-platform/tests/services/test_ontology_service.py b/packages/uipath-platform/tests/services/test_ontology_service.py index 2cf22254a..b42319614 100644 --- a/packages/uipath-platform/tests/services/test_ontology_service.py +++ b/packages/uipath-platform/tests/services/test_ontology_service.py @@ -239,6 +239,55 @@ async def test_get_artifact_refuses_a_size_mismatch( ONTOLOGY_ID, "nxorders.ofn", expected=expected ) + async def test_get_artifact_by_type_reads_the_schema_in_one_request( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/type/schema", + content=SCHEMA, + headers={ + "content-type": "text/owl-functional", + "etag": f'"{_sha(SCHEMA)}"', + "content-disposition": ( + "attachment; filename=\"nxorders.ofn\"; filename*=UTF-8''nxorders.ofn" + ), + }, + ) + + content = await service.get_artifact_by_type_async(ONTOLOGY_ID, "schema") + + assert content.content == SCHEMA + assert content.file_name == "nxorders.ofn" + assert content.type == "schema" + assert content.media_type == "text/owl-functional" + assert len(httpx_mock.get_requests()) == 1 + + def test_sync_get_artifact_by_type( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/type/schema", + content=SCHEMA, + headers={"etag": f'"{_sha(SCHEMA)}"'}, + ) + + content = service.get_artifact_by_type(ONTOLOGY_ID, "schema") + + assert content.text == SCHEMA.decode() + assert content.file_name == "schema" + + async def test_get_artifact_by_type_refuses_content_that_misses_its_etag( + self, httpx_mock: HTTPXMock, service: OntologyService, api: str + ) -> None: + httpx_mock.add_response( + url=f"{api}/{ONTOLOGY_ID}/artifact/type/schema", + content=SCHEMA, + headers={"etag": '"0000"'}, + ) + + with pytest.raises(OntologyArtifactIntegrityError, match="ETag"): + await service.get_artifact_by_type_async(ONTOLOGY_ID, "schema") + async def test_download_artifacts_verifies_each_file_and_skips_oversize( self, httpx_mock: HTTPXMock,