feat(datafabric): standalone ontology tool grounded on OWL + R2RML

[sankalp-uipath]

What

Adds a standalone Data Fabric ontology tool for low-code agents. The agent selects ontologies (not entities); the tool derives the entities it may query from the ontology's R2RML, resolves their schemas, and runs the existing inner SQL sub-graph grounded on both the OWL (semantic schema) and the R2RML (ontology→table/column mapping).

An ontology context (contextType: "datafabricontology") now becomes a tool on its own — no entitySet required in agent.json.

How it works (first invocation, cached)

1. Fetch the ontology's R2RML (critical — it is the entity allow-list) and OWL (grounds the prompt) via EntitiesService.get_ontology_file_async.
2. Parse R2RML with rdflib → the closed (entity_name, folder_path) allow-list, reading one rr:tableName (via rr:logicalTable) + one uipath:folderPath per rr:TriplesMap.
3. Resolve the allow-list concurrently (asyncio.gather): distinct folderPath → folder_key (folders.retrieve_key_async), then name → id (entities.retrieve_by_name_async), and delegate to the SDK's public entities.resolve_entity_set_async to fetch the schemas and build the folder-scoped EntitiesService (routing each entity's queries to its folder). Using the public resolver means the tool builds nothing from SDK internals.
4. Build a dedicated ontology system prompt (OWL + R2RML + entity schemas) and compile the ontology DataFabricGraph — the inner agent still has a single tool, execute_sql.

Everything from the sub-graph down (execute_sql → query_entity_records_async) mirrors the entity tool.

Layout — the entity tool is left untouched

All ontology code lives in its own datafabric_tool/ontology/ subpackage. The entity tool's files are byte-identical to main: datafabric_tool.py, datafabric_subgraph.py, datafabric_prompt_builder.py, and the package __init__.py are unchanged by this PR. context_tool.py is the only shared file touched — it builds the standalone ontology tool for the ontology context (flag-gated) and imports the tool directly from datafabric_tool.ontology.

New — datafabric_tool/ontology/

• ontology_r2rml.py — rdflib-based parser: parse_r2rml_entities() → the (entity_name, folder_path) allow-list (parses Turtle as an RDF graph; R2RMLParseError on invalid Turtle or contract violations).
• ontology_tool.py — resolve_ontology_entities() (the concurrent resolver), DataFabricOntologyQueryHandler, create_datafabric_ontology_tool(); owns the DATAFABRIC_ONTOLOGY_FF flag constant.
• ontology_subgraph.py — a self-contained, prompt-agnostic duplicate of DataFabricGraph (takes a pre-built system_prompt), so the entity sub-graph stays identical to main.
• ontology_prompt_builder.py — the ontology tool's inner prompt (OWL + R2RML + entity schemas), self-contained.
• ontology_fetcher.py — fetch_ontology_file (raw content + media type; raises) + fence_ontology_block.

Design decisions

• Closed allow-list (Option A): the entities the tool can touch are exactly those declared in the ontology's R2RML — the LLM can never widen scope. execute_sql's blast radius = the resolved set.
• uipath:folderPath (a folder path, not a GUID): R2RML has no folder concept and is deployment-agnostic; rr:tableName stays a valid SQL table name. Folder identity is resolved through the trusted folder service, never from mapping content. (Authoring contract documented for the ontology-authoring skill.)
• rdflib parser: the R2RML is parsed as an RDF graph rather than scanned with regexes, so authoring variations (predicate order, whitespace, compact one-line maps, prefix/@base differences) are handled by a real Turtle parser. Validated against the live california-schools mapping fetched from Data Fabric.
• Duplicated, isolated sub-graph: ontology_subgraph.py is an intentional copy of datafabric_subgraph.py so the entity path is not modified. It is excluded from Sonar copy-paste detection (sonar.cpd.exclusions) rather than sharing code, to preserve that isolation.
• No SDK change for the core feature — all new code is in uipath-langchain-python over existing public uipath-platform methods.

Feature flag

