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/nlp/client.py ADDED
@@ -0,0 +1,305 @@
1
+ """
2
+ Base LLM client interface with OpenAI-compatible message format.
3
+
4
+ This module defines the abstract interface for LLM providers, using
5
+ OpenAI's message format as the standard. This allows ProGraph to work
6
+ with Databricks Foundation Model APIs, OpenAI, Anthropic, and other
7
+ providers through a consistent interface.
8
+ """
9
+
10
+ import logging
11
+ from abc import ABC, abstractmethod
12
+ from dataclasses import dataclass, field
13
+ from typing import Any, Callable, Dict, List, Optional
14
+ from prograph.rules import home
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+
19
+ @dataclass
20
+ class Message:
21
+ """
22
+ OpenAI-compatible message format.
23
+
24
+ Attributes:
25
+ role: The role of the message sender. One of:
26
+ - "system": System instructions
27
+ - "user": User input
28
+ - "assistant": Model response
29
+ - "tool": Tool/function response
30
+ content: The text content of the message.
31
+ tool_calls: List of tool calls made by the assistant (if any).
32
+ tool_call_id: ID of the tool call this message responds to (for tool role).
33
+ name: Optional name for the message sender.
34
+ """
35
+
36
+ role: str
37
+ content: str
38
+ tool_calls: Optional[List[Dict[str, Any]]] = None
39
+ tool_call_id: Optional[str] = None
40
+ name: Optional[str] = None
41
+
42
+ def to_dict(self) -> Dict[str, Any]:
43
+ """Convert to OpenAI API format."""
44
+ result: Dict[str, Any] = {"role": self.role, "content": self.content}
45
+ if self.tool_calls is not None:
46
+ result["tool_calls"] = self.tool_calls
47
+ if self.tool_call_id is not None:
48
+ result["tool_call_id"] = self.tool_call_id
49
+ if self.name is not None:
50
+ result["name"] = self.name
51
+ return result
52
+
53
+ @classmethod
54
+ def system(cls, content: str) -> "Message":
55
+ """Create a system message."""
56
+ return cls(role="system", content=content)
57
+
58
+ @classmethod
59
+ def user(cls, content: str) -> "Message":
60
+ """Create a user message."""
61
+ return cls(role="user", content=content)
62
+
63
+ @classmethod
64
+ def assistant(
65
+ cls, content: str, tool_calls: Optional[List[Dict[str, Any]]] = None
66
+ ) -> "Message":
67
+ """Create an assistant message."""
68
+ return cls(role="assistant", content=content, tool_calls=tool_calls)
69
+
70
+ @classmethod
71
+ def tool(cls, content: str, tool_call_id: str) -> "Message":
72
+ """Create a tool response message."""
73
+ return cls(role="tool", content=content, tool_call_id=tool_call_id)
74
+
75
+
76
+ @dataclass
77
+ class Tool:
78
+ """
79
+ OpenAI-compatible tool/function definition.
80
+
81
+ Attributes:
82
+ name: The name of the function/tool.
83
+ description: Description of what the tool does (helps LLM decide when to use it).
84
+ parameters: JSON Schema object describing the function parameters.
85
+ """
86
+
87
+ name: str
88
+ description: str
89
+ parameters: Dict[str, Any] = field(default_factory=dict)
90
+
91
+ def to_dict(self) -> Dict[str, Any]:
92
+ """Convert to OpenAI API format."""
93
+ return {
94
+ "type": "function",
95
+ "function": {
96
+ "name": self.name,
97
+ "description": self.description,
98
+ "parameters": self.parameters,
99
+ },
100
+ }
101
+
102
+
103
+ @dataclass
104
+ class ToolCall:
105
+ """
106
+ Represents a tool call made by the model.
107
+
108
+ Attributes:
109
+ id: Unique identifier for this tool call.
110
+ name: Name of the function to call.
111
+ arguments: JSON string of function arguments.
112
+ """
113
+
114
+ id: str
115
+ name: str
116
+ arguments: str
117
+
118
+ def to_dict(self) -> Dict[str, Any]:
119
+ """Convert to OpenAI API format."""
120
+ return {
121
+ "id": self.id,
122
+ "type": "function",
123
+ "function": {"name": self.name, "arguments": self.arguments},
124
+ }
125
+
126
+
127
+ @dataclass
128
+ class CompletionResponse:
129
+ """
130
+ Standardized response from LLM completion.
131
+
132
+ Attributes:
133
+ content: The text content of the response (may be empty if tool_calls present).
134
+ tool_calls: List of tool calls made by the model (if any).
135
+ usage: Token usage statistics (prompt_tokens, completion_tokens, total_tokens).
136
+ finish_reason: Why the model stopped generating (stop, tool_calls, length, etc.).
137
+ model: The model that generated the response.
138
+ """
139
+
140
+ content: str
141
+ tool_calls: Optional[List[ToolCall]] = None
142
+ usage: Optional[Dict[str, int]] = None
143
+ finish_reason: Optional[str] = None
144
+ model: Optional[str] = None
145
+
146
+ @property
147
+ def has_tool_calls(self) -> bool:
148
+ """Check if response contains tool calls."""
149
+ return self.tool_calls is not None and len(self.tool_calls) > 0
150
+
151
+
152
+ class LLMClient(ABC):
153
+ """
154
+ Abstract base class for pluggable LLM providers.
155
+
156
+ Implementations should handle authentication, API calls, and response
157
+ parsing for their specific provider while exposing a consistent interface.
158
+
159
+ Example:
160
+ >>> client = DatabricksLLMClient()
161
+ >>> messages = [Message.user("What is 2+2?")]
162
+ >>> response = client.complete(messages)
163
+ >>> print(response.content)
164
+ "2 + 2 = 4"
165
+ """
166
+
167
+ @abstractmethod
168
+ def complete(
169
+ self,
170
+ messages: List[Message],
171
+ tools: Optional[List[Tool]] = None,
172
+ tool_choice: str = "auto",
173
+ temperature: Optional[float] = 0.0,
174
+ max_tokens: Optional[int] = None,
175
+ ) -> CompletionResponse:
176
+ """
177
+ Generate a completion for the given messages.
178
+
179
+ Args:
180
+ messages: List of messages in the conversation.
181
+ tools: Optional list of tools the model can call.
182
+ tool_choice: How the model should choose tools:
183
+ - "auto": Model decides whether to call tools
184
+ - "none": Never call tools
185
+ - "required": Must call at least one tool
186
+ temperature: Sampling temperature (0.0 = deterministic);
187
+ None sends none. A model that refuses the parameter is
188
+ asked again without it (`_send_with_temperature`).
189
+ max_tokens: Maximum tokens in the response.
190
+
191
+ Returns:
192
+ CompletionResponse with the model's response; its `content` is
193
+ the answer's text as a string (`answer_text`).
194
+
195
+ Raises:
196
+ LLMError: If the API call fails.
197
+ """
198
+ pass
199
+
200
+ def _send_with_temperature(
201
+ self,
202
+ send: Callable[[Dict[str, Any]], Any],
203
+ request: Dict[str, Any],
204
+ temperature: Optional[float],
205
+ ) -> Any:
206
+ """`send(request)` with `temperature` in it, where the model takes it.
207
+
208
+ Claude from Opus 4.7 and Sonnet 5 on, and OpenAI's reasoning models,
209
+ refuse a sampling temperature with a 400. Which models
210
+ do is the provider's to say and changes with each release, so the
211
+ client does not keep a list: a 400 that names the temperature is
212
+ asked again once without it, and the client sends none for the rest
213
+ of its life. A model that takes it keeps the deterministic 0.0."""
214
+ if temperature is None or getattr(self, "_temperature_refused", False):
215
+ return send(request)
216
+ try:
217
+ return send({**request, "temperature": temperature})
218
+ except Exception as error:
219
+ if not refuses_temperature(error):
220
+ raise
221
+ self._temperature_refused = True
222
+ logger.info("llm_temperature_refused model=%s", self.model_name)
223
+ return send(request)
224
+
225
+ @abstractmethod
226
+ def supports_function_calling(self) -> bool:
227
+ """
228
+ Check if this provider supports function/tool calling.
229
+
230
+ Returns:
231
+ True if the provider supports tools, False otherwise.
232
+ """
233
+ pass
234
+
235
+ @property
236
+ @abstractmethod
237
+ def model_name(self) -> str:
238
+ """Get the name of the model being used."""
239
+ pass
240
+
241
+
242
+ def refuses_temperature(error: BaseException) -> bool:
243
+ """Whether a provider's error is a 400 refusing the temperature."""
244
+ status = getattr(error, "status_code", None)
245
+ if status != 400:
246
+ return False
247
+ text = getattr(error, "message", None) or str(error)
248
+ return "temperature" in str(text).lower()
249
+
250
+
251
+ @home("model-answer-text", "A model's answer and its temperature (NLP)",
252
+ terms=("answer_text", "temperature", "refuses_temperature", "LLM client", "provider"))
253
+ def answer_text(content: Any) -> str:
254
+ """The text of a model's answer, as a string.
255
+
256
+ An OpenAI-compatible answer's content is a string, or, from a model
257
+ that reasons (Claude 5.5 on Databricks), a list of parts: a
258
+ `reasoning` part with its summary and signature, then a `text` part.
259
+ Anthropic's Messages API answers a list of blocks of the same kinds.
260
+ The answer is the `text` parts joined; reasoning, thinking and every
261
+ other kind of part are not the answer. Parts may be dicts or SDK
262
+ objects."""
263
+ if content is None:
264
+ return ""
265
+ if isinstance(content, str):
266
+ return content
267
+ parts = content if isinstance(content, (list, tuple)) else [content]
268
+ texts = []
269
+ for part in parts:
270
+ if isinstance(part, str):
271
+ texts.append(part)
272
+ continue
273
+ if isinstance(part, dict):
274
+ kind, text = part.get("type"), part.get("text")
275
+ else:
276
+ kind, text = getattr(part, "type", None), getattr(part, "text", None)
277
+ if kind == "text" and isinstance(text, str):
278
+ texts.append(text)
279
+ return "".join(texts)
280
+
281
+
282
+ class LLMError(Exception):
283
+ """Base exception for LLM client errors."""
284
+
285
+ pass
286
+
287
+
288
+ class LLMAuthenticationError(LLMError):
289
+ """Raised when authentication fails."""
290
+
291
+ pass
292
+
293
+
294
+ class LLMRateLimitError(LLMError):
295
+ """Raised when rate limit is exceeded."""
296
+
297
+ pass
298
+
299
+
300
+ class LLMAPIError(LLMError):
301
+ """Raised when the API returns an error."""
302
+
303
+ def __init__(self, message: str, status_code: Optional[int] = None):
304
+ super().__init__(message)
305
+ self.status_code = status_code
@@ -0,0 +1,369 @@
1
+ """
2
+ Databricks Unity Catalog function registration for ProGraph.
3
+
4
+ Enables registering ProGraph as a tool that can be used by
5
+ Databricks AI agents and LangChain/LangGraph applications.
6
+ """
7
+
8
+ import json
9
+ from typing import TYPE_CHECKING, Any, Dict, List, Optional
10
+
11
+ if TYPE_CHECKING:
12
+ from prograph import ProGraph
13
+
14
+ # Check for Databricks SDK availability
15
+ try:
16
+ from databricks.sdk import WorkspaceClient
17
+ from databricks.sdk.service.catalog import FunctionInfo
18
+
19
+ DATABRICKS_SDK_AVAILABLE = True
20
+ except ImportError:
21
+ DATABRICKS_SDK_AVAILABLE = False
22
+ WorkspaceClient = None # type: ignore
23
+
24
+ # Check for UC Function Client availability
25
+ try:
26
+ from unitycatalog.ai.core.databricks import DatabricksFunctionClient
27
+
28
+ UC_FUNCTION_CLIENT_AVAILABLE = True
29
+ except ImportError:
30
+ UC_FUNCTION_CLIENT_AVAILABLE = False
31
+ DatabricksFunctionClient = None # type: ignore
32
+
33
+ # Check for LangChain integration availability
34
+ try:
35
+ from databricks_langchain import UCFunctionToolkit
36
+
37
+ LANGCHAIN_AVAILABLE = True
38
+ except ImportError:
39
+ LANGCHAIN_AVAILABLE = False
40
+ UCFunctionToolkit = None # type: ignore
41
+
42
+
43
+ class ProGraphToolError(Exception):
44
+ """Error creating or registering ProGraph tools."""
45
+
46
+ pass
47
+
48
+
49
+ def create_prograph_tool(
50
+ engine: "ProGraph",
51
+ catalog: str,
52
+ schema: str,
53
+ function_name: str = "execute_graph_query",
54
+ replace: bool = True,
55
+ ) -> str:
56
+ """
57
+ Register ProGraph as a Unity Catalog function tool.
58
+
59
+ Creates a UC function that accepts Cypher and SPARQL queries and
60
+ executes them against the provided ProGraph engine. This function
61
+ can then be used as a tool by Databricks AI agents.
62
+
63
+ Args:
64
+ engine: ProGraph engine instance to use for execution.
65
+ catalog: Unity Catalog catalog name.
66
+ schema: Unity Catalog schema name.
67
+ function_name: Name for the function (default: execute_graph_query).
68
+ replace: Whether to replace existing function.
69
+
70
+ Returns:
71
+ Fully qualified function name (catalog.schema.function_name).
72
+
73
+ Raises:
74
+ ProGraphToolError: If registration fails or dependencies missing.
75
+
76
+ Example:
77
+ >>> tool_name = create_prograph_tool(
78
+ ... engine=engine,
79
+ ... catalog="my_catalog",
80
+ ... schema="my_schema"
81
+ ... )
82
+ >>> print(tool_name)
83
+ "my_catalog.my_schema.execute_graph_query"
84
+ """
85
+ if not UC_FUNCTION_CLIENT_AVAILABLE:
86
+ raise ProGraphToolError(
87
+ "Unity Catalog function client not available. "
88
+ "Install with: pip install unitycatalog-ai-core"
89
+ )
90
+
91
+ # Create the function that will be registered
92
+ def execute_graph_query(
93
+ query: str,
94
+ language: str = "sparql",
95
+ ) -> str:
96
+ """
97
+ Execute a graph query against ProGraph.
98
+
99
+ This tool queries a graph over existing tables with SPARQL; the
100
+ graph is read from the data sources without copying them.
101
+
102
+ Args:
103
+ query: The SPARQL query to execute.
104
+ language: Query language: "sparql" (the default) or "cypher".
105
+
106
+ Returns:
107
+ JSON string containing the query results as a list of dictionaries.
108
+ """
109
+ try:
110
+ results = engine.execute(query, language=language, return_type="list")
111
+ return json.dumps(results, default=str)
112
+ except Exception as e:
113
+ return json.dumps({"error": str(e)})
114
+
115
+ # Register the function with Unity Catalog
116
+ try:
117
+ client = DatabricksFunctionClient()
118
+ function_info = client.create_python_function(
119
+ func=execute_graph_query,
120
+ catalog=catalog,
121
+ schema=schema,
122
+ replace=replace,
123
+ )
124
+
125
+ full_name = f"{catalog}.{schema}.{function_name}"
126
+ return full_name
127
+
128
+ except Exception as e:
129
+ raise ProGraphToolError(f"Failed to register function: {e}")
130
+
131
+
132
+ def create_schema_tool(
133
+ engine: "ProGraph",
134
+ catalog: str,
135
+ schema: str,
136
+ function_name: str = "get_graph_schema",
137
+ replace: bool = True,
138
+ ) -> str:
139
+ """
140
+ Register a schema description tool for ProGraph.
141
+
142
+ Creates a UC function that returns the graph schema description,
143
+ useful for agents to understand what queries are possible.
144
+
145
+ Args:
146
+ engine: ProGraph engine instance.
147
+ catalog: Unity Catalog catalog name.
148
+ schema: Unity Catalog schema name.
149
+ function_name: Name for the function.
150
+ replace: Whether to replace existing function.
151
+
152
+ Returns:
153
+ Fully qualified function name.
154
+ """
155
+ if not UC_FUNCTION_CLIENT_AVAILABLE:
156
+ raise ProGraphToolError(
157
+ "Unity Catalog function client not available. "
158
+ "Install with: pip install unitycatalog-ai-core"
159
+ )
160
+
161
+ from prograph.nlp.schema_context import SchemaContextBuilder
162
+
163
+ context_builder = SchemaContextBuilder(engine)
164
+
165
+ def get_graph_schema() -> str:
166
+ """
167
+ Get the schema description of the ProGraph virtual graph.
168
+
169
+ Returns a description of available node labels, relationship types,
170
+ and their properties. Use this to understand what queries are possible.
171
+
172
+ Returns:
173
+ Markdown-formatted schema description.
174
+ """
175
+ return context_builder.build_schema_description()
176
+
177
+ try:
178
+ client = DatabricksFunctionClient()
179
+ client.create_python_function(
180
+ func=get_graph_schema,
181
+ catalog=catalog,
182
+ schema=schema,
183
+ replace=replace,
184
+ )
185
+
186
+ return f"{catalog}.{schema}.{function_name}"
187
+
188
+ except Exception as e:
189
+ raise ProGraphToolError(f"Failed to register schema function: {e}")
190
+
191
+
192
+ def get_prograph_toolkit(
193
+ function_names: List[str],
194
+ ) -> Any:
195
+ """
196
+ Get a LangChain-compatible toolkit for ProGraph tools.
197
+
198
+ Wraps registered UC functions in a UCFunctionToolkit for use
199
+ with LangChain agents and LangGraph applications.
200
+
201
+ Args:
202
+ function_names: List of fully qualified UC function names.
203
+
204
+ Returns:
205
+ UCFunctionToolkit instance.
206
+
207
+ Raises:
208
+ ProGraphToolError: If LangChain integration not available.
209
+
210
+ Example:
211
+ >>> toolkit = get_prograph_toolkit([
212
+ ... "my_catalog.my_schema.execute_graph_query",
213
+ ... "my_catalog.my_schema.get_graph_schema"
214
+ ... ])
215
+ >>> tools = toolkit.tools
216
+ """
217
+ if not LANGCHAIN_AVAILABLE:
218
+ raise ProGraphToolError(
219
+ "LangChain integration not available. "
220
+ "Install with: pip install databricks-langchain"
221
+ )
222
+
223
+ return UCFunctionToolkit(function_names=function_names)
224
+
225
+
226
+ def get_tool_definitions() -> List[Dict[str, Any]]:
227
+ """
228
+ Get OpenAI-compatible tool definitions for ProGraph.
229
+
230
+ Returns tool definitions in the format expected by OpenAI's
231
+ function calling API, suitable for use with any compatible LLM.
232
+
233
+ Returns:
234
+ List of tool definition dictionaries.
235
+ """
236
+ return [
237
+ {
238
+ "type": "function",
239
+ "function": {
240
+ "name": "execute_graph_query",
241
+ "description": (
242
+ "Execute a graph query against ProGraph virtual graph. "
243
+ "Supports Cypher and SPARQL query languages for pattern "
244
+ "matching, traversals, and aggregations over connected data."
245
+ ),
246
+ "parameters": {
247
+ "type": "object",
248
+ "properties": {
249
+ "query": {
250
+ "type": "string",
251
+ "description": (
252
+ "The SPARQL query to execute (SELECT, ASK, CONSTRUCT)."
253
+ ),
254
+ },
255
+ "language": {
256
+ "type": "string",
257
+ "enum": ["sparql"],
258
+ "description": "Query language to use.",
259
+ "default": "sparql",
260
+ },
261
+ },
262
+ "required": ["query"],
263
+ },
264
+ },
265
+ },
266
+ {
267
+ "type": "function",
268
+ "function": {
269
+ "name": "get_graph_schema",
270
+ "description": (
271
+ "Get the schema of the ProGraph virtual graph. "
272
+ "Returns available node labels, relationship types, "
273
+ "and their properties to help construct valid queries."
274
+ ),
275
+ "parameters": {
276
+ "type": "object",
277
+ "properties": {},
278
+ "required": [],
279
+ },
280
+ },
281
+ },
282
+ ]
283
+
284
+
285
+ def create_agent_executor(
286
+ engine: "ProGraph",
287
+ llm_client: Any,
288
+ catalog: Optional[str] = None,
289
+ schema: Optional[str] = None,
290
+ ) -> Any:
291
+ """
292
+ Create a LangChain agent executor with ProGraph tools.
293
+
294
+ Convenience function that sets up a complete agent with ProGraph
295
+ query capabilities.
296
+
297
+ Args:
298
+ engine: ProGraph engine instance.
299
+ llm_client: LangChain-compatible LLM.
300
+ catalog: Optional UC catalog for tool registration.
301
+ schema: Optional UC schema for tool registration.
302
+
303
+ Returns:
304
+ AgentExecutor instance.
305
+
306
+ Raises:
307
+ ProGraphToolError: If LangChain not available.
308
+ """
309
+ if not LANGCHAIN_AVAILABLE:
310
+ raise ProGraphToolError(
311
+ "LangChain integration not available. "
312
+ "Install with: pip install databricks-langchain langchain"
313
+ )
314
+
315
+ try:
316
+ from langchain.agents import AgentExecutor, create_tool_calling_agent
317
+ from langchain.prompts import ChatPromptTemplate
318
+ except ImportError:
319
+ raise ProGraphToolError(
320
+ "LangChain not available. Install with: pip install langchain"
321
+ )
322
+
323
+ # Register tools if catalog/schema provided
324
+ if catalog and schema:
325
+ query_tool = create_prograph_tool(engine, catalog, schema)
326
+ schema_tool = create_schema_tool(engine, catalog, schema)
327
+ toolkit = get_prograph_toolkit([query_tool, schema_tool])
328
+ tools = toolkit.tools
329
+ else:
330
+ # Use local tools without UC registration
331
+ from prograph.nlp.schema_context import SchemaContextBuilder
332
+
333
+ context_builder = SchemaContextBuilder(engine)
334
+
335
+ # Create simple tool wrappers
336
+ from langchain.tools import Tool
337
+
338
+ def execute_query(query: str) -> str:
339
+ try:
340
+ results = engine.execute(query, return_type="list")
341
+ return json.dumps(results, default=str)
342
+ except Exception as e:
343
+ return json.dumps({"error": str(e)})
344
+
345
+ def get_schema() -> str:
346
+ return context_builder.build_schema_description()
347
+
348
+ tools = [
349
+ Tool(
350
+ name="execute_graph_query",
351
+ description="Execute a Cypher or SPARQL query against the graph",
352
+ func=execute_query,
353
+ ),
354
+ Tool(
355
+ name="get_graph_schema",
356
+ description="Get the schema of the graph",
357
+ func=get_schema,
358
+ ),
359
+ ]
360
+
361
+ # Create agent
362
+ prompt = ChatPromptTemplate.from_messages([
363
+ ("system", "You are a graph analytics assistant. Use the provided tools to query and analyze the graph."),
364
+ ("human", "{input}"),
365
+ ("placeholder", "{agent_scratchpad}"),
366
+ ])
367
+
368
+ agent = create_tool_calling_agent(llm_client, tools, prompt)
369
+ return AgentExecutor(agent=agent, tools=tools, verbose=True)