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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- 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
|