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