• Gated by DataFabricOntologyEnabled (default off), a single shared constant owned by the ontology subpackage.
• Two guards (defense in depth): the tool-factory entry (context_tool — off ⇒ no tool created, feature fully inert) and the handler's lazy init (re-checks before any OWL/R2RML fetch/parse/resolve). Off ⇒ the agent runs exactly as before; the entity tool is flag-independent.

Security

• Entity/folder scope is bounded by the R2RML allow-list; folder keys come only from trusted folder-path resolution (not the LLM).
• execute_sql's single-statement sqlparse guard is unchanged.
• OWL/R2RML are injected as prompt context; a hostile ontology can only reference entities it itself declares (Option A), which still pass folder-scoped resolution.

Testing

• Unit tests for the parser (incl. the live california-schools shape), resolver (concurrent folder-key + by-name id fetch, delegation to resolve_entity_set_async), the ontology prompt builder, the ontology sub-graph nodes, the factory, and the flag guard. New ontology modules are covered ≥99%.
• Live e2e on alpha (datafabric/ab, gpt-5.4, california-schools ontology): flag prefetched on → R2RML + OWL fetched → folderPath resolved → 3 entities resolved by name → OWL+R2RML-grounded SQL (join on the R2RML FK) executed folder-scoped → correct answer. Confirmed retrieve_by_name (/metadata) returns populated field schemas.

Notes / dependencies

• Depends on SDK #1728 (merged), which ships the ontology binding: ontologySet on the context, AgentContextType.DATA_FABRIC_ONTOLOGY, get_ontology_file_async, and resolve_entity_set_async. The feature needs uipath>=2.13.2 / uipath-platform>=0.2.1; pyproject.toml currently pins the higher uipath>=2.13.5 / uipath-platform>=0.2.4 adopted from main. No env-based configuration fallback is used — ontologies come only from the context's ontologySet.
• Adds rdflib>=7.0.0, <8.0.0 for the R2RML parser.
• Runtime flag delivery also requires DataFabricOntologyEnabled in uipath-agents-python's _ALL_FLAGS prefetch + the gitops flag deployed for the target tenants (both already in place from the prior work).
• Authoring dependency: ontologies must be published with a uipath:folderPath per rr:TriplesMap (authoring-skill guidelines provided) — otherwise resolution fails loudly by design.
• Supersedes the earlier "inject ontology into the entity tool" approach and folds in the R2RML grounding work.

[Copilot]

Pull request overview

Adds an optional fetch_ontology inner tool to the Data Fabric SQL sub-agent so the inner LLM can retrieve a configured ontology’s OWL schema from the QueryEngine REST API and use it to generate semantically-correct SQL.

Changes:

• Introduces an ontology REST client (fetch_ontology_owl) with name validation and size limiting.
• Adds a fetch_ontology leaf tool with an instance-level cache and wires it into the inner Data Fabric subgraph alongside execute_sql.
• Threads ontology_name / folder_key into the Data Fabric tool construction path (with an env-var fallback).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/uipath_langchain/agent/tools/datafabric_tool/ontology_fetch_tool.py	New leaf tool (fetch_ontology) and cached fetcher wrapper for inner SQL agent use.
src/uipath_langchain/agent/tools/datafabric_tool/ontology_client.py	New client helper to fetch OWL content via EntitiesService.request_async, including name validation and payload cap.
src/uipath_langchain/agent/tools/datafabric_tool/models.py	Adds an intentionally-empty args schema (OntologyFetchInput) for the new tool.
src/uipath_langchain/agent/tools/datafabric_tool/datafabric_tool.py	Plumbs ontology_name / folder_key into the query handler creation (currently with env-var fallback).
src/uipath_langchain/agent/tools/datafabric_tool/datafabric_subgraph.py	Adds optional fetch_ontology tool binding and dispatch-by-tool-name inside the inner subgraph.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 2 comments.

[UIPath-Harshit]

PR Review: feat(datafabric): standalone ontology tool grounded on OWL + R2RML

Overall: Well-structured, thoughtful PR. The isolation strategy (separate subpackage, entity tool untouched) is the right call. A few concerns below.

Positives

