prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/mcp/tools.py ADDED
@@ -0,0 +1,504 @@
1
+ """Tool implementations for the ProGraph MCP server.
2
+
3
+ Kept separate from server wiring so they can be unit-tested without an MCP
4
+ session. Each function takes the engine explicitly; the server module binds
5
+ the engine when registering tools.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import difflib
11
+ from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional
12
+
13
+ from prograph.schema.context import (
14
+ describe_schema,
15
+ render_compact,
16
+ render_markdown,
17
+ )
18
+ from prograph.schema.examples import generate_examples
19
+
20
+ if TYPE_CHECKING:
21
+ from prograph import ProGraph
22
+ from prograph.schema.context import SchemaDescriptor
23
+
24
+
25
+ DEFAULT_ROW_LIMIT = 100
26
+ MAX_ROW_LIMIT = 1000
27
+
28
+ SchemaFormat = Literal["compact", "markdown", "dict"]
29
+
30
+
31
+ # ──────────────────────────────────────────────────────────────────────
32
+ # execute_query
33
+ # ──────────────────────────────────────────────────────────────────────
34
+
35
+
36
+ def execute_query(
37
+ engine: "ProGraph",
38
+ query: str,
39
+ *,
40
+ language: Optional[str] = None,
41
+ limit: Optional[int] = None,
42
+ ) -> Dict[str, Any]:
43
+ """Execute a graph query and return results in a tool-friendly shape.
44
+
45
+ Successful response::
46
+
47
+ {
48
+ "rows": [...],
49
+ "row_count": N,
50
+ "language": "sparql",
51
+ "truncated": bool,
52
+ "limit_applied": N,
53
+ }
54
+
55
+ Error response (LLM-friendly: includes the schema slice and label-name
56
+ suggestions when the error mentions an unknown identifier)::
57
+
58
+ {
59
+ "error": "...",
60
+ "query": "...",
61
+ "language": "...",
62
+ "schema": "<compact schema>",
63
+ "suggestions": ["Person", "Company"], # if applicable
64
+ }
65
+ """
66
+ effective_limit = _clamp_limit(limit)
67
+
68
+ try:
69
+ # A pyarrow.Table: only the rows returned become Python values.
70
+ table = engine.execute(query, language=language, return_type="arrow")
71
+ except Exception as e:
72
+ response = _error_response(engine, query, language, e)
73
+ return response
74
+ total = table.num_rows
75
+ rows = table.slice(0, effective_limit).to_pylist(maps_as_pydicts="strict")
76
+
77
+ truncated = total > effective_limit
78
+
79
+ response = {
80
+ "rows": rows,
81
+ "row_count": len(rows),
82
+ "total_row_count": total,
83
+ "language": _language(engine, query, language),
84
+ "truncated": truncated,
85
+ "limit_applied": effective_limit,
86
+ }
87
+ return response
88
+
89
+
90
+
91
+ def _clamp_limit(limit: Optional[int]) -> int:
92
+ if limit is None:
93
+ return DEFAULT_ROW_LIMIT
94
+ if limit < 1:
95
+ return 1
96
+ return min(limit, MAX_ROW_LIMIT)
97
+
98
+
99
+ def _language(engine: "ProGraph", query: str, language: Optional[str]) -> str:
100
+ """The language the engine runs the query as: the argument, else the
101
+ engine's default, else the engine's own detection."""
102
+ if language:
103
+ return language
104
+ default = getattr(engine, "default_language", "auto")
105
+ if default and default != "auto":
106
+ return default
107
+ from prograph.hints import parse_hints
108
+ return engine._detect_language(parse_hints(query)[0])
109
+
110
+
111
+ def _error_response(
112
+ engine: "ProGraph",
113
+ query: str,
114
+ language: Optional[str],
115
+ error: Exception,
116
+ ) -> Dict[str, Any]:
117
+ schema = engine.schema # property on ProGraph
118
+ response: Dict[str, Any] = {
119
+ "error": f"{type(error).__name__}: {error}",
120
+ "query": query,
121
+ "language": _language(engine, query, language),
122
+ }
123
+ if schema is not None:
124
+ desc = describe_schema(schema)
125
+ response["schema"] = render_compact(desc)
126
+ # An undeclared name carries what was looked up and the nearest
127
+ # declared names; the text of any other error is searched for an
128
+ # identifier.
129
+ from prograph.utils.exceptions import UnknownNameError
130
+ if isinstance(error, UnknownNameError):
131
+ response["unknown_name"] = {"name": error.name, "kind": error.kind,
132
+ "looked_up_on": list(error.labels),
133
+ "declared_by": list(error.declared_by)}
134
+ suggestions = list(error.nearest)
135
+ else:
136
+ suggestions = _suggest_identifiers(str(error), desc)
137
+ if suggestions:
138
+ response["suggestions"] = suggestions
139
+ return response
140
+
141
+
142
+ def _suggest_identifiers(error_msg: str, desc: "SchemaDescriptor") -> List[str]:
143
+ """Fuzzy-match unknown identifiers in the error against schema labels.
144
+
145
+ Looks for quoted-or-bare tokens in the error message and finds the
146
+ nearest matches among node labels, relationship types, and property
147
+ names. Helps the calling LLM correct a typo without another tool call.
148
+ """
149
+ known: List[str] = []
150
+ for n in desc.nodes:
151
+ if n.label is not None:
152
+ known.append(n.label)
153
+ known.extend(p.name for p in n.properties)
154
+ for r in desc.relationships:
155
+ known.append(r.rel_type)
156
+ known.extend(p.name for p in r.properties)
157
+ if not known:
158
+ return []
159
+
160
+ import re
161
+ tokens = set(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", error_msg))
162
+ candidates: List[str] = []
163
+ for tok in tokens:
164
+ if tok in known:
165
+ continue
166
+ matches = difflib.get_close_matches(tok, known, n=2, cutoff=0.7)
167
+ candidates.extend(matches)
168
+ # Dedup preserving order
169
+ seen = set()
170
+ result = []
171
+ for c in candidates:
172
+ if c not in seen:
173
+ seen.add(c)
174
+ result.append(c)
175
+ return result[:5]
176
+
177
+
178
+ # ──────────────────────────────────────────────────────────────────────
179
+ # explain_query
180
+ # ──────────────────────────────────────────────────────────────────────
181
+
182
+
183
+ def explain_query(
184
+ engine: "ProGraph",
185
+ query: str,
186
+ *,
187
+ language: Optional[str] = None,
188
+ ) -> Dict[str, Any]:
189
+ """The SQL the engine runs for a query, without running it."""
190
+ try:
191
+ return {
192
+ "query": query,
193
+ "language": _language(engine, query, language),
194
+ "sql": engine.to_sql(query, language=language),
195
+ }
196
+ except Exception as e:
197
+ return _error_response(engine, query, language, e)
198
+
199
+
200
+ # ──────────────────────────────────────────────────────────────────────
201
+ # Schema introspection
202
+ # ──────────────────────────────────────────────────────────────────────
203
+
204
+
205
+ def get_schema(
206
+ engine: "ProGraph",
207
+ *,
208
+ format: SchemaFormat = "compact",
209
+ ) -> Dict[str, Any]:
210
+ """Describe the graph schema in the requested format."""
211
+ schema = engine.schema
212
+ if schema is None:
213
+ return {"format": format, "schema": None, "available": False}
214
+
215
+ desc = describe_schema(schema)
216
+ if format == "dict":
217
+ payload: Any = desc.to_dict()
218
+ elif format == "markdown":
219
+ payload = render_markdown(desc)
220
+ else:
221
+ payload = render_compact(desc)
222
+
223
+ return {
224
+ "format": format,
225
+ "schema": payload,
226
+ "available": True,
227
+ "node_count": len(desc.nodes),
228
+ "relationship_count": len(desc.relationships),
229
+ "languages": desc.languages,
230
+ }
231
+
232
+
233
+ def list_node_labels(engine: "ProGraph") -> List[str]:
234
+ """List all node labels known to the engine."""
235
+ from prograph.r2rml.schema import require_property_graph
236
+ require_property_graph(engine.schema, "node labels")
237
+ schema = engine.schema
238
+ if schema is None:
239
+ return []
240
+ return [m.label for m in schema.node_mappings if m.label is not None]
241
+
242
+
243
+ def list_relationship_types(engine: "ProGraph") -> List[Dict[str, str]]:
244
+ """List relationship types with their endpoint labels."""
245
+ from prograph.r2rml.schema import require_property_graph
246
+ require_property_graph(engine.schema, "relationship types")
247
+ schema = engine.schema
248
+ if schema is None:
249
+ return []
250
+ return [
251
+ {
252
+ "type": m.rel_type,
253
+ "start_label": m.start_node_label,
254
+ "end_label": m.end_node_label,
255
+ "start_identity": getattr(m, "start_node_identity", None),
256
+ "end_identity": getattr(m, "end_node_identity", None),
257
+ }
258
+ for m in schema.relationship_mappings
259
+ ]
260
+
261
+
262
+ # ──────────────────────────────────────────────────────────────────────
263
+ # Suggestions
264
+ # ──────────────────────────────────────────────────────────────────────
265
+
266
+
267
+ def suggest_queries(
268
+ engine: "ProGraph",
269
+ *,
270
+ n: int = 5,
271
+ language: str = "sparql",
272
+ ) -> List[Dict[str, Any]]:
273
+ """Generate example question/query pairs from the schema."""
274
+ schema = engine.schema
275
+ if schema is None:
276
+ return []
277
+ examples = generate_examples(describe_schema(schema), n=n, language=language)
278
+ return [e.to_dict() for e in examples]
279
+
280
+
281
+ # ──────────────────────────────────────────────────────────────────────
282
+ # Ontology (semantic model) + SHACL validation, the agent's contract
283
+ # ──────────────────────────────────────────────────────────────────────
284
+
285
+
286
+ def get_ontology(engine: "ProGraph") -> Dict[str, Any]:
287
+ """Describe the bound ontology, the *semantic* model behind the tabular
288
+ schema: class hierarchy, property domains/ranges, and OWL characteristics.
289
+
290
+ This is what lets an agent reason about the data rather than just its
291
+ columns: it learns that a query over a superclass covers its subclasses,
292
+ which properties connect which classes, and which properties are
293
+ transitive / symmetric / inverse / chained (and so participate in
294
+ entailment). Returns ``available: False`` when no ontology is bound.
295
+ """
296
+ ont = engine.ontology
297
+ profile = engine.profile
298
+ if ont is None:
299
+ return {
300
+ "available": False,
301
+ "profile": profile,
302
+ "note": (
303
+ "No ontology is bound to this engine; queries run on the "
304
+ "tabular schema only (use get_schema)."
305
+ ),
306
+ }
307
+
308
+ hierarchy = ont.hierarchy
309
+ classes: List[Dict[str, Any]] = []
310
+ for name in sorted(ont.classes):
311
+ classes.append({
312
+ "name": name,
313
+ "subClassOf": sorted(hierarchy.get_direct_superclasses(name)),
314
+ "subclasses": sorted(ont.get_subclasses(name, include_self=False)),
315
+ "equivalentClasses": sorted(ont.get_equivalent_classes(name)),
316
+ })
317
+
318
+ properties: List[Dict[str, Any]] = []
319
+ for pname, md in sorted(ont.properties.items()):
320
+ characteristics: List[str] = []
321
+ if md.is_symmetric:
322
+ characteristics.append("symmetric")
323
+ if md.is_transitive:
324
+ characteristics.append("transitive")
325
+ if md.is_functional:
326
+ characteristics.append("functional")
327
+ properties.append({
328
+ "name": pname,
329
+ "domain": sorted(md.domain),
330
+ "range": sorted(md.range),
331
+ "characteristics": characteristics,
332
+ "inverseOf": md.inverse_of,
333
+ "subPropertyOf": sorted(md.super_properties),
334
+ "equivalentProperties": sorted(md.equivalent_properties),
335
+ "propertyChain": md.property_chain,
336
+ })
337
+
338
+ # A bound ontology is applied at query time (subclasses, sub-properties,
339
+ # domains and ranges); under profile 'rl' OWL 2 RL's facts are also stored.
340
+ note = (
341
+ "An ontology is bound, so matching a class expands to its "
342
+ "subclasses at query time. Query the superclass to roll up its "
343
+ "subclasses."
344
+ )
345
+ if profile != "rl":
346
+ note += " A transitive property is queried as a path (ex:p+)."
347
+ else:
348
+ note += (" Under profile 'rl' the facts of OWL 2 RL's rules (transitive, "
349
+ "inverse and symmetric properties, chains, owl:sameAs) are "
350
+ "materialized too, and a pattern matches them directly.")
351
+
352
+ return {
353
+ "available": True,
354
+ "profile": profile,
355
+ "note": note,
356
+ "classes": classes,
357
+ "properties": properties,
358
+ }
359
+
360
+
361
+ def validate_against_shapes(engine: "ProGraph", shapes: str) -> Dict[str, Any]:
362
+ """Validate the graph SPARQL answers against SHACL ``shapes`` and return a
363
+ conformance report.
364
+
365
+ The runtime guardrail: before an agent commits or trusts a fact, check it
366
+ against the shapes. ``shapes`` is a SHACL graph as a Turtle string or a path
367
+ to a ``.ttl`` file. The report lists each violation's focus node, property
368
+ path, severity, and message so the agent can repair rather than just fail.
369
+
370
+ The shapes meet the IRIs a SPARQL query returns; a ``sh:targetClass`` the
371
+ mapping never produces selects nothing, and validation conforms vacuously.
372
+ """
373
+ try:
374
+ report = engine.validate_shapes(shapes)
375
+ except Exception as e: # backend unsupported, bad shapes, etc.
376
+ return {
377
+ "available": False,
378
+ "error": f"{type(e).__name__}: {e}",
379
+ }
380
+
381
+ return {
382
+ "available": True,
383
+ "conforms": report.conforms,
384
+ "violation_count": len(report.violations),
385
+ "by_severity": dict(report.by_severity),
386
+ "violations": [
387
+ {
388
+ "focus_node": v.focus_node,
389
+ "path": v.result_path,
390
+ "severity": v.severity,
391
+ "message": v.message,
392
+ }
393
+ for v in report.violations
394
+ ],
395
+ }
396
+
397
+
398
+ def check_data_quality(engine: "ProGraph") -> Dict[str, Any]:
399
+ """Validate the engine's current data against the operator-configured
400
+ SHACL shapes (``engine.default_shapes``), a zero-argument runtime guardrail.
401
+
402
+ Unlike :func:`validate_against_shapes` (which takes shapes the caller
403
+ supplies), this checks the shapes the *operator* declared for this engine.
404
+ It is exposed as a no-required-argument MCP tool so an agent's context pass
405
+ invokes it automatically: the conformance verdict is surfaced into the
406
+ agent's reasoning, so a non-conforming dataset is visible *before* any
407
+ number derived from it is trusted. Deterministic, independent of the LLM.
408
+
409
+ Returns ``{available: False}`` when no default shapes are configured.
410
+ """
411
+ shapes = engine.default_shapes
412
+ if not shapes:
413
+ return {
414
+ "available": False,
415
+ "reason": "no operator-configured shapes on this engine",
416
+ }
417
+ result = validate_against_shapes(engine, shapes)
418
+ if result.get("available"):
419
+ result["guardrail"] = (
420
+ "PASS, data conforms to the operator's shapes; results may be trusted."
421
+ if result.get("conforms")
422
+ else (
423
+ f"FAIL, {result.get('violation_count')} shape violation(s); "
424
+ "treat results derived from the offending nodes as untrusted "
425
+ "and surface the data-quality problem in your answer."
426
+ )
427
+ )
428
+ return result
429
+
430
+
431
+ # ──────────────────────────────────────────────────────────────────────
432
+ # Generated-views introspection (Genie integration)
433
+ # ──────────────────────────────────────────────────────────────────────
434
+
435
+
436
+ def generate_views(
437
+ engine: "ProGraph",
438
+ *,
439
+ target_catalog: Optional[str] = None,
440
+ target_schema: str = "prograph_views",
441
+ include_labels: Optional[List[str]] = None,
442
+ exclude_labels: Optional[List[str]] = None,
443
+ ) -> List[Dict[str, Any]]:
444
+ """Introspect the SQL views ProGraph would generate from this engine.
445
+
446
+ Returns a JSON-serializable list of view descriptors, name,
447
+ source (schema_label / subclass_closure / owl_defined_class /
448
+ …), source label, description, fully-qualified namespace
449
+ placement, and columns. **Genie should prefer querying these
450
+ views over the raw tables** when a question maps to a class,
451
+ subclass closure, or OWL-entailed defined class: the view
452
+ encodes the right semantic projection consistently.
453
+
454
+ This tool does NOT execute any DDL; it's read-only introspection.
455
+ To actually create the views in the warehouse, the operator runs
456
+ ``prograph generate-views`` (CLI) or ``engine.write_views()``
457
+ (Python). Those steps happen outside this MCP session.
458
+
459
+ Args:
460
+ engine: The :class:`ProGraph` engine.
461
+ target_catalog: Optional catalog prefix for fully-qualified
462
+ naming (e.g. ``"workspace"`` on Databricks Unity Catalog).
463
+ target_schema: Schema/namespace where the views live. Defaults
464
+ to ``"prograph_views"`` per the operational-artifacts
465
+ principle.
466
+ include_labels / exclude_labels: NodeMapping label filters.
467
+
468
+ Returns:
469
+ ``[{name, source, source_label, description,
470
+ fully_qualified_name, columns}, ...]``.
471
+ """
472
+ views = engine.generate_views(
473
+ target_catalog=target_catalog,
474
+ target_schema=target_schema,
475
+ include_labels=include_labels,
476
+ exclude_labels=exclude_labels,
477
+ )
478
+ prefix_parts = [target_schema]
479
+ if target_catalog:
480
+ prefix_parts.insert(0, target_catalog)
481
+ prefix = ".".join(prefix_parts)
482
+ return [
483
+ {
484
+ "name": v.name,
485
+ "fully_qualified_name": f"{prefix}.{v.name}",
486
+ "source": v.source.value,
487
+ "source_label": v.source_label,
488
+ "description": v.description,
489
+ "columns": list(v.columns),
490
+ }
491
+ for v in views
492
+ ]
493
+
494
+
495
+ __all__ = [
496
+ "check_data_quality",
497
+ "execute_query",
498
+ "explain_query",
499
+ "get_schema",
500
+ "list_node_labels",
501
+ "list_relationship_types",
502
+ "suggest_queries",
503
+ "generate_views",
504
+ ]
@@ -0,0 +1,79 @@
1
+ """
2
+ ProGraph Natural Language Interface.
3
+
4
+ Enables querying ProGraph using natural language, powered by LLMs.
5
+ Supports multiple providers (Databricks, OpenAI) and multi-turn conversations.
6
+
7
+ Example:
8
+ >>> from prograph import ProGraph
9
+ >>> from prograph.nlp import NaturalLanguageInterface
10
+ >>> from prograph.nlp.providers import DatabricksLLMClient
11
+
12
+ >>> # Setup
13
+ >>> engine = ProGraph(backend='spark', schema=schema, dataframes=dfs)
14
+ >>> llm = DatabricksLLMClient()
15
+ >>> nl = NaturalLanguageInterface(engine, llm)
16
+
17
+ >>> # Query
18
+ >>> result = nl.ask("Find customers who placed more than 10 orders")
19
+ >>> print(result.generated_query)
20
+ >>> print(result.results)
21
+
22
+ >>> # Follow-up
23
+ >>> result2 = nl.ask("Now filter to France only",
24
+ ... conversation_id=result.conversation_id)
25
+ """
26
+
27
+ from prograph.nlp.client import (
28
+ CompletionResponse,
29
+ LLMClient,
30
+ LLMError,
31
+ LLMAPIError,
32
+ LLMAuthenticationError,
33
+ LLMRateLimitError,
34
+ Message,
35
+ Tool,
36
+ ToolCall,
37
+ )
38
+ from prograph.nlp.interface import (
39
+ ConversationContext,
40
+ NaturalLanguageInterface,
41
+ QueryResult,
42
+ )
43
+ from prograph.nlp.schema_context import SchemaContextBuilder
44
+
45
+ __all__ = [
46
+ # Main interface
47
+ "NaturalLanguageInterface",
48
+ "QueryResult",
49
+ "ConversationContext",
50
+ # LLM client base
51
+ "LLMClient",
52
+ "Message",
53
+ "Tool",
54
+ "ToolCall",
55
+ "CompletionResponse",
56
+ # Errors
57
+ "LLMError",
58
+ "LLMAPIError",
59
+ "LLMAuthenticationError",
60
+ "LLMRateLimitError",
61
+ # Schema context
62
+ "SchemaContextBuilder",
63
+ ]
64
+
65
+ # Lazy imports for providers to avoid import errors when dependencies not installed
66
+ def __getattr__(name: str):
67
+ if name == "DatabricksLLMClient":
68
+ from prograph.nlp.providers.databricks import DatabricksLLMClient
69
+ return DatabricksLLMClient
70
+ elif name == "OpenAILLMClient":
71
+ from prograph.nlp.providers.openai import OpenAILLMClient
72
+ return OpenAILLMClient
73
+ elif name == "create_prograph_tool":
74
+ from prograph.nlp.databricks_tools import create_prograph_tool
75
+ return create_prograph_tool
76
+ elif name == "get_prograph_toolkit":
77
+ from prograph.nlp.databricks_tools import get_prograph_toolkit
78
+ return get_prograph_toolkit
79
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")