feat(datafabric ontology): first-class read-only entities, enforcement, debug, read-flow wiring

Extends the ontology layer per review feedback:

1. df:ReadableEntity is now first-class. CompiledOntology gains
   `known_entities` (every df:entityKey the ontology declares) plus
   is_known / is_writable / is_read_only helpers. Previously a read-only
   entity was indistinguishable from one the ontology never mentioned —
   both were merely absent from entity_access.

2. Read-only is enforced, not advisory. validate_mutation_intent rejects
   a write to an entity the ontology knows but grants no write ops; the
   write handler prunes such entities from write_schemas so they never
   appear in the write tool description. (Verified: Customer is excluded
   and a direct update is rejected.)

3. Debug output. CompiledOntology.to_human_readable() + module-level
   format_ontology_debug(owl, compiled) render the raw OWL Turtle and a
   human-readable IR (entities + access modes, measure/state/reference
   field semantics, relationships). Logged at DEBUG in the fetch/compile
   path and printed by both POC scripts during a run.

4. Ontology wired into the READ flow (reads still go through the existing
   NL-to-SQL path — ontology enriches, does not restrict). Shared
   maybe_fetch_and_compile_ontology helper used by both handlers; the read
   handler threads CompiledOntology into DataFabricGraph.create ->
   datafabric_prompt_builder, which emits an "## Ontology Context" section
   (access modes, relationships, FK/reference targets, state-value sources)
   for schema linking (P5).

Also: poc_refund_drive.py verification read-back now addresses entities by
GUID (get_record_async requires the id, not the name).

Validated live on staging (dataservicetest/addyTest): debug IR shows
Customer READ-ONLY; Customer pruned from writes + write rejected; refund
flow insert + 3 updates persist, 4/4 verified. 752 tests pass, ruff clean.

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

Author: UIPath-Harshit

.gitignore

@@ -195,3 +195,4 @@ samples/**/entry-points.json
 samples/**/uv.lock
 
 testcases/**/uv.lock
+poc_out/

scripts/poc_refund_drive.py

@@ -93,6 +93,13 @@ async def main() -> int:
             "  ACTIVE — entity_access:",
             {k: sorted(v) for k, v in onto.entity_access.items()},
         )
+        # Always dump the raw OWL + human-readable IR for the POC.
+        from uipath_langchain.agent.tools.datafabric_tool.ontology_compiler import (
+            format_ontology_debug,
+        )
+
+        print()
+        print(format_ontology_debug(ONTOLOGY_TTL, onto))
     else:
         print("  INACTIVE (metadata-only)")
 
@@ -148,9 +155,12 @@ async def write(**kw):  # noqa: ANN003
     def g(rec, k):  # noqa: ANN001
         return rec.get(k) if isinstance(rec, dict) else getattr(rec, k, None)
 
-    order = await svc.get_record_async(by_suffix["PurchaseOrder"], ids["ORDER_ID"])
-    risk = await svc.get_record_async(by_suffix["CustomerRisk"], ids["RISK_ID"])
-    contact = await svc.get_record_async(by_suffix["Contact"], ids["CONTACT_ID"])
+    # get_record_async addresses the entity by its GUID id, not its name
+    # (same rule the write executor follows).
+    id_by_suffix = {it.name.rsplit("_", 1)[1]: it.id for it in items}
+    order = await svc.get_record_async(id_by_suffix["PurchaseOrder"], ids["ORDER_ID"])
+    risk = await svc.get_record_async(id_by_suffix["CustomerRisk"], ids["RISK_ID"])
+    contact = await svc.get_record_async(id_by_suffix["Contact"], ids["CONTACT_ID"])
 
     print("\n=== VERIFY (read-back) ===")
     checks = [

scripts/run_agent_with_ontology.py

@@ -141,6 +141,30 @@ def _fmt_set_map(m: dict[str, Any]) -> str:
     print(_fmt_set_map(compiled.entity_relationships))
 
 
+def _print_ontology_debug(
+    owl_turtle: str, compiled: Any, *, debug_ontology: bool
+) -> None:
+    """Print the human-readable IR and, when enabled, the raw OWL Turtle.
+
+    Uses ``ontology_compiler.format_ontology_debug`` so the CLI output mirrors
+    exactly what the runtime emits to debug logs.
+    """
+    if compiled is None:
+        return
+    from uipath_langchain.agent.tools.datafabric_tool.ontology_compiler import (
+        format_ontology_debug,
+    )
+
+    if debug_ontology:
+        # Full block: raw OWL + human-readable IR.
+        print()
+        print(format_ontology_debug(owl_turtle, compiled))
+    else:
+        # Human-readable IR only (no raw-OWL dump).
+        print("\n=== COMPILED ONTOLOGY (human-readable IR) ===")
+        print(compiled.to_human_readable())
+
+
 def _load_entity_set(path: Path) -> list[Any]:
     """Load a JSON list of DataFabricEntityItem dicts into model instances."""
     import json
@@ -201,6 +225,10 @@ async def _async_main(args: argparse.Namespace) -> int:
     _print_ontology_facts(
         standalone_compiled, header="ONTOLOGY FACTS (standalone compile)"
     )
+    # Richer human-readable IR (and, when --debug-ontology, the raw OWL too).
+    _print_ontology_debug(
+        ttl_text, standalone_compiled, debug_ontology=args.debug_ontology
+    )
 
     # --- Step 2: load entity set. --------------------------------------------
     try:
@@ -309,6 +337,7 @@ async def _async_main(args: argparse.Namespace) -> int:
     ):
         print("\nontology ACTIVE -- handler compiled and is using the ontology.")
         _print_ontology_facts(compiled, header="ONTOLOGY FACTS (active in handler)")