1. Clean isolation — all ontology code in datafabric_tool/ontology/, entity tool byte-identical to main. Sonar CPD exclusion is the right trade-off for keeping them decoupled.
2. Closed allow-list (Option A) — entities bounded by R2RML, LLM can't widen scope. Good security posture.
3. rdflib over regex — real Turtle parser handles authoring variations correctly. Tests validate compact/multi-line/reordered syntax.
4. Defense in depth — flag checked at both tool creation (context_tool.py) and lazy init (_ensure_graph). Tool is fully inert when off.
5. OWL degrades gracefully, R2RML is fatal — correct priority since R2RML is the allow-list.
6. Test coverage — comprehensive unit tests for parser, resolver, subgraph, prompt builder, fetcher. Edge cases covered well.

Concerns

1. rdflib as a new dependency (medium)

• rdflib pulls in pyparsing. This adds ~5MB to the package for a feature-flagged path. Is lazy importing the rdflib module an option? Currently ontology_r2rml.py imports it at module level — if context_tool.py does the lazy import of the ontology package only when the flag is on, this is probably fine, but worth confirming rdflib doesn't get loaded for non-ontology agents.

2. Duplicated sub-graph (ontology_subgraph.py — 233 lines)

• I understand the rationale (entity tool stays untouched), but this is a full copy of DataFabricGraph + QueryExecutor + state model. The only difference is the constructor takes system_prompt: str instead of building it internally. Could the entity sub-graph be refactored to also accept a pre-built prompt, making duplication unnecessary? The PR description says "deliberately isolated" — if this is a temporary measure until the entity tool is also refactored, document the intended convergence timeline.

3. Folder resolution is sequential-then-concurrent but not batched optimally (ontology_tool.py:725-753)

• Step 1a resolves distinct folder paths concurrently (good). Step 1b resolves entities by name concurrently (good). But steps 1a and 1b are sequential — 1b waits for all folder keys before starting any entity lookups. Since entity lookups need the folder key, this is correct, but worth noting that for N entities across M folders, latency = folder_resolve_time + entity_resolve_time (not parallelized across steps). Acceptable for small ontologies, but flag if california-schools (3 entities, 1 folder) takes noticeable time.

4. _MAX_ONTOLOGY_BYTES = 2_000_000 (ontology_fetcher.py:114)

• 2MB of raw text injected into a prompt is a lot of tokens (~500K+). The size cap protects against blowup, but in practice even a 200KB OWL could degrade LLM quality. Consider a tighter warning threshold or token-budget-aware truncation, especially if customers publish large ontologies.

5. asyncio.Lock for lazy init (ontology_tool.py:778)

• This is a per-handler lock, so it's scoped correctly. But if the handler is shared across event loops (unlikely but possible in some deployment patterns), asyncio.Lock would fail. Just a note — probably fine for the current runtime.

6. Missing error context in resolve_ontology_entities (ontology_tool.py:742-746)

• When retrieve_by_name_async fails for one entity in the asyncio.gather, the whole batch fails with the first exception. Consider return_exceptions=True + a summary error that names which entities failed, to aid debugging multi-entity ontologies.

7. Test: test_factory_builds_handler_from_ontology_set accesses private _ontologies (test_datafabric_ontology_tool.py:1321)

• Minor, but fragile. Consider testing via the tool description or metadata instead.

Nits

• ontology_r2rml.py:344-345: The # NOSONAR comments are clear, but consider adding a ruff: noqa equivalent if ruff also flags http:// in strings.
• ontology_prompt_builder.py:199: (field.description or "").replace("|", r"\|").replace("\n", " ") — good defensive escaping. The entity tool's prompt builder should probably do the same if it doesn't already.
• ontology_tool.py:809: sdk = UiPath() inside _ensure_graph — this instantiates a new SDK client on every first-call. Is there a reason not to accept the SDK as a constructor parameter for testability?

Verdict

Approve with minor suggestions. The architecture is sound, security model is correct, and the feature is properly gated. The duplicated sub-graph is the main thing worth discussing — it's defensible now but should have a convergence plan. The rdflib dependency is justified by the robustness gains over regex parsing.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud