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
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)
|