+        _print_ontology_debug(ttl_text, compiled, debug_ontology=args.debug_ontology)
     else:
         print(
             "\nontology INACTIVE (fell back to metadata-only). The handler did "
@@ -414,6 +443,13 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         default="datafabric",
         help="Name for the Data Fabric context resource (default: datafabric).",
     )
+    parser.add_argument(
+        "--debug-ontology",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Dump the raw OWL Turtle alongside the human-readable compiled IR "
+        "(default: on). Use --no-debug-ontology to print only the IR.",
+    )
     parser.add_argument(
         "--dry-run",
         action="store_true",

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

@@ -32,6 +32,11 @@ class CompiledOntology(BaseModel):
     valid (if sparse) ``CompiledOntology`` rather than raising.
     """
 
+    known_entities: set[str] = Field(default_factory=set)
+    """Every entity_key the ontology declares (has ``df:entityKey``), readable
+    or writable. A read-only ``df:ReadableEntity`` is "known but not in
+    ``entity_access``"; an entity absent here is unknown to the ontology."""
+
     entity_access: dict[str, set[str]] = Field(default_factory=dict)
     """entity_key -> set of allowed operations, e.g. ``{"insert", "update"}``."""
 
@@ -53,10 +58,87 @@ class CompiledOntology(BaseModel):
     def is_empty(self) -> bool:
         """True if no ontology facts were extracted (graceful-fallback signal)."""
         return not (
-            self.entity_access
+            self.known_entities
+            or self.entity_access
             or self.measure_fields
             or self.state_fields
             or self.reference_fields
             or self.hitl_operations
             or self.entity_relationships
         )
+
+    def is_known(self, entity_key: str) -> bool:
+        """True if the ontology declares this entity (readable or writable)."""
+        return entity_key in self.known_entities
+
+    def is_writable(self, entity_key: str) -> bool:
+        """True if the ontology grants any write access to this entity."""
+        return entity_key in self.entity_access
+
+    def is_read_only(self, entity_key: str) -> bool:
+        """True if the entity is declared by the ontology but grants no writes.
+
+        A ``df:ReadableEntity`` is "known but not in ``entity_access``".
+        """
+        return (
+            entity_key in self.known_entities and entity_key not in self.entity_access
+        )
+
+    def to_human_readable(self) -> str:
+        """Render a compact, grouped, human-readable summary of the IR.
+
+        Sections: entity access modes (with HITL ops), field semantics
+        (measure / state / reference), and entity relationships. Intended
+        for debug logs and the ontology CLI scripts.
+        """
+        lines: list[str] = []
+
+        # -- Entities (access mode + HITL) --
+        lines.append("Entities:")
+        if self.known_entities:
+            for ek in sorted(self.known_entities):
+                ops = self.entity_access.get(ek)
+                if ops is not None:
+                    mode = (
+                        f"WRITABLE [{','.join(sorted(ops))}]"
+                        if ops
+                        else "WRITABLE [no ops declared]"
+                    )
+                else:
+                    mode = "READ-ONLY"
+                line = f"  - {ek}: {mode}"
+                hitl = self.hitl_operations.get(ek)
+                if hitl:
+                    line += f" (HITL: {','.join(sorted(hitl))})"
+                lines.append(line)
+        else:
+            lines.append("  (none)")
+
+        # -- Field semantics --
+        lines.append("Field semantics:")
+        if self.measure_fields:
+            lines.append("  Measure fields (additive / replacement):")
+            for k in sorted(self.measure_fields):
+                lines.append(f"    - {k}: {self.measure_fields[k]}")
+        if self.state_fields:
+            lines.append("  State fields (choiceset / state-machine):")
+            for k in sorted(self.state_fields):
+                src = self.state_fields[k] or "(unspecified)"
+                lines.append(f"    - {k}: {src}")
+        if self.reference_fields:
+            lines.append("  Reference fields (-> target entity):")
+            for k in sorted(self.reference_fields):
+                lines.append(f"    - {k} -> {self.reference_fields[k]}")
+        if not (self.measure_fields or self.state_fields or self.reference_fields):
+            lines.append("  (none)")
+
+        # -- Relationships --
+        lines.append("Relationships:")
+        if self.entity_relationships:
+            for ek in sorted(self.entity_relationships):
+                targets = ", ".join(self.entity_relationships[ek])
+                lines.append(f"  - {ek} -> {targets}")
+        else:
+            lines.append("  (none)")
+
+        return "\n".join(lines)

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

@@ -13,6 +13,7 @@
 
 from uipath.platform.entities import Entity
 
+from .compiled_ontology import CompiledOntology
 from .datafabric_prompts import SQL_CONSTRAINTS
 from .models import (
     EntitySchema,
@@ -149,11 +150,71 @@ def build_entity_context(entity: Entity) -> EntitySQLContext:
     return EntitySQLContext(entity_schema=schema, query_patterns=query_patterns)
 
 
+def format_ontology_context(compiled_ontology: CompiledOntology) -> str:
+    """Render read-side schema-linking enrichment from a compiled ontology.
+
+    This is informational context for the NL-to-SQL model (the P5 goal). It
+    surfaces per-entity access modes, entity relationships, reference/FK fields
+    (to guide join-path selection), and state fields (with their valid-value
+    source). It does NOT restrict reads.
+
+    Args:
+        compiled_ontology: The compiled OWL ontology IR.
+
+    Returns:
+        A markdown ``## Ontology Context`` section, or an empty string when the
+        ontology carries no facts.
+    """
+    if compiled_ontology is None or compiled_ontology.is_empty():
+        return ""
+
+    lines: list[str] = ["## Ontology Context", ""]
+    lines.append(
+        "Ontology-derived schema-linking hints (informational; does not "
+        "restrict what you may read):"
+    )
+    lines.append("")
+
+    # Per-entity access mode (purely informational for the read model).
+    if compiled_ontology.known_entities:
+        lines.append("**Entity access modes:**")
+        for ek in sorted(compiled_ontology.known_entities):
+            mode = "WRITABLE" if compiled_ontology.is_writable(ek) else "READ-ONLY"
+            lines.append(f"- {ek}: {mode}")
+        lines.append("")
+
+    # Entity relationships (entity -> related entities).
+    if compiled_ontology.entity_relationships:
+        lines.append("**Entity relationships (entity -> related entities):**")
+        for ek in sorted(compiled_ontology.entity_relationships):
+            targets = ", ".join(compiled_ontology.entity_relationships[ek])
+            lines.append(f"- {ek} -> {targets}")
+        lines.append("")
+
+    # Reference / FK fields (guide join-path selection).
+    if compiled_ontology.reference_fields:
+        lines.append("**Reference / foreign-key fields (field -> target entity):**")
+        for k in sorted(compiled_ontology.reference_fields):
+            lines.append(f"- {k} -> {compiled_ontology.reference_fields[k]}")
+        lines.append("")
+
+    # State fields and their valid-value source.
+    if compiled_ontology.state_fields:
+        lines.append("**State fields (field -> valid-value source):**")
+        for k in sorted(compiled_ontology.state_fields):
+            src = compiled_ontology.state_fields[k] or "(unspecified)"
+            lines.append(f"- {k} -> {src}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
 def build_sql_context(
     entities: list[Entity],
     resource_description: str = "",
     base_system_prompt: str = "",
     prompt_version: str | None = None,
+    compiled_ontology: CompiledOntology | None = None,
 ) -> SQLContext:
     """Build the full SQL context from entities, prompts, and constraints.
 
@@ -173,11 +234,18 @@ def build_sql_context(
     )
     rendered_prompt = version.render(ctx)
 
+    ontology_context = (
+        format_ontology_context(compiled_ontology)
+        if compiled_ontology is not None
+        else ""
+    )
+
     return SQLContext(
         base_system_prompt=base_system_prompt or None,
         resource_description=None,
         sql_expert_system_prompt=rendered_prompt,
         constraints=SQL_CONSTRAINTS,
+        ontology_context=ontology_context or None,
         entity_contexts=[build_entity_context(e) for e in entities],
     )
 
@@ -210,6 +278,10 @@ def format_sql_context(ctx: SQLContext) -> str:
         lines.append(ctx.resource_description)
         lines.append("")
 
+    if ctx.ontology_context:
+        lines.append(ctx.ontology_context.rstrip())
+        lines.append("")
+
     lines.append("## All available Data Fabric Entities")
     lines.append("")
 
@@ -245,6 +317,7 @@ def build(
     resource_description: str = "",
     base_system_prompt: str = "",
     prompt_version: str | None = None,
+    compiled_ontology: CompiledOntology | None = None,
 ) -> str:
     """Build the full SQL prompt text for the inner sub-graph LLM.
 
@@ -258,6 +331,10 @@ def build(
         base_system_prompt: Optional system prompt from the outer agent.
         prompt_version: Optional version key (e.g. ``"v0"``, ``"v1"``).
             Defaults to the registry's default.
+        compiled_ontology: Optional compiled OWL ontology. When present an
+            ``## Ontology Context`` section is appended with read-side
+            schema-linking enrichment (relationships, FK targets, state-value
+            sources, access modes). Purely informational — never restricts reads.
 
     Returns:
         Formatted prompt string for the inner LLM system message.
@@ -270,6 +347,7 @@ def build(
         resource_description,
         base_system_prompt,
         prompt_version=prompt_version,
+        compiled_ontology=compiled_ontology,
     )
     return format_sql_context(ctx)
 

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

@@ -33,6 +33,7 @@
 
 from ..datafabric_query_tool import DataFabricQueryTool
 from . import datafabric_prompt_builder
+from .compiled_ontology import CompiledOntology
 from .models import DataFabricExecuteSqlInput
 
 logger = logging.getLogger(__name__)
@@ -88,14 +89,18 @@ def __init__(
         max_iterations: int = 25,
         resource_description: str = "",
         base_system_prompt: str = "",
+        compiled_ontology: CompiledOntology | None = None,
     ) -> None:
         self._max_iterations = max_iterations
         self._execute_sql_tool = self._create_execute_sql_tool(
             entities_service, entities
         )
         self._system_message = SystemMessage(
             content=datafabric_prompt_builder.build(
-                entities, resource_description, base_system_prompt
+                entities,
+                resource_description,
+                base_system_prompt,
+                compiled_ontology=compiled_ontology,
             )
         )
         self._inner_llm = llm.model_copy(update={"disable_streaming": True}).bind_tools(
@@ -226,14 +231,21 @@ def create(
         max_iterations: int = 25,
         resource_description: str = "",
         base_system_prompt: str = "",
+        compiled_ontology: CompiledOntology | None = None,
     ) -> CompiledStateGraph[Any]:
-        """Create and return a compiled Data Fabric sub-graph."""
+        """Create and return a compiled Data Fabric sub-graph.
+
+        When *compiled_ontology* is supplied it enriches the read prompt with
+        schema-linking context (relationships, FK targets, state-value sources,
+        access modes). It never restricts reads.
+        """
         graph = DataFabricGraph(
             llm,
             entities,
             entities_service,
             max_iterations,
             resource_description,
             base_system_prompt,
+            compiled_ontology=compiled_ontology,
         )
         return graph.compiled_graph