prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/mcp/server.py ADDED
@@ -0,0 +1,601 @@
1
+ """FastMCP server wiring for ProGraph.
2
+
3
+ This module binds the engine-facing tool implementations in
4
+ ``prograph.mcp.tools`` to a ``FastMCP`` server with tools and resources.
5
+ The server itself is transport-agnostic; the CLI in ``prograph.mcp.__main__``
6
+ decides between stdio / HTTP.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional
12
+
13
+ from prograph.mcp import tools as _tools
14
+ from prograph.schema.context import (
15
+ describe_schema,
16
+ render_compact,
17
+ render_markdown,
18
+ )
19
+ from prograph.schema.examples import generate_examples, render_examples
20
+
21
+ if TYPE_CHECKING:
22
+ from prograph import ProGraph
23
+ from mcp.server.fastmcp import FastMCP
24
+
25
+
26
+ SERVER_INSTRUCTIONS = """
27
+ This server is the **graph-query escape hatch** for analytical agents.
28
+ It exposes a ProGraph virtual graph (your existing tables, viewed as a
29
+ property graph with OWL ontology + SHACL validation) through tools you
30
+ should reach for **when SQL alone doesn't capture the question**.
31
+
32
+ When to reach for this server (vs. plain SQL against the warehouse):
33
+
34
+ - **Variable-length paths** (`(a)-[*1..5]->(b)`). SQL would need a
35
+ recursive CTE; Cypher / SPARQL property paths express it
36
+ natively.
37
+ - **Pattern matching with named hops** ("customers within 3 hops of a
38
+ fraud-flagged account, sorted by transaction volume"). Plain SQL
39
+ needs many self-joins; graph syntax is one line.
40
+ - **OWL-aware traversal**. ProGraph's ontology layer expands queries
41
+ through `rdfs:subClassOf`, `owl:equivalentClass`, transitive and
42
+ symmetric properties, and inverse properties. SQL doesn't.
43
+ - **Property paths in SPARQL** (`?x :friend+/:lives_in ?city`).
44
+
45
+ When NOT to reach for this server:
46
+
47
+ - **Simple aggregations, GROUP BY, joins on flat tables.** Use SQL.
48
+ - **Counts, averages, time-bucketed metrics over known views.** Use SQL.
49
+ - **Anything that's well-expressed in the `prograph_views.*` schema
50
+ ProGraph generates.** Those views are query-time projections of the
51
+ graph's semantic structure, querying them in SQL is faster than
52
+ round-tripping through this MCP server.
53
+
54
+ Workflow for the graph cases this server handles:
55
+
56
+ 1. Call `get_schema` (or read the `prograph://schema` resource) once
57
+ to see node labels, relationship types, properties, and OWL
58
+ classes the engine knows about.
59
+ 2. Optionally call `generate_views` to introspect which semantic
60
+ projections are exposed as `prograph_views.*` SQL views, those
61
+ are usually a better answer than calling `execute_query`.
62
+ 3. For genuinely graph-shaped questions, call `execute_query` with
63
+ Cypher / SPARQL. The language is auto-detected;
64
+ pass `language` explicitly to override.
65
+ 4. On errors, the response includes a compact schema and identifier
66
+ suggestions so you can correct typos without a separate round trip.
67
+ 5. Use `explain_query` if a query is slow or returns unexpected
68
+ results. It returns the physical plan without executing.
69
+ """
70
+
71
+
72
+ def _name_the_version(server: Any) -> None:
73
+ """The server's `serverInfo.version` at initialize is ProGraph's: FastMCP takes no version and its
74
+ server would report the mcp package's own."""
75
+ from prograph import __version__
76
+ server._mcp_server.version = __version__
77
+
78
+
79
+ def build_server(
80
+ engine: "ProGraph",
81
+ *,
82
+ name: str = "prograph",
83
+ json_response: bool = False,
84
+ stateless_http: bool = False,
85
+ ) -> "FastMCP":
86
+ """Wire a FastMCP server around the given ProGraph engine.
87
+
88
+ Args:
89
+ engine: A configured ProGraph instance.
90
+ name: MCP server name (shown to clients in their server list).
91
+ json_response: For the streamable-http transport, return plain JSON
92
+ responses instead of SSE streams. Required by simple JSON-RPC MCP
93
+ clients (e.g. an agent that POSTs ``tools/call`` and reads
94
+ ``response.json()``) that don't parse ``text/event-stream``.
95
+ stateless_http: For streamable-http, treat each request as an
96
+ independent session (no ``Mcp-Session-Id``, no ``initialize``
97
+ round-trip required). Pairs with ``json_response`` to make the
98
+ server consumable by lightweight HTTP MCP clients.
99
+
100
+ Returns:
101
+ A FastMCP instance ready to run via ``run_stdio_async`` /
102
+ ``run_streamable_http_async`` / etc.
103
+ """
104
+ from mcp.server.fastmcp import FastMCP
105
+
106
+ server = FastMCP(
107
+ name=name,
108
+ instructions=SERVER_INSTRUCTIONS.strip(),
109
+ json_response=json_response,
110
+ stateless_http=stateless_http,
111
+ )
112
+ _name_the_version(server)
113
+
114
+ # ── Tools ────────────────────────────────────────────────────────────
115
+
116
+ @server.tool(
117
+ description=(
118
+ "Execute a graph query, Cypher or SPARQL, "
119
+ "and return the result rows. **Reach for this when the question "
120
+ "is genuinely graph-shaped**: variable-length paths, multi-hop "
121
+ "neighborhoods, OWL-aware traversal, or property-path patterns. "
122
+ "Don't use it for plain aggregations or filters on flat tables; "
123
+ "those should hit the warehouse's SQL directly, including "
124
+ "the `prograph_views.*` projections that expose ProGraph's "
125
+ "reasoning as standard SQL tables.\n\n"
126
+ "Language is auto-detected from the query syntax unless "
127
+ "`language` is supplied. Output is capped at "
128
+ f"{_tools.DEFAULT_ROW_LIMIT} rows by default and "
129
+ f"{_tools.MAX_ROW_LIMIT} maximum. On error, the response "
130
+ "includes a compact schema and identifier suggestions so you "
131
+ "can correct typos without a separate `get_schema` call."
132
+ )
133
+ )
134
+ def execute_query(
135
+ query: str,
136
+ language: Optional[
137
+ Literal["sparql", "auto"]
138
+ ] = None,
139
+ limit: Optional[int] = None,
140
+ ) -> Dict[str, Any]:
141
+ return _tools.execute_query(engine, query, language=language, limit=limit)
142
+
143
+ @server.tool(
144
+ description=(
145
+ "Return the physical execution plan for a graph query without "
146
+ "running it. Useful for understanding what backend operations "
147
+ "will execute, how filters and joins are expressed in SQL, and "
148
+ "which paths fall back to in-memory traversal. Prefer this "
149
+ "over `execute_query` when debugging unexpected results or "
150
+ "slow runtimes."
151
+ )
152
+ )
153
+ def explain_query(
154
+ query: str,
155
+ language: Optional[
156
+ Literal["sparql", "auto"]
157
+ ] = None,
158
+ ) -> Dict[str, Any]:
159
+ return _tools.explain_query(engine, query, language=language)
160
+
161
+ @server.tool(
162
+ description=(
163
+ "Describe the graph schema this server exposes, node labels, "
164
+ "relationship types, properties, source tables, and OWL "
165
+ "classes if an ontology is loaded. Call this once at the "
166
+ "start of a session before reaching for `execute_query`; "
167
+ "subsequent calls can be skipped because the schema doesn't "
168
+ "change mid-session.\n\n"
169
+ "`format='compact'` (default) is token-efficient and is the "
170
+ "right choice for LLM consumption. `'markdown'` is human-"
171
+ "readable for inline rendering. `'dict'` returns structured "
172
+ "JSON for programmatic introspection."
173
+ )
174
+ )
175
+ def get_schema(
176
+ format: Literal["compact", "markdown", "dict"] = "compact",
177
+ ) -> Dict[str, Any]:
178
+ return _tools.get_schema(engine, format=format)
179
+
180
+ @server.tool(
181
+ description=(
182
+ "Return the list of node labels in the schema. Lightweight "
183
+ "alternative to `get_schema` when you only need the label "
184
+ "set (e.g. for autocomplete or schema-aware reasoning)."
185
+ )
186
+ )
187
+ def list_node_labels() -> List[str]:
188
+ return _tools.list_node_labels(engine)
189
+
190
+ @server.tool(
191
+ description=(
192
+ "Return the list of relationship types with their start "
193
+ "and end node labels, the directed edges in the graph "
194
+ "schema. Use to discover traversal options before writing "
195
+ "a Cypher / SPARQL query."
196
+ )
197
+ )
198
+ def list_relationship_types() -> List[Dict[str, str]]:
199
+ return _tools.list_relationship_types(engine)
200
+
201
+ @server.tool(
202
+ description=(
203
+ "Describe the **ontology** bound to this engine, the *semantic* "
204
+ "model behind the tabular schema: the class hierarchy "
205
+ "(subClassOf / subclasses / equivalent classes) and each "
206
+ "property's domain, range, and OWL characteristics "
207
+ "(symmetric / transitive / functional / inverseOf / "
208
+ "subPropertyOf / property chains).\n\n"
209
+ "**Reach for this to reason semantically rather than by column "
210
+ "names.** It tells you that a query over a superclass already "
211
+ "covers its subclasses (so roll up by querying the superclass, "
212
+ "don't enumerate subclasses by hand), which properties connect "
213
+ "which classes, and which properties entail extra edges. The "
214
+ "`profile` field (ql, rl, or null with no ontology) and `note` say whether matches are expanded "
215
+ "and reasoning is materialized. Returns `available: false` when "
216
+ "no ontology is bound, fall back to `get_schema`."
217
+ )
218
+ )
219
+ def get_ontology() -> Dict[str, Any]:
220
+ return _tools.get_ontology(engine)
221
+
222
+ @server.tool(
223
+ description=(
224
+ "Validate this engine's current data against SHACL `shapes` and "
225
+ "return a conformance report. **The runtime guardrail**: before "
226
+ "you commit or trust a fact, check it against the shapes. "
227
+ "`shapes` is a SHACL graph as a Turtle string (or a path to a "
228
+ "`.ttl` file). The report's `conforms` flag plus per-violation "
229
+ "`focus_node` / `path` / `severity` / `message` let you *repair* "
230
+ "a bad value rather than just fail. The graph validated is the one "
231
+ "SPARQL answers, so write `sh:targetClass` with the IRIs a SPARQL "
232
+ "query returns; shapes aimed at other IRIs conform vacuously."
233
+ )
234
+ )
235
+ def validate_against_shapes(shapes: str) -> Dict[str, Any]:
236
+ return _tools.validate_against_shapes(engine, shapes)
237
+
238
+ # Zero-argument runtime guardrail, only exposed when the operator
239
+ # configured default shapes on the engine. Because it takes no required
240
+ # arguments, an MCP client's context pass invokes it automatically, so the
241
+ # SHACL conformance verdict reaches the agent's reasoning before it trusts
242
+ # any number derived from the data.
243
+ if engine.default_shapes:
244
+ @server.tool(
245
+ description=(
246
+ "Check the engine's current data against the operator's "
247
+ "configured SHACL shapes and return a conformance verdict "
248
+ "(`conforms`, `violation_count`, per-violation `focus_node` / "
249
+ "`path` / `severity` / `message`, and a `guardrail` PASS/FAIL "
250
+ "summary). **The deterministic honesty boundary**: if this "
251
+ "FAILs, the data violates the operator's rules, surface the "
252
+ "problem and do not present numbers derived from the offending "
253
+ "rows as trustworthy. Takes no arguments; validates the shapes "
254
+ "the operator declared for this engine."
255
+ )
256
+ )
257
+ def check_data_quality() -> Dict[str, Any]:
258
+ return _tools.check_data_quality(engine)
259
+
260
+ @server.tool(
261
+ description=(
262
+ "Return ProGraph-generated SQL view descriptors, name, "
263
+ "fully-qualified namespace placement, source kind "
264
+ "(schema_label / subclass_closure / owl_defined_class / "
265
+ "shacl_violation / metric), the source label or shape, "
266
+ "the description, and the projected columns. **These views "
267
+ "are the preferred answer when a question maps to a class, "
268
+ "subclass closure, or OWL-entailed defined class**, they "
269
+ "expose the graph's semantic projections as standard SQL "
270
+ "tables that BI tools, dashboards, and natural-language-to-"
271
+ "SQL systems can query directly without going through this "
272
+ "server.\n\n"
273
+ "This tool is read-only. It tells you which views *would* "
274
+ "be generated against this engine's schema. To actually "
275
+ "create them in the warehouse, the operator runs `prograph "
276
+ "generate-views` (CLI) or `engine.write_views()` (Python). "
277
+ "Pass `target_catalog` to qualify the namespace (required "
278
+ "for Unity Catalog three-part names)."
279
+ )
280
+ )
281
+ def generate_views(
282
+ target_catalog: Optional[str] = None,
283
+ target_schema: str = "prograph_views",
284
+ include_labels: Optional[List[str]] = None,
285
+ exclude_labels: Optional[List[str]] = None,
286
+ ) -> List[Dict[str, Any]]:
287
+ return _tools.generate_views(
288
+ engine,
289
+ target_catalog=target_catalog,
290
+ target_schema=target_schema,
291
+ include_labels=include_labels,
292
+ exclude_labels=exclude_labels,
293
+ )
294
+
295
+ @server.tool(
296
+ description=(
297
+ "Generate example question/query pairs grounded in the "
298
+ "graph schema. Useful for first-time exploration: each "
299
+ "sample shows a realistic NL question paired with the "
300
+ "SPARQL that answers it. Genie can use these "
301
+ "as few-shot examples for its own reasoning."
302
+ )
303
+ )
304
+ def suggest_queries(
305
+ n: int = 5,
306
+ language: Literal["sparql"] = "sparql",
307
+ ) -> List[Dict[str, Any]]:
308
+ return _tools.suggest_queries(engine, n=n, language=language)
309
+
310
+ # ── Resources ────────────────────────────────────────────────────────
311
+
312
+ @server.resource(
313
+ "prograph://schema",
314
+ description="Graph schema rendered as markdown.",
315
+ mime_type="text/markdown",
316
+ )
317
+ def schema_markdown_resource() -> str:
318
+ schema = engine.schema
319
+ if schema is None:
320
+ return "No schema available."
321
+ return render_markdown(describe_schema(schema))
322
+
323
+ @server.resource(
324
+ "prograph://schema/compact",
325
+ description="Graph schema in compact one-line-per-type form.",
326
+ mime_type="text/plain",
327
+ )
328
+ def schema_compact_resource() -> str:
329
+ schema = engine.schema
330
+ if schema is None:
331
+ return ""
332
+ return render_compact(describe_schema(schema))
333
+
334
+ @server.resource(
335
+ "prograph://examples",
336
+ description="Schema-grounded example queries.",
337
+ mime_type="text/markdown",
338
+ )
339
+ def examples_resource() -> str:
340
+ schema = engine.schema
341
+ if schema is None:
342
+ return ""
343
+ return render_examples(generate_examples(describe_schema(schema), n=5))
344
+
345
+ return server
346
+
347
+
348
+ SPARQL_INSTRUCTIONS = """
349
+ This server answers questions over tables mapped to RDF, in SPARQL 1.1.
350
+ ProGraph translates each query to the database's SQL and runs it there;
351
+ every answer carries the SPARQL and the SQL that ran.
352
+
353
+ 1. For a question in plain language, call `ask` with the question:
354
+ ProGraph writes the SPARQL, checks it and runs it. No `get_schema`
355
+ call is needed first. `language: "cypher"` has it write Cypher. If `ask` answers `no_model` or
356
+ `model_unavailable`, write the query yourself.
357
+ 2. For a SPARQL query you already have, or to follow up on the SPARQL
358
+ `ask` returned, call `run_sparql`.
359
+ 3. Before writing SPARQL yourself, call `get_schema`. It gives the PREFIX
360
+ lines, the classes (a class covers the classes within it), each
361
+ predicate with its datatype or the classes it links, example queries
362
+ that run on this data, and `query_rules`, the rules to write it by.
363
+ 4. An error is data: `error`, `reason` and `suggestions` (the declared IRIs
364
+ nearest one the schema does not declare). Fix the query and call again.
365
+ A `warnings` entry means an IRI matched nothing: no rows for it is not
366
+ the data's answer.
367
+ 5. `explain_sparql` shows the SQL a query would run, without running it.
368
+ """
369
+
370
+
371
+ def build_sparql_server(
372
+ engines: Any,
373
+ *,
374
+ llm: Any = None,
375
+ name: str = "prograph",
376
+ extra_tools: bool = False,
377
+ explain_answers: bool = True,
378
+ json_response: bool = False,
379
+ stateless_http: bool = False,
380
+ streamable_http_path: str = "/mcp",
381
+ host: str = "127.0.0.1",
382
+ allowed_hosts: Optional[List[str]] = None,
383
+ row_cap: Optional[int] = None,
384
+ timeout: Optional[float] = None,
385
+ queries: Any = None,
386
+ ) -> "FastMCP":
387
+ """The MCP server of a SPARQL deployment: `get_schema`,
388
+ `run_sparql`, `ask`, `explain_sparql` (`prograph.mcp.sparql`) and
389
+ `cancel_query`; the ontology, SHACL and views tools with `extra_tools`.
390
+
391
+ `queries` holds the running `run_sparql` calls by id
392
+ (`prograph.execution.RunningQueries`; one of its own by default):
393
+ `prograph serve` shares one with /sparql, so `cancel_query` cancels a
394
+ query by its id from either.
395
+
396
+ `engines` is a ProGraph, or the endpoint's engine source
397
+ (`prograph.endpoint.engines`: a function of the HTTP request), so a call
398
+ over HTTP runs on the engine of the person who made it, as /sparql's
399
+ requests do. `llm` is the client `ask`
400
+ writes queries with (`prograph.nlp`); a function of no arguments that
401
+ returns one is called at the first `ask`. Without one, `ask` answers
402
+ with an error naming the setting.
403
+
404
+ `host` is the address the server binds: on a local one FastMCP accepts
405
+ only requests whose Host is local (its DNS rebinding protection), which
406
+ `allowed_hosts` extends; bound to all addresses (a Databricks App
407
+ behind its proxy) it checks no Host, and the server's authentication
408
+ stands.
409
+
410
+ `row_cap` and `timeout` are the endpoint's: past
411
+ either a call's answer is an error, as at /sparql, whatever its `limit`.
412
+ Each tool runs in a worker thread (`anyio.to_thread.run_sync`, as
413
+ /sparql's `run_in_threadpool`), so one call never holds the event loop
414
+ that answers every other request.
415
+ """
416
+ import anyio
417
+ from mcp.server.fastmcp import FastMCP
418
+ from prograph.mcp import sparql as S
419
+
420
+ security = None
421
+ if allowed_hosts:
422
+ from mcp.server.transport_security import TransportSecuritySettings
423
+ security = TransportSecuritySettings(
424
+ enable_dns_rebinding_protection=True,
425
+ allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*", *allowed_hosts])
426
+ server = FastMCP(
427
+ name=name,
428
+ instructions=SPARQL_INSTRUCTIONS.strip(),
429
+ json_response=json_response,
430
+ stateless_http=stateless_http,
431
+ streamable_http_path=streamable_http_path,
432
+ host=host,
433
+ transport_security=security,
434
+ )
435
+ _name_the_version(server)
436
+ source = engines if callable(engines) and not hasattr(engines, "execute") else (lambda request: engines)
437
+ held: Dict[str, Any] = {}
438
+ from prograph.execution import RunningQueries
439
+ running = queries if queries is not None else RunningQueries()
440
+
441
+ def request_now() -> Any:
442
+ # On the event loop: the request the call came with (None over stdio).
443
+ try:
444
+ return server.get_context().request_context.request
445
+ except (LookupError, ValueError):
446
+ return None
447
+
448
+ async def in_thread(work: Any) -> Any:
449
+ """`work(request)` in a worker thread, the request taken here."""
450
+ request = request_now()
451
+ return await anyio.to_thread.run_sync(lambda: work(request))
452
+
453
+ def with_engine(request: Any, call):
454
+ try:
455
+ current = source(request)
456
+ except Exception as error: # noqa: BLE001 - no engine for this caller
457
+ return {"error": str(getattr(error, "reason", None) or error),
458
+ "reason": "unauthorized" if getattr(error, "status", None) == 401 else type(error).__name__}
459
+ try:
460
+ return call(current)
461
+ finally:
462
+ # The engine source learns the call has ended, so a running
463
+ # call's engine is not closed as idle.
464
+ let_go = getattr(engines, "release", None)
465
+ if callable(let_go):
466
+ let_go(current)
467
+
468
+ def model() -> Any:
469
+ if "llm" not in held:
470
+ held["llm"] = llm() if callable(llm) and not hasattr(llm, "complete") else llm
471
+ return held["llm"]
472
+
473
+ @server.tool(description=(
474
+ "Call this before writing SPARQL yourself (not needed before `ask`). Returns the "
475
+ "vocabulary to write SPARQL in: the PREFIX lines to start every query with, the classes "
476
+ "and their hierarchy (a query over a class covers the classes within it), each predicate "
477
+ "with its datatype or the classes it links, example queries generated from the mapping, "
478
+ "and `query_rules`, the rules to write a query by. Use exactly these IRIs: any other "
479
+ "matches nothing."))
480
+ async def get_schema() -> Dict[str, Any]:
481
+ return await in_thread(lambda r: with_engine(r, S.get_schema))
482
+
483
+ @server.tool(description=(
484
+ "Run a SPARQL 1.1 query (SELECT, ASK or CONSTRUCT) and return its rows with the SPARQL "
485
+ "and the SQL that ran. ProGraph translates SPARQL into SQL where it can and runs it on "
486
+ "the database: `ran_in: 'sql'` is the normal path, 'python' a fallback on ProGraph's own "
487
+ "executor (see `reason`); neither is an error. Start the query with the PREFIX "
488
+ "lines `get_schema` gives. Rows are capped at `limit` (default "
489
+ f"{_tools.DEFAULT_ROW_LIMIT}, at most {_tools.MAX_ROW_LIMIT}); `total_row_count` is the "
490
+ "real total and `truncated` says whether rows were left out. On an error, read `reason` "
491
+ "and `suggestions`, fix the query and call again. Use it for a SPARQL query you already "
492
+ "have or to follow up on the SPARQL `ask` returned; for a question in plain language, "
493
+ "call `ask`. The answer's `query_id` cancels the run with `cancel_query`; to cancel it "
494
+ "before the answer comes, pass a random UUID (version 4) of your own as `query_id`."))
495
+ async def run_sparql(query: str, limit: Optional[int] = None,
496
+ query_id: Optional[str] = None) -> Dict[str, Any]:
497
+ try:
498
+ context = running.open(query_id)
499
+ except ValueError as error:
500
+ return {"sparql": query, "sql": None, "error": f"query_id: {error}", "reason": "bad_query_id",
501
+ "suggestions": ["pass a new random UUID (version 4), or none"]}
502
+ try:
503
+ answer = await in_thread(lambda r: with_engine(r, lambda e: S.run_sparql(
504
+ e, query, limit, row_cap=row_cap, timeout=timeout, context=context)))
505
+ finally:
506
+ running.close(context)
507
+ answer["query_id"] = context.query_id
508
+ return answer
509
+
510
+ @server.tool(description=(
511
+ "Call this for any question in plain language (no `get_schema` call needed first): "
512
+ "ProGraph writes the SPARQL over this schema, checks it, runs it, and returns the "
513
+ "question, the SPARQL, the SQL that ran, the rows and a "
514
+ "short explanation. The SQL is ProGraph's translation of that SPARQL, run on the "
515
+ "database; `ran_in` reads as in `run_sparql`. Check the returned SPARQL says what you "
516
+ "meant; to refine it, edit it and call `run_sparql`. The same row limit as `run_sparql`. "
517
+ "`language: 'cypher'` has ProGraph write a read-only Cypher query over the property-graph "
518
+ "view instead, returned as `cypher`; a query that writes is refused (`reason` 'read_only')."))
519
+ async def ask(question: str, limit: Optional[int] = None,
520
+ language: Literal["sparql", "cypher"] = "sparql") -> Dict[str, Any]:
521
+ def work(request: Any) -> Dict[str, Any]:
522
+ try:
523
+ client = model()
524
+ except Exception as error: # noqa: BLE001 - a model that cannot be built
525
+ return {"question": question, "error": f"the model for ask cannot be reached: {error}",
526
+ "reason": "model_unavailable"}
527
+ if client is None:
528
+ return {"question": question, "error": "no model is configured for ask: start the "
529
+ "server with a model (--model), or write the query and call run_sparql",
530
+ "reason": "no_model"}
531
+ return with_engine(request, lambda e: S.ask(e, question, client, limit, explain=explain_answers,
532
+ row_cap=row_cap, timeout=timeout, language=language))
533
+ return await in_thread(work)
534
+
535
+ @server.tool(description=(
536
+ "Show the SQL that ProGraph translates a SPARQL query into, without running it: `sql`, "
537
+ "and `ran_in` ('sql': it would run on the database, the normal path; or 'python' with the "
538
+ "`reason` it has no SQL translation). Use it to check a "
539
+ "query before running a large one."))
540
+ async def explain_sparql(query: str) -> Dict[str, Any]:
541
+ return await in_thread(lambda r: with_engine(r, lambda e: S.explain_sparql(e, query)))
542
+
543
+ @server.tool(description=(
544
+ "Cancel a running `run_sparql` call (or a /sparql query of this server) by its `query_id`: "
545
+ "the database statement it runs is stopped, and its answer is the error `reason` "
546
+ "'cancelled'. `cancelled` is false when no query with that id is running (it ended, or "
547
+ "the id is unknown); nothing changes then."))
548
+ async def cancel_query(query_id: str) -> Dict[str, Any]:
549
+ found = await anyio.to_thread.run_sync(lambda: running.cancel(query_id))
550
+ if found:
551
+ return {"query_id": query_id, "cancelled": True}
552
+ return {"query_id": query_id, "cancelled": False, "reason": "not_running",
553
+ "error": "no running query has this id"}
554
+
555
+ @server.prompt(name="write-sparql", description=(
556
+ "The guidance `ask` gives its model for writing SPARQL over this mapping: the rules, the "
557
+ "vocabulary (PREFIX lines, classes, predicates) and examples generated from the mapping. "
558
+ "For a client that writes its own queries for `run_sparql`."))
559
+ async def write_sparql() -> str:
560
+ from prograph.nlp.prompts.system import sparql_prompt
561
+
562
+ def work(request: Any) -> str:
563
+ got = with_engine(request, lambda e: sparql_prompt(e.schema))
564
+ return got if isinstance(got, str) else f"No schema for this caller: {got.get('error')}"
565
+ return await in_thread(work)
566
+
567
+ if extra_tools:
568
+ @server.tool(description=(
569
+ "Describe the ontology bound to the engine: its class hierarchy and each property's "
570
+ "domain, range and OWL characteristics. `available: false` when none is bound."))
571
+ async def get_ontology() -> Dict[str, Any]:
572
+ return await in_thread(lambda r: with_engine(r, _tools.get_ontology))
573
+
574
+ @server.tool(description=(
575
+ "Validate the data against SHACL shapes, given as Turtle text, and return the "
576
+ "conformance report."))
577
+ async def validate_against_shapes(shapes: str) -> Dict[str, Any]:
578
+ def work(request: Any) -> Dict[str, Any]:
579
+ # Turtle text only: read as a path, a caller could have the
580
+ # server's files back in a parse error.
581
+ import rdflib
582
+ try:
583
+ graph = rdflib.Graph().parse(data=shapes, format="turtle")
584
+ except Exception as error: # noqa: BLE001 - the error is the answer
585
+ return {"error": f"the shapes are not Turtle: {type(error).__name__}",
586
+ "reason": "invalid_shapes"}
587
+ return with_engine(request, lambda e: _tools.validate_against_shapes(e, graph))
588
+ return await in_thread(work)
589
+
590
+ @server.tool(description=(
591
+ "Describe the SQL views ProGraph would generate for this schema (classes, subclass "
592
+ "closures, OWL-defined classes), read only."))
593
+ async def generate_views(target_catalog: Optional[str] = None,
594
+ target_schema: str = "prograph_views") -> List[Dict[str, Any]]:
595
+ return await in_thread(lambda r: with_engine(r, lambda e: _tools.generate_views(
596
+ e, target_catalog=target_catalog, target_schema=target_schema)))
597
+
598
+ return server
599
+
600
+
601
+ __all__ = ["build_server", "build_sparql_server", "SERVER_INSTRUCTIONS", "SPARQL_INSTRUCTIONS"]