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
@@ -0,0 +1,274 @@
1
+ """
2
+ Anthropic API LLM client.
3
+
4
+ Direct integration with Anthropic API for Claude models.
5
+ """
6
+
7
+ import os
8
+ from typing import Any, Dict, List, Optional
9
+
10
+ from prograph.nlp.client import (
11
+ CompletionResponse,
12
+ LLMAPIError,
13
+ LLMAuthenticationError,
14
+ LLMClient,
15
+ LLMError,
16
+ LLMRateLimitError,
17
+ Message,
18
+ Tool,
19
+ ToolCall,
20
+ answer_text,
21
+ )
22
+
23
+ # Check for Anthropic SDK availability
24
+ try:
25
+ import anthropic
26
+ from anthropic import Anthropic, APIError, AuthenticationError, RateLimitError
27
+
28
+ ANTHROPIC_SDK_AVAILABLE = True
29
+ except ImportError:
30
+ ANTHROPIC_SDK_AVAILABLE = False
31
+ Anthropic = None # type: ignore
32
+
33
+
34
+ class AnthropicLLMClient(LLMClient):
35
+ """
36
+ LLM client using Anthropic API directly.
37
+
38
+ For use with Claude models in non-Databricks environments.
39
+
40
+ Example:
41
+ >>> # From environment variable
42
+ >>> client = AnthropicLLMClient()
43
+
44
+ >>> # Explicit API key
45
+ >>> client = AnthropicLLMClient(
46
+ ... model="claude-sonnet-4-20250514",
47
+ ... api_key="sk-ant-..."
48
+ ... )
49
+
50
+ >>> messages = [Message.user("Explain graph databases")]
51
+ >>> response = client.complete(messages)
52
+ """
53
+
54
+
55
+ def __init__(
56
+ self,
57
+ model: str = "claude-sonnet-4-20250514",
58
+ api_key: Optional[str] = None,
59
+ base_url: Optional[str] = None,
60
+ timeout: float = 120.0,
61
+ max_tokens: int = 4096,
62
+ ):
63
+ """
64
+ Initialize Anthropic LLM client.
65
+
66
+ Args:
67
+ model: Model name (e.g., "claude-sonnet-4-20250514", "claude-3-5-sonnet-20241022").
68
+ api_key: Anthropic API key. Uses ANTHROPIC_API_KEY env var if not provided.
69
+ base_url: Optional custom base URL.
70
+ timeout: Request timeout in seconds.
71
+ max_tokens: Default maximum tokens for responses.
72
+
73
+ Raises:
74
+ LLMError: If Anthropic SDK is not installed.
75
+ LLMAuthenticationError: If API key is not found.
76
+ """
77
+ if not ANTHROPIC_SDK_AVAILABLE:
78
+ raise LLMError(
79
+ "Anthropic SDK is required. Install with: pip install anthropic"
80
+ )
81
+
82
+ self._model = model
83
+ self._timeout = timeout
84
+ self._default_max_tokens = max_tokens
85
+
86
+ # Get API key from environment if not provided
87
+ if api_key is None:
88
+ api_key = os.environ.get("ANTHROPIC_API_KEY")
89
+ if api_key is None:
90
+ raise LLMAuthenticationError(
91
+ "Anthropic API key not found. "
92
+ "Set ANTHROPIC_API_KEY environment variable or pass api_key parameter."
93
+ )
94
+
95
+ # Build client kwargs
96
+ client_kwargs: Dict[str, Any] = {
97
+ "api_key": api_key,
98
+ "timeout": timeout,
99
+ }
100
+ if base_url:
101
+ client_kwargs["base_url"] = base_url
102
+
103
+ self._client = Anthropic(**client_kwargs)
104
+
105
+ def _convert_messages(
106
+ self, messages: List[Message]
107
+ ) -> tuple[Optional[str], List[Dict[str, Any]]]:
108
+ """
109
+ Convert OpenAI-style messages to Anthropic format.
110
+
111
+ Anthropic separates system message from conversation messages.
112
+
113
+ Returns:
114
+ Tuple of (system_message, conversation_messages)
115
+ """
116
+ system_message = None
117
+ conversation = []
118
+
119
+ for msg in messages:
120
+ if msg.role == "system":
121
+ # Anthropic takes system as a separate parameter
122
+ system_message = msg.content
123
+ elif msg.role == "user":
124
+ conversation.append({"role": "user", "content": msg.content})
125
+ elif msg.role == "assistant":
126
+ content: Any = msg.content
127
+ # Handle tool calls in assistant messages
128
+ if msg.tool_calls:
129
+ content = []
130
+ if msg.content:
131
+ content.append({"type": "text", "text": msg.content})
132
+ for tc in msg.tool_calls:
133
+ content.append({
134
+ "type": "tool_use",
135
+ "id": tc["id"],
136
+ "name": tc["function"]["name"],
137
+ "input": tc["function"]["arguments"],
138
+ })
139
+ conversation.append({"role": "assistant", "content": content})
140
+ elif msg.role == "tool":
141
+ # Anthropic uses tool_result in user messages
142
+ conversation.append({
143
+ "role": "user",
144
+ "content": [{
145
+ "type": "tool_result",
146
+ "tool_use_id": msg.tool_call_id,
147
+ "content": msg.content,
148
+ }]
149
+ })
150
+
151
+ return system_message, conversation
152
+
153
+ def _convert_tools(self, tools: List[Tool]) -> List[Dict[str, Any]]:
154
+ """Convert OpenAI-style tools to Anthropic format."""
155
+ anthropic_tools = []
156
+ for tool in tools:
157
+ anthropic_tools.append({
158
+ "name": tool.name,
159
+ "description": tool.description,
160
+ "input_schema": tool.parameters,
161
+ })
162
+ return anthropic_tools
163
+
164
+ def complete(
165
+ self,
166
+ messages: List[Message],
167
+ tools: Optional[List[Tool]] = None,
168
+ tool_choice: str = "auto",
169
+ temperature: Optional[float] = 0.0,
170
+ max_tokens: Optional[int] = None,
171
+ ) -> CompletionResponse:
172
+ """
173
+ Generate a completion using Anthropic API.
174
+
175
+ Args:
176
+ messages: Conversation messages.
177
+ tools: Optional tools for function calling.
178
+ tool_choice: Tool selection strategy ("auto", "none", "required").
179
+ temperature: Sampling temperature; None sends none, and a
180
+ model that refuses it is asked again without it.
181
+ max_tokens: Maximum response tokens.
182
+
183
+ Returns:
184
+ CompletionResponse with the model's response.
185
+
186
+ Raises:
187
+ LLMAuthenticationError: If authentication fails.
188
+ LLMRateLimitError: If rate limit is exceeded.
189
+ LLMAPIError: For other API errors.
190
+ """
191
+ try:
192
+ # Convert messages to Anthropic format
193
+ system_message, conversation = self._convert_messages(messages)
194
+
195
+ # Build request
196
+ request_kwargs: Dict[str, Any] = {
197
+ "model": self._model,
198
+ "messages": conversation,
199
+ "max_tokens": max_tokens or self._default_max_tokens,
200
+ }
201
+
202
+ if system_message:
203
+ request_kwargs["system"] = system_message
204
+
205
+ if tools is not None and len(tools) > 0:
206
+ request_kwargs["tools"] = self._convert_tools(tools)
207
+ # Map tool_choice to Anthropic format
208
+ if tool_choice == "required":
209
+ request_kwargs["tool_choice"] = {"type": "any"}
210
+ elif tool_choice == "none":
211
+ # Don't include tools if none selected
212
+ del request_kwargs["tools"]
213
+ # "auto" is the default in Anthropic
214
+
215
+ # Make API call
216
+ response = self._send_with_temperature(
217
+ lambda request: self._client.messages.create(**request),
218
+ request_kwargs,
219
+ temperature,
220
+ )
221
+
222
+ # Parse response
223
+ content_text = answer_text(response.content)
224
+ tool_calls = []
225
+
226
+ for block in response.content:
227
+ if block.type == "tool_use":
228
+ # Convert tool arguments to JSON string if needed
229
+ import json
230
+ args = block.input
231
+ if isinstance(args, dict):
232
+ args = json.dumps(args)
233
+ tool_calls.append(
234
+ ToolCall(
235
+ id=block.id,
236
+ name=block.name,
237
+ arguments=args,
238
+ )
239
+ )
240
+
241
+ # Build usage dict
242
+ usage = None
243
+ if response.usage:
244
+ usage = {
245
+ "prompt_tokens": response.usage.input_tokens,
246
+ "completion_tokens": response.usage.output_tokens,
247
+ "total_tokens": response.usage.input_tokens + response.usage.output_tokens,
248
+ }
249
+
250
+ return CompletionResponse(
251
+ content=content_text,
252
+ tool_calls=tool_calls if tool_calls else None,
253
+ usage=usage,
254
+ finish_reason=response.stop_reason,
255
+ model=response.model,
256
+ )
257
+
258
+ except AuthenticationError as e:
259
+ raise LLMAuthenticationError(f"Anthropic authentication failed: {e}")
260
+ except RateLimitError as e:
261
+ raise LLMRateLimitError(f"Anthropic rate limit exceeded: {e}")
262
+ except APIError as e:
263
+ raise LLMAPIError(f"Anthropic API error: {e}", status_code=getattr(e, 'status_code', None))
264
+ except Exception as e:
265
+ raise LLMError(f"Unexpected error calling Anthropic: {e}")
266
+
267
+ def supports_function_calling(self) -> bool:
268
+ """Claude models support function calling."""
269
+ return True
270
+
271
+ @property
272
+ def model_name(self) -> str:
273
+ """Get the model name."""
274
+ return self._model
@@ -0,0 +1,312 @@
1
+ """
2
+ Databricks Foundation Model APIs LLM client.
3
+
4
+ Uses Databricks serving endpoints with OpenAI-compatible API.
5
+ Supports auto-detection of workspace URL and token from environment.
6
+ """
7
+
8
+ import json
9
+ import logging
10
+ import os
11
+ from typing import Any, Dict, List, Optional
12
+
13
+ logger = logging.getLogger(__name__)
14
+
15
+ from prograph.nlp.client import (
16
+ CompletionResponse,
17
+ LLMAPIError,
18
+ LLMAuthenticationError,
19
+ LLMClient,
20
+ LLMError,
21
+ LLMRateLimitError,
22
+ Message,
23
+ Tool,
24
+ ToolCall,
25
+ answer_text,
26
+ )
27
+
28
+ # Check for OpenAI SDK availability
29
+ try:
30
+ from openai import OpenAI, APIError, AuthenticationError, RateLimitError
31
+
32
+ OPENAI_SDK_AVAILABLE = True
33
+ except ImportError:
34
+ OPENAI_SDK_AVAILABLE = False
35
+ OpenAI = None # type: ignore
36
+
37
+
38
+ # The model ProGraph writes queries with when none is named, on Databricks Model Serving: the one
39
+ # measured best on the accuracy set (docs/sparql/databricks.md, "How well ask answers";
40
+ # tests/nlp/accuracy). `prograph serve --mcp`, `prograph-mcp --sparql` and this client all use it.
41
+ DEFAULT_MODEL = "databricks-claude-sonnet-4-5"
42
+
43
+
44
+ class DatabricksLLMClient(LLMClient):
45
+ """
46
+ LLM client using Databricks Foundation Model APIs.
47
+
48
+ Uses the OpenAI SDK with Databricks-specific base URL and authentication.
49
+ Supports auto-detection of workspace configuration from Databricks runtime
50
+ environment or explicit configuration.
51
+
52
+ Example:
53
+ >>> # Auto-detect from Databricks environment
54
+ >>> client = DatabricksLLMClient()
55
+
56
+ >>> # Explicit configuration
57
+ >>> client = DatabricksLLMClient(
58
+ ... model="databricks-claude-sonnet-4-5",
59
+ ... workspace_url="https://my-workspace.cloud.databricks.com",
60
+ ... token="dapi..."
61
+ ... )
62
+
63
+ >>> messages = [Message.user("Explain graph databases")]
64
+ >>> response = client.complete(messages)
65
+ """
66
+
67
+
68
+ def __init__(
69
+ self,
70
+ model: str = DEFAULT_MODEL,
71
+ workspace_url: Optional[str] = None,
72
+ token: Optional[str] = None,
73
+ timeout: float = 120.0,
74
+ ):
75
+ """
76
+ Initialize Databricks LLM client.
77
+
78
+ Args:
79
+ model: A Model Serving endpoint's name (default DEFAULT_MODEL).
80
+ workspace_url: Databricks workspace URL. Auto-detected if not provided.
81
+ token: Databricks API token. Auto-detected if not provided.
82
+ timeout: Request timeout in seconds.
83
+
84
+ Raises:
85
+ LLMError: If OpenAI SDK is not installed.
86
+ LLMAuthenticationError: If credentials cannot be detected.
87
+ """
88
+ if not OPENAI_SDK_AVAILABLE:
89
+ raise LLMError(
90
+ "OpenAI SDK is required for Databricks LLM client. "
91
+ "Install with: pip install 'prograph[nlp]' (the mcp extra includes it)"
92
+ )
93
+
94
+ self._model = model
95
+ self._timeout = timeout
96
+
97
+ # Auto-detect workspace URL
98
+ if workspace_url is None:
99
+ workspace_url = self._detect_workspace_url()
100
+ if workspace_url is None:
101
+ raise LLMAuthenticationError(
102
+ "Could not detect Databricks workspace URL. "
103
+ "Set DATABRICKS_HOST environment variable or pass workspace_url parameter."
104
+ )
105
+
106
+ # Auto-detect token. One from the SDK's configuration (a Databricks
107
+ # App's service principal by OAuth) expires within the hour, and a
108
+ # server keeps its client for its life: it is asked for at each call
109
+ # (`_fresh_token`), the configuration refreshing it.
110
+ self._config = None
111
+ if token is None:
112
+ token = self._detect_token()
113
+ if token is None:
114
+ raise LLMAuthenticationError(
115
+ "Could not detect Databricks API token. "
116
+ "Set DATABRICKS_TOKEN environment variable or pass token parameter."
117
+ )
118
+
119
+ # A Databricks App's DATABRICKS_HOST is the bare host name: as the
120
+ # base URL it had no scheme, and every call failed to connect.
121
+ if "://" not in workspace_url:
122
+ workspace_url = f"https://{workspace_url}"
123
+ # Ensure workspace URL ends with /serving-endpoints
124
+ base_url = workspace_url.rstrip("/")
125
+ if not base_url.endswith("/serving-endpoints"):
126
+ base_url = f"{base_url}/serving-endpoints"
127
+
128
+ self._client = OpenAI(
129
+ api_key=token,
130
+ base_url=base_url,
131
+ timeout=timeout,
132
+ )
133
+ self._workspace_url = workspace_url
134
+
135
+ def _detect_workspace_url(self) -> Optional[str]:
136
+ """Auto-detect Databricks workspace URL from environment."""
137
+ # Try common environment variables
138
+ for var in ["DATABRICKS_HOST", "DATABRICKS_WORKSPACE_URL"]:
139
+ url = os.environ.get(var)
140
+ if url:
141
+ return url
142
+
143
+ # Try to detect from Databricks runtime context
144
+ try:
145
+ # In Databricks notebooks, this context is available
146
+ from dbruntime.databricks_repl_context import get_context
147
+
148
+ ctx = get_context()
149
+ if ctx and hasattr(ctx, "browserHostName"):
150
+ return f"https://{ctx.browserHostName}"
151
+ except ImportError:
152
+ pass
153
+
154
+ return None
155
+
156
+ def _detect_token(self) -> Optional[str]:
157
+ """Auto-detect Databricks API token from environment or SDK config."""
158
+ # Try common environment variables
159
+ for var in ["DATABRICKS_TOKEN", "DATABRICKS_API_TOKEN"]:
160
+ token = os.environ.get(var)
161
+ if token:
162
+ return token
163
+
164
+ # Try to detect from Databricks runtime context
165
+ try:
166
+ from dbruntime.databricks_repl_context import get_context
167
+
168
+ ctx = get_context()
169
+ if ctx and hasattr(ctx, "apiToken"):
170
+ return ctx.apiToken
171
+ except ImportError:
172
+ pass
173
+
174
+ # Try to get token from databricks-sdk config
175
+ # This uses ~/.databrickscfg, OAuth, databricks-cli, or other configured auth
176
+ try:
177
+ from databricks.sdk.config import Config
178
+
179
+ # Create config - this auto-detects from environment/config files
180
+ config = Config()
181
+
182
+ # First check if there's a direct token
183
+ if config.token:
184
+ return config.token
185
+ self._config = config
186
+
187
+ # For OAuth/CLI auth, get token via authenticate()
188
+ # This works for databricks-cli, oauth-m2m, oauth-u2m, etc.
189
+ headers = config.authenticate()
190
+ if headers and 'Authorization' in headers:
191
+ auth_header = headers['Authorization']
192
+ if auth_header.startswith('Bearer '):
193
+ return auth_header[7:] # Remove 'Bearer ' prefix
194
+ except Exception as e:
195
+ logger.debug("databricks_token_extraction_failed: %s", e)
196
+ pass
197
+
198
+ return None
199
+
200
+ def _fresh_token(self) -> None:
201
+ """The client's token, current: asked of the SDK's configuration
202
+ where the token came from it, which refreshes an expired one."""
203
+ if self._config is None:
204
+ return
205
+ header = (self._config.authenticate() or {}).get("Authorization", "")
206
+ if header.startswith("Bearer "):
207
+ self._client.api_key = header[len("Bearer "):]
208
+
209
+ def complete(
210
+ self,
211
+ messages: List[Message],
212
+ tools: Optional[List[Tool]] = None,
213
+ tool_choice: str = "auto",
214
+ temperature: Optional[float] = 0.0,
215
+ max_tokens: Optional[int] = None,
216
+ ) -> CompletionResponse:
217
+ """
218
+ Generate a completion using Databricks Foundation Model APIs.
219
+
220
+ Args:
221
+ messages: Conversation messages.
222
+ tools: Optional tools for function calling.
223
+ tool_choice: Tool selection strategy.
224
+ temperature: Sampling temperature; None sends none, and a
225
+ model that refuses it is asked again without it.
226
+ max_tokens: Maximum response tokens.
227
+
228
+ Returns:
229
+ CompletionResponse with the model's response.
230
+
231
+ Raises:
232
+ LLMAuthenticationError: If authentication fails.
233
+ LLMRateLimitError: If rate limit is exceeded.
234
+ LLMAPIError: For other API errors.
235
+ """
236
+ try:
237
+ self._fresh_token()
238
+ # Build request
239
+ request_kwargs: Dict[str, Any] = {
240
+ "model": self._model,
241
+ "messages": [m.to_dict() for m in messages],
242
+ }
243
+
244
+ if max_tokens is not None:
245
+ request_kwargs["max_tokens"] = max_tokens
246
+
247
+ if tools is not None and len(tools) > 0:
248
+ request_kwargs["tools"] = [t.to_dict() for t in tools]
249
+ request_kwargs["tool_choice"] = tool_choice
250
+
251
+ # Make API call
252
+ response = self._send_with_temperature(
253
+ lambda request: self._client.chat.completions.create(**request),
254
+ request_kwargs,
255
+ temperature,
256
+ )
257
+
258
+ # Parse response
259
+ choice = response.choices[0]
260
+ message = choice.message
261
+
262
+ # Parse tool calls if present
263
+ tool_calls = None
264
+ if message.tool_calls:
265
+ tool_calls = [
266
+ ToolCall(
267
+ id=tc.id,
268
+ name=tc.function.name,
269
+ arguments=tc.function.arguments,
270
+ )
271
+ for tc in message.tool_calls
272
+ ]
273
+
274
+ # Build usage dict
275
+ usage = None
276
+ if response.usage:
277
+ usage = {
278
+ "prompt_tokens": response.usage.prompt_tokens,
279
+ "completion_tokens": response.usage.completion_tokens,
280
+ "total_tokens": response.usage.total_tokens,
281
+ }
282
+
283
+ return CompletionResponse(
284
+ content=answer_text(message.content),
285
+ tool_calls=tool_calls,
286
+ usage=usage,
287
+ finish_reason=choice.finish_reason,
288
+ model=response.model,
289
+ )
290
+
291
+ except AuthenticationError as e:
292
+ raise LLMAuthenticationError(f"Databricks authentication failed: {e}")
293
+ except RateLimitError as e:
294
+ raise LLMRateLimitError(f"Databricks rate limit exceeded: {e}")
295
+ except APIError as e:
296
+ raise LLMAPIError(f"Databricks API error: {e}", status_code=getattr(e, "status_code", None))
297
+ except Exception as e:
298
+ raise LLMError(f"Unexpected error calling Databricks: {e}")
299
+
300
+ def supports_function_calling(self) -> bool:
301
+ """Databricks Foundation Model APIs support function calling."""
302
+ return True
303
+
304
+ @property
305
+ def model_name(self) -> str:
306
+ """Get the model name."""
307
+ return self._model
308
+
309
+ @property
310
+ def workspace_url(self) -> str:
311
+ """Get the Databricks workspace URL."""
312
+ return self._workspace_url