Repository navigation
feat(ontology): add an Ontology service client to uipath-platform [DS-9950] - #1999
Conversation
…-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 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
Pagination handling can falsely reject SQL containing LIMIT/OFFSET outside paging clauses and silently ignore requested bounds by appending them inside trailing line comments.
2 open issues
What changed in this PR
Adds sdk.ontology to the UiPath Platform SDK, supporting the agent ontology tool’s migration from Data Fabric to the dedicated Ontology service.
Changes:
- Adds sync and async APIs for ontology details, verified artifact downloads, graph retrieval, and SQL queries with pagination.
- Adds ontology resource bindings and deprecates the Data Fabric ontology-file API.
- Adds service and binding tests and bumps
uipath-platformto 0.3.11.
| File | Description |
|---|---|
packages/uipath/uv.lock |
Updates the platform dependency version. |
packages/uipath-platform/uv.lock |
Aligns the lockfile with version 0.3.11. |
packages/uipath-platform/tests/services/test_ontology_service.py |
Tests service requests, artifact integrity, bindings, and pagination. |
packages/uipath-platform/tests/common/test_resource_override.py |
Tests ontology binding parsing. |
packages/uipath-platform/src/uipath/platform/ontology/ontology.py |
Defines ontology, artifact, and SQL response models. |
packages/uipath-platform/src/uipath/platform/ontology/_ontology_service.py |
Implements the sync and async service APIs. |
packages/uipath-platform/src/uipath/platform/ontology/__init__.py |
Exports the service, models, and constants. |
packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py |
Documents the legacy module’s deprecation. |
packages/uipath-platform/src/uipath/platform/entities/_entities_service.py |
Deprecates the Data Fabric ontology-file method. |
packages/uipath-platform/src/uipath/platform/common/_bindings.py |
Enables ontology resource overrides. |
packages/uipath-platform/src/uipath/platform/_uipath.py |
Exposes the cached sdk.ontology client. |
packages/uipath-platform/pyproject.toml |
Bumps the package version to 0.3.11. |
packages/uipath-platform/CLAUDE.md |
Documents the new service and package directory. |
Review effort: Balanced
| _HAS_LIMIT = re.compile(r"\blimit\b", re.IGNORECASE) | ||
| _HAS_OFFSET = re.compile(r"\boffset\b", re.IGNORECASE) |
There was a problem hiding this comment.
Fixed in 36c47ee by removing the limit and offset arguments. execute_sql now sends the statement as written, so callers put LIMIT and OFFSET in the SQL, and the service applies its 50-row default and 200-row cap. Nothing is appended to the statement any more, so paging words in parameters, literals or comments no longer matter. The new tests cover a :limit parameter and a trailing -- comment.
| """ | ||
| if not statement or not statement.strip(): | ||
| raise ValueError("statement must be a non-empty SELECT") | ||
| bounded = statement.rstrip().rstrip(";") |
There was a problem hiding this comment.
Fixed in 36c47ee by removing the limit and offset arguments. execute_sql now sends the statement as written, so callers put LIMIT and OFFSET in the SQL, and the service applies its 50-row default and 200-row cap. Nothing is appended to the statement any more, so paging words in parameters, literals or comments no longer matter. The new tests cover a :limit parameter and a trailing -- comment.
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 <noreply@anthropic.com>
| ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path | ||
| ) | ||
| contents: List[OntologyArtifactContent] = [] | ||
| for entry in self._within_budget(manifest, max_bytes): |
There was a problem hiding this comment.
Files over max_bytes get dropped with a logger.warning and the method returns a shorter list that looks complete. From the caller's side there's no way to tell "this ontology has no mapping file" from "the mapping file was 300 KB and got skipped", and the agent tool is meant to note exactly that in the trace.
Could we either raise here, or return the skipped entries next to the contents (something like a small result with files and skipped)? The design doc says a too-large schema file should carry on and show up in the trace, which the current shape doesn't let the caller do.
There was a problem hiding this comment.
Basically we are not using this download_artifacts methods in langchain client. Coding agent just added them. But comment still makes sense. Addressed it, so that JIC if any one uses them in the future. It now returns the skipped files along with the downloads, so the caller can log them. Ideally we can remove these methods, but left them for now.
| ontology_id, artifact_type, folder_key=folder_key, folder_path=folder_path | ||
| ) | ||
| contents: List[OntologyArtifactContent] = [] | ||
| for entry in self._within_budget(manifest, max_bytes): |
There was a problem hiding this comment.
Each artifact is awaited one at a time here. An ontology with schema, mapping, rules, summary and context is five sequential round trips on the agent's first tool call, which is already the slow path.
We already depend on anyio, so a task group (or plain asyncio.gather) would bring that down to roughly one round trip. Failure semantics don't change since any single failure aborts the batch either way.
There was a problem hiding this comment.
Switched the async version to download in parallel.
| "remoteA2aAgent", | ||
| "memorySpace", | ||
| "businessRule", | ||
| "ontology", |
There was a problem hiding this comment.
Question on the folder value this override will carry at runtime. GenericResourceOverwrite only has folderPath, and the decorator on OntologyService sends that straight through as the folder path header, which the Ontology service resolves via Orchestrator and 404s (FOLDER_NOT_FOUND) when it doesn't match a path.
The Agents packager fills folderPath from the item's folderId, and for ontologies that field holds the service's folderId, which is the folder key GUID. On the entity side both runtimes already treat that value as an id rather than a path: the C# handler reads the folderPath key into overwriteFolderId, and the Python planner tries path resolution and falls back to using the raw value as a key (#1548 explains why).
Do we know the ontology override will always have been rewritten to a real path by the time it reaches resourceOverwrites? If a GUID can get through (debug runs, or a deploy that keeps the default), the decorator should send it as folder_key instead, or the override should accept folderId the way EntityResourceOverwrite does. If Solutions guarantees a path here, a short note on the model would save the next person the same question.
There was a problem hiding this comment.
Right, the packager puts the folder key there. If the value is a GUID, it now goes as the folder key instead of the path. Addressed it
… 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 <noreply@anthropic.com>
| folder_identifier="folder_path", | ||
| ) | ||
| @traced(name="ontology_get_graph", run_type="uipath") | ||
| async def get_graph_async( |
There was a problem hiding this comment.
Nit: Might be keep one method either sync or async
There was a problem hiding this comment.
Kept both to match the other platform services. The agent uses the async ones, but coded agents tend to use sync.
| folder_identifier="folder_path", | ||
| ) | ||
| @traced(name="ontology_get_artifact", run_type="uipath") | ||
| def get_artifact( |
There was a problem hiding this comment.
This might be calling to RCS right ?
There was a problem hiding this comment.
These are the ontology service's own artifact routes, from ontology #257. RCS only has the catalog entry (id, name, folder), and the agent only uses it at design time, for the ontology picker. At runtime it goes straight to the ontology service.
| folder_identifier="folder_path", | ||
| ) | ||
| @traced(name="ontology_list_artifacts", run_type="uipath") | ||
| def list_artifacts( |
There was a problem hiding this comment.
This API should be referring to RCS and not ontology right ?
There was a problem hiding this comment.
These are the ontology service's own artifact routes, from ontology #257. RCS only has the catalog entry (id, name, folder), and the agent only uses it at design time, for the ontology picker. At runtime it goes straight to the ontology service.
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 <noreply@anthropic.com>
|
🚨 Heads up:
|
|
@venkat202 As discussed, Moved fetching ofn shchema file to a single API call |
main (#1999) released uipath-platform 0.3.11, so move this PR's bump to 0.3.12 and raise uipath's floor on it accordingly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>




What
Adds
sdk.ontology(OntologyService) for the Ontology service (ontology_/api/v1):get— an ontology by idlist_artifacts,get_artifact,download_artifacts— its artifact manifest and files, with a checksum checkget_artifact_by_type— the one file of a single-file type, such as the schema, in a single request (ontology Chore/adjust docs #260)get_graph— its object graphexecute_sql— SQL over its objects; paging is written in the statementEach method has a sync and an async variant.
Also:
ontologybinding type so resource overrides resolve ontologiesEntitiesService.get_ontology_file_async(the Data Fabric ontology file fetch)uipath-platformto 0.3.11Why
The agent ontology tool in uipath-langchain moves from Data Fabric to the Ontology service, which addresses ontologies by id. Validated end to end with a low-code agent on a local robot against alpha.
🤖 Generated with Claude Code