feat: add optional OWL ontology compiler for Data Fabric writes

Builds the ontology layer from write RFC v2. The OWL ontology is the
authoring/storage format; it is compiled into a CompiledOntology
intermediate representation (NOT injected as raw OWL — research shows
LLMs reason poorly over raw OWL Turtle).

- compiled_ontology.py: CompiledOntology model (entity_access,
  measure_fields, state_fields, reference_fields, hitl_operations,
  entity_relationships) per RFC §5.2
- ontology_compiler.py: compile_ontology(owl_turtle) via rdflib.
  Supports both ontology dialects — the .ttl dialect (rdfs:subClassOf
  df:WritableEntity + action-derived ops + df:hasField) and the RFC
  dialect (a df:WritableEntity + df:allowsOperation). Resilient to
  partial annotations; raises OntologyCompileError only on malformed
  Turtle.
- write_validation.py: validate_mutation_intent gains optional
  compiled_ontology — rejects operations not in entity_access. State
  transition validation deferred to v3 (documented TODO).
- datafabric_tool.py: DataFabricWriteHandler best-effort fetches +
  compiles the ontology via get_ontology_file_async. The method is
  absent from the current platform package, so this degrades gracefully
  to the metadata-only path (compiled_ontology stays None) — the build
  does not break.
- rdflib>=7.0.0 added to dependencies.

23 new tests (refund + order-management dialects, RFC dialect, graceful
paths). 109 datafabric_tool tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: UIPath-Harshit

pyproject.toml

@@ -24,6 +24,7 @@ dependencies = [
     "pillow>=12.1.1",
     "a2a-sdk>=0.2.0,<1.0.0",
     "uipath-langchain-client[openai]>=1.14.0,<1.15.0",
+    "rdflib>=7.0.0,<8.0.0",
 ]
 
 classifiers = [

src/uipath_langchain/agent/tools/datafabric_tool/compiled_ontology.py

@@ -0,0 +1,62 @@
+"""Compiled OWL ontology model for Data Fabric writes.
+
+A ``CompiledOntology`` is the intermediate representation produced by
+``ontology_compiler.compile_ontology`` from an OWL 2 QL Turtle source
+(the ``df:`` write-extension vocabulary, see ``p1-owl-write-extension.ttl``).
+
+The ontology is OPTIONAL.  When present it enriches and constrains writes
+with semantics that entity metadata alone cannot express:
+
+  - which entities are writable and which operations they allow
+  - field semantics (state / measure / reference)
+  - HITL markers on destructive operations
+  - entity-to-entity relationships
+
+When the ontology is absent the metadata-only write path still works
+(graceful fallback).  See RFC ``p1-write-rfc-v2-ontology.md`` §5.2.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class CompiledOntology(BaseModel):
+    """Result of compiling an OWL write-extension ontology.
+
+    All members are keyed by the ``df:entityKey`` / ``df:fieldKey`` strings,
+    which are the exact values the LLM uses in ``DataFabricWriteInput``.
+    Field-level members are keyed as ``"<entity_key>.<field_key>"``.
+
+    Every member defaults to empty, so a partial or empty ontology yields a
+    valid (if sparse) ``CompiledOntology`` rather than raising.
+    """
+
+    entity_access: dict[str, set[str]] = Field(default_factory=dict)
+    """entity_key -> set of allowed operations, e.g. ``{"insert", "update"}``."""
+
+    measure_fields: dict[str, str] = Field(default_factory=dict)
+    """``"entity_key.field_key"`` -> ``"additive"`` | ``"replacement"``."""
+
+    state_fields: dict[str, str] = Field(default_factory=dict)
+    """``"entity_key.field_key"`` -> choiceset / state-machine key."""
+
+    reference_fields: dict[str, str] = Field(default_factory=dict)
+    """``"entity_key.field_key"`` -> referenced entity_key (FK target)."""
+
+    hitl_operations: dict[str, set[str]] = Field(default_factory=dict)
+    """entity_key -> set of operations that require human-in-the-loop."""
+
+    entity_relationships: dict[str, list[str]] = Field(default_factory=dict)
+    """entity_key -> list of referenced entity_keys (semantic relationships)."""
+
+    def is_empty(self) -> bool:
+        """True if no ontology facts were extracted (graceful-fallback signal)."""
+        return not (
+            self.entity_access
+            or self.measure_fields
+            or self.state_fields
+            or self.reference_fields
+            or self.hitl_operations
+            or self.entity_relationships
+        )

src/uipath_langchain/agent/tools/datafabric_tool/datafabric_tool.py

@@ -27,6 +27,7 @@
 from uipath.platform.entities import DataFabricEntityItem
 
 from ..base_uipath_structured_tool import BaseUiPathStructuredTool
+from .compiled_ontology import CompiledOntology
 from .models import (
     DataFabricQueryInput,
     DataFabricWriteInput,
@@ -168,6 +169,7 @@ def __init__(
         self._entity_set = entity_set
         self._write_schemas: dict[str, EntityWriteSchema] | None = None
         self._write_tool_description: str | None = None
+        self._compiled_ontology: CompiledOntology | None = None
         self._executor: Any | None = None
         self._init_lock = asyncio.Lock()
 
@@ -203,12 +205,60 @@ async def _ensure_initialized(self) -> None:
                     writable_fields=writable,
                 )
 
+            # Optional ontology layer: fetch + compile the OWL ontology if the
+            # platform exposes get_ontology_file_async. This method may only
+            # exist on a feature branch — if it is absent we degrade gracefully
+            # to the metadata-only write path (compiled_ontology stays None).
+            self._compiled_ontology = await self._maybe_compile_ontology(
+                resolution.entities_service
+            )
+
+            entity_access = (
+                self._compiled_ontology.entity_access
+                if self._compiled_ontology
+                else None
+            )
             self._write_tool_description = build_write_tool_description(
-                self._write_schemas
+                self._write_schemas,
+                entity_access=entity_access,
             )
 
             self._executor = WriteExecutor(resolution.entities_service)
 
+    async def _maybe_compile_ontology(
+        self, entities_service: Any
+    ) -> CompiledOntology | None:
+        """Best-effort fetch + compile of the optional OWL ontology.
+
+        Returns the compiled ontology, or ``None`` when no ontology is
+        available or the platform package does not expose the fetch method.
+        Never raises — any failure degrades to the metadata-only path.
+        """
+        get_ontology = getattr(entities_service, "get_ontology_file_async", None)
+        if not callable(get_ontology):
+            logger.debug(
+                "EntitiesService has no get_ontology_file_async; "
+                "skipping ontology compilation (metadata-only writes)."
+            )
+            return None
+
+        from .ontology_compiler import compile_ontology
+
+        try:
+            owl_turtle = await get_ontology("owl")
+            if not owl_turtle:
+                logger.debug("No OWL ontology returned; metadata-only writes.")
+                return None
+            compiled = compile_ontology(owl_turtle)
+            logger.debug(
+                "Compiled ontology with %d writable entities.",
+                len(compiled.entity_access),
+            )
+            return compiled
+        except Exception as exc:  # graceful no-op on any fetch/parse failure
+            logger.debug("Ontology fetch/compile skipped: %s", exc)
+            return None
+
     async def __call__(
         self,
         entity_key: str,
@@ -243,8 +293,10 @@ async def __call__(
             fields=fields,
         )
 
-        # Validate
-        errors = validate_mutation_intent(intent, self._write_schemas)
+        # Validate (ontology, when present, constrains allowed operations)
+        errors = validate_mutation_intent(
+            intent, self._write_schemas, self._compiled_ontology
+        )
         if errors:
             return json.dumps(
                 {