prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,414 @@
1
+ """Dataclass types for the Genie integration.
2
+
3
+ Defines the contract between the view generator, the instruction
4
+ generator, the sample-query generator, the Space emitter, and the
5
+ CLI. Every later module produces or consumes these types.
6
+
7
+ Design principles:
8
+
9
+ - **Frozen**, once produced, an artifact doesn't change. Generators
10
+ rebuild from scratch; callers don't mutate. Mutation would imply
11
+ the artifact has a lifecycle separate from the schema it came from.
12
+ - **JSON-serializable**, every type roundtrips through dict/JSON via
13
+ ``to_dict``/``from_dict``. The Space emitter writes YAML; YAML is
14
+ JSON-compatible structured data.
15
+ - **No engine references**. These types describe outputs, not
16
+ inputs. They don't carry pointers to ``ProGraph`` instances,
17
+ connections, or schemas. That keeps them serializable and
18
+ diff-friendly.
19
+
20
+ See ``docs/guides/genie.md`` for the user-facing workflow.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import asdict, dataclass, field
26
+ from enum import Enum
27
+ from typing import Any, Dict, List, Optional
28
+
29
+
30
+ # ─── View definitions ────────────────────────────────────────────────
31
+
32
+
33
+ class ViewSource(str, Enum):
34
+ """Where a generated view came from.
35
+
36
+ Decision 3 in the Genie integration spike enumerates the four
37
+ sources of views (subclass closure, OWL defined class, SHACL
38
+ violation, metric). The fifth value ``SCHEMA_LABEL`` covers the
39
+ trivial "one view per node label" case the view generator emits
40
+ by default.
41
+
42
+ The enum is a ``str`` subclass so ``ViewSource.OWL_DEFINED_CLASS ==
43
+ "owl_defined_class"`` is True, convenient for JSON serialization
44
+ and equality checks.
45
+ """
46
+
47
+ SCHEMA_LABEL = "schema_label"
48
+ """A view projecting one NodeMapping's rows. Trivial case."""
49
+
50
+ SUBCLASS_CLOSURE = "subclass_closure"
51
+ """A view unioning all subclasses of a parent label."""
52
+
53
+ OWL_DEFINED_CLASS = "owl_defined_class"
54
+ """A view projecting an OWL-entailed class (RL+ restriction)."""
55
+
56
+ SHACL_VIOLATION = "shacl_violation"
57
+ """A view exposing the latest SHACL run's violations."""
58
+
59
+ METRIC = "metric"
60
+ """An aggregation view (Phase 5 measure/dimension; placeholder)."""
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class ViewDefinition:
65
+ """A single generated SQL view.
66
+
67
+ Carries the SQL needed to ``CREATE OR REPLACE VIEW`` it plus the
68
+ provenance to know where the definition came from.
69
+
70
+ The ``sql`` field is the bare SELECT body, callers
71
+ (e.g. ``view_writer.py``) wrap it in ``CREATE OR REPLACE VIEW
72
+ {namespace}.{name} AS {sql}`` for the target dialect.
73
+ """
74
+
75
+ name: str
76
+ """The view's local name (no schema/catalog prefix).
77
+
78
+ Conventionally ``snake_case``; the namespace prefix is added at
79
+ write time so the same ``ViewDefinition`` works against Databricks
80
+ SQL (``catalog.schema.name``), Postgres (``schema.name``), or
81
+ DuckDB (``name``).
82
+ """
83
+
84
+ sql: str
85
+ """The SELECT body that defines the view.
86
+
87
+ Does **not** include the ``CREATE OR REPLACE VIEW {fqn} AS``
88
+ wrapper, that's the writer's job. Leaving it off lets the same
89
+ definition emit to different dialects with different quoting
90
+ rules.
91
+ """
92
+
93
+ source: ViewSource
94
+ """Which kind of source produced this view.
95
+
96
+ Used by the Space emitter to group views in instructions ("OWL-
97
+ inferred classes:" vs "Data-quality views:") and by the writer
98
+ to decide ordering (closure views before defined-class views,
99
+ etc.).
100
+ """
101
+
102
+ description: str = ""
103
+ """Human-readable summary. Goes into the SQL ``COMMENT`` and into
104
+ Genie Space instructions. One sentence; no trailing period
105
+ required.
106
+ """
107
+
108
+ source_label: Optional[str] = None
109
+ """For label-derived views (``SCHEMA_LABEL``, ``SUBCLASS_CLOSURE``,
110
+ ``OWL_DEFINED_CLASS``), the originating label. ``None`` for
111
+ others.
112
+ """
113
+
114
+ source_shape_iri: Optional[str] = None
115
+ """For ``SHACL_VIOLATION`` views, the SHACL shape IRI. ``None``
116
+ otherwise."""
117
+
118
+ source_metric_name: Optional[str] = None
119
+ """For ``METRIC`` views, the metric definition name. ``None``
120
+ otherwise."""
121
+
122
+ columns: List[str] = field(default_factory=list)
123
+ """The view's projected columns, in order. Lets callers introspect
124
+ without parsing the SQL. Optional: if empty, the writer can
125
+ leave column comments off."""
126
+
127
+ def to_dict(self) -> Dict[str, Any]:
128
+ d = asdict(self)
129
+ # Normalize the enum to its string value for JSON.
130
+ d["source"] = self.source.value
131
+ return d
132
+
133
+ @classmethod
134
+ def from_dict(cls, data: Dict[str, Any]) -> "ViewDefinition":
135
+ kwargs = dict(data)
136
+ kwargs["source"] = ViewSource(kwargs["source"])
137
+ return cls(**kwargs)
138
+
139
+
140
+ # ─── Sample queries ──────────────────────────────────────────────────
141
+
142
+
143
+ @dataclass(frozen=True)
144
+ class SampleQuery:
145
+ """A natural-language question paired with its expected SQL.
146
+
147
+ Genie uses these as few-shot examples when reasoning about how to
148
+ answer user questions. The generator (W4) produces 10-30 of these
149
+ per schema, covering common patterns over each generated view.
150
+ """
151
+
152
+ question: str
153
+ """The natural-language question Genie should learn to answer.
154
+
155
+ Written in the voice of a real user: "Which components are at
156
+ high wear risk?" not "Project the OWL-entailed
157
+ :HighWearComponent class."
158
+ """
159
+
160
+ sql: str
161
+ """The expected SQL answer.
162
+
163
+ Should reference generated views (``prograph_views.*``) where
164
+ appropriate, so Genie learns to use them rather than rolling its
165
+ own filters over the base tables.
166
+ """
167
+
168
+ description: str = ""
169
+ """Optional context for the Genie operator who reviews these
170
+ samples. Not consumed by Genie itself."""
171
+
172
+ tags: List[str] = field(default_factory=list)
173
+ """Optional taxonomy for filtering/grouping (e.g. ``["high-wear",
174
+ "maintenance"]``). The Space emitter can use these to organize
175
+ the sample-query list."""
176
+
177
+ def to_dict(self) -> Dict[str, Any]:
178
+ return asdict(self)
179
+
180
+ @classmethod
181
+ def from_dict(cls, data: Dict[str, Any]) -> "SampleQuery":
182
+ return cls(**data)
183
+
184
+
185
+ # ─── Instructions ────────────────────────────────────────────────────
186
+
187
+
188
+ @dataclass(frozen=True)
189
+ class InstructionsSection:
190
+ """One section of the auto-generated instructions doc.
191
+
192
+ Genie's instructions field accepts a single text blob; we model it
193
+ as sections internally so different generators can contribute
194
+ pieces independently and the assembler can order them sensibly.
195
+ """
196
+
197
+ heading: str
198
+ """Section heading, e.g. ``"Entities"``, ``"Relationships"``,
199
+ ``"Defined Classes"``, ``"Data Quality"``."""
200
+
201
+ body: str
202
+ """Markdown-formatted body. Will be rendered verbatim into the
203
+ Genie Space's instructions field. Length: a paragraph to a few
204
+ paragraphs; the assembler caps the full doc at ~4000 tokens."""
205
+
206
+ order: int = 0
207
+ """Sort key for ordering sections in the final doc. Lower goes
208
+ first. Conventional values:
209
+
210
+ - 10: introduction / overview
211
+ - 20: entities (node labels)
212
+ - 30: relationships
213
+ - 40: subclass / type hierarchies
214
+ - 50: OWL-defined classes
215
+ - 60: SHACL constraints / data quality
216
+ - 70: metrics (Phase 5)
217
+ - 80: example query patterns
218
+ - 90: glossary / terms
219
+ """
220
+
221
+ def to_dict(self) -> Dict[str, Any]:
222
+ return asdict(self)
223
+
224
+ @classmethod
225
+ def from_dict(cls, data: Dict[str, Any]) -> "InstructionsSection":
226
+ return cls(**data)
227
+
228
+
229
+ @dataclass(frozen=True)
230
+ class InstructionsDoc:
231
+ """The full set of instructions for one Genie Space.
232
+
233
+ Composed of sections (independent generators contribute their own)
234
+ plus a final assembled body. The Space emitter consumes
235
+ ``rendered`` for the actual Genie Space configuration; the
236
+ sections are kept around for round-tripping and user editing.
237
+ """
238
+
239
+ sections: List[InstructionsSection] = field(default_factory=list)
240
+ """The component sections, in arbitrary order. The assembler
241
+ sorts by ``section.order`` before rendering."""
242
+
243
+ rendered: str = ""
244
+ """The fully-assembled markdown body, sections ordered and
245
+ concatenated with ``\\n\\n`` separators. Truncated at the
246
+ configured token budget (default ~4000 Genie tokens, set by the
247
+ assembler). This is what goes into the Genie Space."""
248
+
249
+ def to_dict(self) -> Dict[str, Any]:
250
+ return {
251
+ "sections": [s.to_dict() for s in self.sections],
252
+ "rendered": self.rendered,
253
+ }
254
+
255
+ @classmethod
256
+ def from_dict(cls, data: Dict[str, Any]) -> "InstructionsDoc":
257
+ return cls(
258
+ sections=[InstructionsSection.from_dict(s) for s in data["sections"]],
259
+ rendered=data.get("rendered", ""),
260
+ )
261
+
262
+
263
+ # ─── MCP server registration ─────────────────────────────────────────
264
+
265
+
266
+ @dataclass(frozen=True)
267
+ class McpServerRegistration:
268
+ """Registration of an MCP server in a Genie Space.
269
+
270
+ Path B from the spike: the existing ProGraph MCP server registered
271
+ so Genie can call it as an escape hatch for graph-shaped queries.
272
+
273
+ Authentication is described, not stored: this dataclass carries
274
+ the *method* (``"databricks_pat"``, ``"oauth"``, etc.); the actual
275
+ secret is supplied separately at Space-import time.
276
+ """
277
+
278
+ name: str
279
+ """Identifier Genie uses to reference the server.
280
+ Conventionally ``"prograph"`` for the primary registration; if
281
+ multiple ProGraph engines are registered, use
282
+ ``"prograph_<domain>"`` (e.g. ``"prograph_turbofan"``)."""
283
+
284
+ endpoint: str
285
+ """The MCP server's URL or local invocation. URL for hosted
286
+ deployments; for local-stdio deployments, the equivalent
287
+ command string."""
288
+
289
+ description: str = ""
290
+ """Human-readable purpose. Genie's tool-selection reasoning reads
291
+ this; phrase it for the model that has to decide whether to call
292
+ this server vs. answer with SQL."""
293
+
294
+ auth_method: str = "databricks_pat"
295
+ """How Genie authenticates. ``"databricks_pat"`` (default),
296
+ ``"oauth"``, ``"service_principal"``, or ``"none"`` for local
297
+ deployments without auth.
298
+
299
+ The actual secret is supplied at import time; this field only
300
+ documents the expected method.
301
+ """
302
+
303
+ def to_dict(self) -> Dict[str, Any]:
304
+ return asdict(self)
305
+
306
+ @classmethod
307
+ def from_dict(cls, data: Dict[str, Any]) -> "McpServerRegistration":
308
+ return cls(**data)
309
+
310
+
311
+ # ─── Genie Space ─────────────────────────────────────────────────────
312
+
313
+
314
+ @dataclass(frozen=True)
315
+ class GenieSpace:
316
+ """A complete Genie Space configuration.
317
+
318
+ The output of ``prograph emit-genie-space``. Serializes to the
319
+ YAML/JSON shape Databricks Genie consumes natively. Decision 7 in
320
+ the spike commits to emitting Genie's documented format rather
321
+ than inventing our own.
322
+
323
+ Fields beyond the Genie-required minimum (``tables``, ``instructions``,
324
+ ``sample_queries``) are namespaced under ``metadata`` to avoid
325
+ collisions with future Databricks-side schema additions.
326
+ """
327
+
328
+ name: str
329
+ """Display name of the Space."""
330
+
331
+ description: str = ""
332
+ """Short description shown in the Genie UI."""
333
+
334
+ tables: List[str] = field(default_factory=list)
335
+ """Fully-qualified table names included in the Space.
336
+
337
+ Mix of user tables (``catalog.schema.engines``) and ProGraph-
338
+ generated views (``catalog.prograph_views.high_wear_components``).
339
+ Order doesn't matter to Genie but the emitter conventionally
340
+ lists user tables first, generated views second.
341
+ """
342
+
343
+ instructions: InstructionsDoc = field(default_factory=InstructionsDoc)
344
+ """Natural-language instructions. The ``rendered`` field's
345
+ contents go into the Genie Space's instructions slot."""
346
+
347
+ sample_queries: List[SampleQuery] = field(default_factory=list)
348
+ """Few-shot NL→SQL pairs. Genie consumes these as exemplars."""
349
+
350
+ mcp_servers: List[McpServerRegistration] = field(default_factory=list)
351
+ """MCP server registrations for the escape-hatch path. Usually
352
+ one (the ProGraph MCP server)."""
353
+
354
+ views: List[ViewDefinition] = field(default_factory=list)
355
+ """The ProGraph-generated views referenced by this Space.
356
+
357
+ Stored on the Space object so consumers can also issue the
358
+ ``CREATE OR REPLACE VIEW`` statements through ``view_writer.py``
359
+ as part of importing the Space. The views are also the
360
+ provenance of the ``catalog.prograph_views.*`` entries in
361
+ ``tables``.
362
+ """
363
+
364
+ metadata: Dict[str, Any] = field(default_factory=dict)
365
+ """Free-form metadata. Conventional keys:
366
+
367
+ - ``"generated_by"``: ``"prograph"``
368
+ - ``"generated_at"``: ISO-8601 timestamp
369
+ - ``"prograph_version"``: the version that produced this Space
370
+ - ``"source_config"``: path to the ``graph.yaml`` it was emitted from
371
+ """
372
+
373
+ def to_dict(self) -> Dict[str, Any]:
374
+ return {
375
+ "name": self.name,
376
+ "description": self.description,
377
+ "tables": list(self.tables),
378
+ "instructions": self.instructions.to_dict(),
379
+ "sample_queries": [q.to_dict() for q in self.sample_queries],
380
+ "mcp_servers": [s.to_dict() for s in self.mcp_servers],
381
+ "views": [v.to_dict() for v in self.views],
382
+ "metadata": dict(self.metadata),
383
+ }
384
+
385
+ @classmethod
386
+ def from_dict(cls, data: Dict[str, Any]) -> "GenieSpace":
387
+ return cls(
388
+ name=data["name"],
389
+ description=data.get("description", ""),
390
+ tables=list(data.get("tables", [])),
391
+ instructions=InstructionsDoc.from_dict(
392
+ data.get("instructions", {"sections": [], "rendered": ""})
393
+ ),
394
+ sample_queries=[
395
+ SampleQuery.from_dict(q) for q in data.get("sample_queries", [])
396
+ ],
397
+ mcp_servers=[
398
+ McpServerRegistration.from_dict(s)
399
+ for s in data.get("mcp_servers", [])
400
+ ],
401
+ views=[ViewDefinition.from_dict(v) for v in data.get("views", [])],
402
+ metadata=dict(data.get("metadata", {})),
403
+ )
404
+
405
+
406
+ __all__ = [
407
+ "ViewSource",
408
+ "ViewDefinition",
409
+ "SampleQuery",
410
+ "InstructionsSection",
411
+ "InstructionsDoc",
412
+ "McpServerRegistration",
413
+ "GenieSpace",
414
+ ]