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,746 @@
1
+ """Schema Inferrer, analyze OWL ontology + instance TTL and generate
2
+ ProGraph YAML schema config, SQL DDL, and a human-readable summary.
3
+ """
4
+
5
+ from collections import defaultdict
6
+ from dataclasses import dataclass, field
7
+ from pathlib import Path
8
+ from typing import Any, Dict, List, Optional, Set, Tuple
9
+
10
+ try:
11
+ from rdflib import Graph, RDF, RDFS, OWL, XSD, Namespace, URIRef, Literal, BNode
12
+ RDFLIB_AVAILABLE = True
13
+ except ImportError:
14
+ RDFLIB_AVAILABLE = False
15
+
16
+ import yaml
17
+
18
+ from prograph.schema.naming import column_from_local_name, rel_type_from_local_name
19
+ from prograph.cli._iri_utils import (
20
+ extract_local_name,
21
+ iri_to_rel_table_name,
22
+ )
23
+
24
+
25
+ def xsd_to_sql_type(xsd_iri: Optional[str], dialect: str = 'postgresql') -> str:
26
+ """Map an XSD type IRI to a SQL column type (prograph.schema.xsd)."""
27
+ from prograph.schema import xsd
28
+ return xsd.sql_type(xsd_iri, dialect)
29
+
30
+
31
+ # =============================================================================
32
+ # Result dataclass
33
+ # =============================================================================
34
+
35
+ @dataclass
36
+ class InferenceResult:
37
+ """Result of schema inference."""
38
+ yaml_config: str
39
+ ddl: str
40
+ summary: str
41
+ node_tables: Dict[str, Any] = field(default_factory=dict)
42
+ relationship_tables: Dict[str, Any] = field(default_factory=dict)
43
+
44
+
45
+ # =============================================================================
46
+ # OWL analysis
47
+ # =============================================================================
48
+
49
+ @dataclass
50
+ class ClassInfo:
51
+ """Information about an OWL class."""
52
+ iri: str
53
+ local_name: str
54
+ label: Optional[str] = None
55
+ parent_iri: Optional[str] = None
56
+ children: List[str] = field(default_factory=list)
57
+ data_properties: Dict[str, str] = field(default_factory=dict) # name → xsd type
58
+ is_leaf: bool = True
59
+ # owl:equivalentClass to a class expression (a restriction, an
60
+ # intersection): membership is entailed by a reasoner, not stored.
61
+ is_defined: bool = False
62
+
63
+
64
+ @dataclass
65
+ class ObjectPropertyInfo:
66
+ """Information about an OWL object property."""
67
+ iri: str
68
+ local_name: str
69
+ label: Optional[str] = None
70
+ domain_iri: Optional[str] = None
71
+ range_iri: Optional[str] = None
72
+
73
+
74
+ @dataclass
75
+ class DataPropertyInfo:
76
+ """Information about an OWL datatype property."""
77
+ iri: str
78
+ local_name: str
79
+ label: Optional[str] = None
80
+ domain_iri: Optional[str] = None
81
+ range_iri: Optional[str] = None # XSD type
82
+
83
+
84
+ def _analyze_ontology(g: 'Graph') -> Tuple[
85
+ Dict[str, ClassInfo],
86
+ Dict[str, ObjectPropertyInfo],
87
+ Dict[str, DataPropertyInfo],
88
+ ]:
89
+ """Extract class hierarchy, object properties, and data properties from an
90
+ rdflib graph containing OWL ontology triples.
91
+
92
+ Returns:
93
+ (classes, object_properties, data_properties)
94
+ """
95
+ classes: Dict[str, ClassInfo] = {}
96
+ obj_props: Dict[str, ObjectPropertyInfo] = {}
97
+ data_props: Dict[str, DataPropertyInfo] = {}
98
+
99
+ # --- Collect classes ---
100
+ for subj in g.subjects(RDF.type, OWL.Class):
101
+ if isinstance(subj, BNode):
102
+ continue
103
+ iri = str(subj)
104
+ local = extract_local_name(iri)
105
+ label = None
106
+ for _, _, lbl in g.triples((subj, RDFS.label, None)):
107
+ label = str(lbl)
108
+ break
109
+ parent_iri = None
110
+ for _, _, parent in g.triples((subj, RDFS.subClassOf, None)):
111
+ if isinstance(parent, URIRef):
112
+ parent_iri = str(parent)
113
+ break
114
+ is_defined = any(
115
+ isinstance(expr, BNode)
116
+ for _, _, expr in g.triples((subj, OWL.equivalentClass, None)))
117
+ classes[iri] = ClassInfo(
118
+ iri=iri, local_name=local, label=label, parent_iri=parent_iri,
119
+ is_defined=is_defined,
120
+ )
121
+
122
+ # Mark parents as non-leaf and populate children lists
123
+ for iri, cls in classes.items():
124
+ if cls.parent_iri and cls.parent_iri in classes:
125
+ classes[cls.parent_iri].is_leaf = False
126
+ classes[cls.parent_iri].children.append(iri)
127
+
128
+ # --- Collect object properties ---
129
+ for subj in g.subjects(RDF.type, OWL.ObjectProperty):
130
+ if isinstance(subj, BNode):
131
+ continue
132
+ iri = str(subj)
133
+ local = extract_local_name(iri)
134
+ label = None
135
+ for _, _, lbl in g.triples((subj, RDFS.label, None)):
136
+ label = str(lbl)
137
+ break
138
+ domain_iri = None
139
+ for _, _, dom in g.triples((subj, RDFS.domain, None)):
140
+ if isinstance(dom, URIRef):
141
+ domain_iri = str(dom)
142
+ break
143
+ range_iri = None
144
+ for _, _, rng in g.triples((subj, RDFS.range, None)):
145
+ if isinstance(rng, URIRef):
146
+ range_iri = str(rng)
147
+ break
148
+ obj_props[iri] = ObjectPropertyInfo(
149
+ iri=iri, local_name=local, label=label,
150
+ domain_iri=domain_iri, range_iri=range_iri,
151
+ )
152
+
153
+ # --- Collect data properties ---
154
+ for subj in g.subjects(RDF.type, OWL.DatatypeProperty):
155
+ if isinstance(subj, BNode):
156
+ continue
157
+ iri = str(subj)
158
+ local = extract_local_name(iri)
159
+ label = None
160
+ for _, _, lbl in g.triples((subj, RDFS.label, None)):
161
+ label = str(lbl)
162
+ break
163
+ domain_iri = None
164
+ for _, _, dom in g.triples((subj, RDFS.domain, None)):
165
+ if isinstance(dom, URIRef):
166
+ domain_iri = str(dom)
167
+ break
168
+ range_iri = None
169
+ for _, _, rng in g.triples((subj, RDFS.range, None)):
170
+ if isinstance(rng, URIRef):
171
+ range_iri = str(rng)
172
+ break
173
+ data_props[iri] = DataPropertyInfo(
174
+ iri=iri, local_name=local, label=label,
175
+ domain_iri=domain_iri, range_iri=range_iri,
176
+ )
177
+
178
+ # Attach data properties to their domain classes
179
+ for dp_iri, dp in data_props.items():
180
+ if dp.domain_iri and dp.domain_iri in classes:
181
+ xsd_type = extract_local_name(dp.range_iri) if dp.range_iri else 'string'
182
+ classes[dp.domain_iri].data_properties[dp.local_name] = xsd_type
183
+
184
+ return classes, obj_props, data_props
185
+
186
+
187
+ def _scan_instance_properties(
188
+ g: 'Graph',
189
+ classes: Dict[str, ClassInfo],
190
+ data_props: Dict[str, DataPropertyInfo],
191
+ ) -> None:
192
+ """Scan instance data to discover properties not declared in the ontology.
193
+
194
+ Modifies `classes` in place, adding discovered properties.
195
+ """
196
+ # Build class IRI → set of IRIs of instances
197
+ label_to_class: Dict[str, str] = {}
198
+ for iri, cls in classes.items():
199
+ label_to_class[cls.local_name] = iri
200
+
201
+ # Scan instance rdf:type triples
202
+ instance_classes: Dict[str, Set[str]] = defaultdict(set) # subject → class IRIs
203
+ for subj, _, obj in g.triples((None, RDF.type, None)):
204
+ if isinstance(subj, BNode):
205
+ continue
206
+ obj_str = str(obj)
207
+ if obj_str in classes:
208
+ instance_classes[str(subj)].add(obj_str)
209
+
210
+ # Scan all properties of known instances
211
+ for subj_str, class_iris in instance_classes.items():
212
+ subj = URIRef(subj_str)
213
+ for _, pred, obj in g.triples((subj, None, None)):
214
+ if pred == RDF.type or pred == RDFS.label or pred == RDFS.comment:
215
+ continue
216
+ if isinstance(obj, Literal):
217
+ prop_name = extract_local_name(str(pred))
218
+ # Check if this property is already declared
219
+ for cls_iri in class_iris:
220
+ cls = classes[cls_iri]
221
+ if prop_name not in cls.data_properties:
222
+ # Walk up hierarchy to check parent
223
+ found = False
224
+ parent_iri = cls.parent_iri
225
+ while parent_iri and parent_iri in classes:
226
+ if prop_name in classes[parent_iri].data_properties:
227
+ found = True
228
+ break
229
+ parent_iri = classes[parent_iri].parent_iri
230
+ if not found:
231
+ # Infer type from literal
232
+ xsd_type = 'string'
233
+ if obj.datatype:
234
+ xsd_type = extract_local_name(str(obj.datatype))
235
+ cls.data_properties[prop_name] = xsd_type
236
+
237
+
238
+ # =============================================================================
239
+ # Table grouping strategies
240
+ # =============================================================================
241
+
242
+ @dataclass
243
+ class TableDef:
244
+ """Definition of a table to be generated."""
245
+ table_name: str
246
+ labels: List[str] # label names that map to this table
247
+ columns: Dict[str, str] # column_name → sql_type
248
+ has_discriminator: bool = False
249
+ discriminator_column: str = 'type'
250
+ primary_key: str = 'id'
251
+
252
+
253
+ @dataclass
254
+ class RelTableDef:
255
+ """Definition of a relationship table."""
256
+ table_name: str
257
+ rel_type: str # UPPERCASE rel type
258
+ start_label: Optional[str] = None
259
+ end_label: Optional[str] = None
260
+ columns: Dict[str, str] = field(default_factory=dict) # extra property columns
261
+
262
+
263
+ def _group_shared_tables(
264
+ classes: Dict[str, ClassInfo],
265
+ data_props: Dict[str, DataPropertyInfo],
266
+ dialect: str = 'postgresql',
267
+ ) -> List[TableDef]:
268
+ """Group subclasses under parent tables using filter_predicate strategy.
269
+
270
+ Logic:
271
+ - Process bottom-up: deepest groupable parents first, so that grandparent
272
+ classes (e.g. PhysicalEntity) don't re-absorb already-grouped subtypes.
273
+ - If a parent has ≥2 direct children that are all leaves, group them.
274
+ - If a parent has children that are themselves parents (intermediate),
275
+ those intermediates get their own shared table; the grandparent only
276
+ gets the non-intermediate children (or becomes a standalone table).
277
+ """
278
+ tables: List[TableDef] = []
279
+ processed: Set[str] = set()
280
+
281
+ # Defined classes get no table: a reasoner entails their members.
282
+ skip_names = {cls.local_name for cls in classes.values() if cls.is_defined}
283
+
284
+ def _depth(iri: str) -> int:
285
+ """Compute depth in the class hierarchy (leaf = 0)."""
286
+ cls = classes.get(iri)
287
+ if not cls or not cls.children:
288
+ return 0
289
+ return 1 + max(_depth(c) for c in cls.children)
290
+
291
+ # Sort classes by depth ascending, process leaves/shallow parents first
292
+ sorted_iris = sorted(classes.keys(), key=_depth)
293
+
294
+ for iri in sorted_iris:
295
+ cls = classes[iri]
296
+ if iri in processed:
297
+ continue
298
+ if cls.local_name in skip_names:
299
+ processed.add(iri)
300
+ continue
301
+
302
+ # Collect direct children that haven't been processed yet
303
+ unprocessed_children = [
304
+ c for c in cls.children
305
+ if c not in processed and classes.get(c, ClassInfo(iri='', local_name='')).local_name not in skip_names
306
+ ]
307
+
308
+ if len(unprocessed_children) >= 2:
309
+ # Shared table for this parent's unprocessed children
310
+ all_labels: List[str] = []
311
+ all_columns: Dict[str, str] = {}
312
+
313
+ # Collect properties from the parent class
314
+ _collect_class_columns(classes, iri, all_columns, dialect)
315
+
316
+ # Collect properties and labels from unprocessed children + their descendants
317
+ for child_iri in unprocessed_children:
318
+ child = classes[child_iri]
319
+ all_labels.append(child.local_name)
320
+ _collect_class_columns(classes, child_iri, all_columns, dialect)
321
+ processed.add(child_iri)
322
+
323
+ # Collect grandchildren too (sub-subtypes not yet processed)
324
+ for gc_iri in child.children:
325
+ if gc_iri not in processed:
326
+ gc = classes[gc_iri]
327
+ if gc.local_name not in skip_names:
328
+ all_labels.append(gc.local_name)
329
+ _collect_class_columns(classes, gc_iri, all_columns, dialect)
330
+ processed.add(gc_iri)
331
+
332
+ processed.add(iri)
333
+ table_name = _class_to_table_name(cls.local_name)
334
+
335
+ tables.append(TableDef(
336
+ table_name=table_name,
337
+ labels=sorted(all_labels),
338
+ columns=all_columns,
339
+ has_discriminator=True,
340
+ ))
341
+ elif len(unprocessed_children) == 1:
342
+ # Single child: no discriminator needed, just mark both processed
343
+ # The child will get its own table
344
+ pass
345
+ # else: no children to group, handled in second pass
346
+
347
+ # Remaining classes that weren't grouped
348
+ for iri, cls in classes.items():
349
+ if iri in processed:
350
+ continue
351
+ if cls.local_name in skip_names:
352
+ continue
353
+ # Skip if it has children that were already grouped (abstract parent)
354
+ if cls.children and all(c in processed for c in cls.children):
355
+ processed.add(iri)
356
+ continue
357
+
358
+ all_columns: Dict[str, str] = {}
359
+ _collect_class_columns(classes, iri, all_columns, dialect)
360
+
361
+ table_name = _class_to_table_name(cls.local_name)
362
+ tables.append(TableDef(
363
+ table_name=table_name,
364
+ labels=[cls.local_name],
365
+ columns=all_columns,
366
+ has_discriminator=False,
367
+ ))
368
+ processed.add(iri)
369
+
370
+ return sorted(tables, key=lambda t: t.table_name)
371
+
372
+
373
+ def _group_one_table_per_class(
374
+ classes: Dict[str, ClassInfo],
375
+ data_props: Dict[str, DataPropertyInfo],
376
+ dialect: str = 'postgresql',
377
+ ) -> List[TableDef]:
378
+ """Every leaf class gets its own table."""
379
+ tables: List[TableDef] = []
380
+
381
+ for iri, cls in classes.items():
382
+ # Skip non-leaf and defined classes
383
+ if not cls.is_leaf or cls.is_defined:
384
+ continue
385
+
386
+ all_columns: Dict[str, str] = {}
387
+ _collect_class_columns(classes, iri, all_columns, dialect)
388
+ # Also collect from parent hierarchy
389
+ parent_iri = cls.parent_iri
390
+ while parent_iri and parent_iri in classes:
391
+ _collect_class_columns(classes, parent_iri, all_columns, dialect)
392
+ parent_iri = classes[parent_iri].parent_iri
393
+
394
+ table_name = _class_to_table_name(cls.local_name)
395
+ tables.append(TableDef(
396
+ table_name=table_name,
397
+ labels=[cls.local_name],
398
+ columns=all_columns,
399
+ has_discriminator=False,
400
+ ))
401
+
402
+ return sorted(tables, key=lambda t: t.table_name)
403
+
404
+
405
+ def _collect_class_columns(
406
+ classes: Dict[str, ClassInfo],
407
+ class_iri: str,
408
+ columns: Dict[str, str],
409
+ dialect: str,
410
+ ) -> None:
411
+ """Collect columns from a class and all its ancestors."""
412
+ cls = classes.get(class_iri)
413
+ if not cls:
414
+ return
415
+ for prop_name, xsd_type in cls.data_properties.items():
416
+ col_name = column_from_local_name(prop_name)
417
+ if col_name not in columns:
418
+ columns[col_name] = xsd_to_sql_type(xsd_type, dialect)
419
+ # Walk up hierarchy
420
+ if cls.parent_iri and cls.parent_iri in classes:
421
+ _collect_class_columns(classes, cls.parent_iri, columns, dialect)
422
+
423
+
424
+ def _class_to_table_name(class_name: str) -> str:
425
+ """Convert a class name to a table name (snake_case, pluralized)."""
426
+ snake = column_from_local_name(class_name)
427
+ return _pluralize(snake)
428
+
429
+
430
+ def _pluralize(word: str) -> str:
431
+ """Simple English pluralization for table names."""
432
+ if word.endswith('s') or word.endswith('sh') or word.endswith('ch'):
433
+ return word + 'es'
434
+ if word.endswith('y') and len(word) > 1 and word[-2] not in 'aeiou':
435
+ return word[:-1] + 'ies'
436
+ if word.endswith('x') or word.endswith('z'):
437
+ return word + 'es'
438
+ if not word.endswith('s'):
439
+ return word + 's'
440
+ return word
441
+
442
+
443
+ def _build_rel_tables(
444
+ obj_props: Dict[str, ObjectPropertyInfo],
445
+ classes: Dict[str, ClassInfo],
446
+ ) -> List[RelTableDef]:
447
+ """Build relationship table definitions from object properties."""
448
+ tables: List[RelTableDef] = []
449
+ for iri, prop in obj_props.items():
450
+ rel_type = rel_type_from_local_name(extract_local_name(iri))
451
+ table_name = iri_to_rel_table_name(iri)
452
+
453
+ start_label = None
454
+ end_label = None
455
+ if prop.domain_iri and prop.domain_iri in classes:
456
+ start_label = classes[prop.domain_iri].local_name
457
+ if prop.range_iri and prop.range_iri in classes:
458
+ end_label = classes[prop.range_iri].local_name
459
+
460
+ tables.append(RelTableDef(
461
+ table_name=table_name,
462
+ rel_type=rel_type,
463
+ start_label=start_label,
464
+ end_label=end_label,
465
+ ))
466
+
467
+ return sorted(tables, key=lambda t: t.table_name)
468
+
469
+
470
+ # =============================================================================
471
+ # Output generation
472
+ # =============================================================================
473
+
474
+ def _generate_yaml(
475
+ node_tables: List[TableDef],
476
+ rel_tables: List[RelTableDef],
477
+ graph_name: str = 'inferred_graph',
478
+ comment: Optional[str] = None,
479
+ ) -> str:
480
+ """Generate ProGraph YAML config string."""
481
+ config: Dict[str, Any] = {
482
+ 'version': '1.0',
483
+ 'graph': {
484
+ 'name': graph_name,
485
+ },
486
+ }
487
+ if comment:
488
+ config['graph']['comment'] = comment
489
+
490
+ # Sources
491
+ sources: Dict[str, Any] = {}
492
+ for t in node_tables:
493
+ sources[t.table_name] = {'table': t.table_name}
494
+ for t in rel_tables:
495
+ sources[t.table_name] = {'table': t.table_name}
496
+ config['sources'] = sources
497
+
498
+ # Nodes
499
+ nodes: List[Dict[str, Any]] = []
500
+ for t in node_tables:
501
+ if t.has_discriminator:
502
+ for label in t.labels:
503
+ node: Dict[str, Any] = {
504
+ 'label': label,
505
+ 'source': t.table_name,
506
+ 'id_column': 'id',
507
+ 'filter_predicate': {t.discriminator_column: label},
508
+ }
509
+ # Properties: all columns except id and discriminator
510
+ props = {}
511
+ for col_name, _ in sorted(t.columns.items()):
512
+ if col_name == 'id':
513
+ continue
514
+ props[col_name] = col_name
515
+ if props:
516
+ node['properties'] = props
517
+ nodes.append(node)
518
+ else:
519
+ for label in t.labels:
520
+ node = {
521
+ 'label': label,
522
+ 'source': t.table_name,
523
+ 'id_column': 'id',
524
+ }
525
+ props = {}
526
+ for col_name, _ in sorted(t.columns.items()):
527
+ if col_name == 'id':
528
+ continue
529
+ props[col_name] = col_name
530
+ if props:
531
+ node['properties'] = props
532
+ nodes.append(node)
533
+ config['nodes'] = nodes
534
+
535
+ # Relationships
536
+ relationships: List[Dict[str, Any]] = []
537
+ for t in rel_tables:
538
+ rel: Dict[str, Any] = {
539
+ 'type': t.rel_type,
540
+ 'source': t.table_name,
541
+ 'start_node': {
542
+ 'label': t.start_label or 'Thing',
543
+ 'column': 'start_id',
544
+ },
545
+ 'end_node': {
546
+ 'label': t.end_label or 'Thing',
547
+ 'column': 'end_id',
548
+ },
549
+ }
550
+ relationships.append(rel)
551
+ config['relationships'] = relationships
552
+
553
+ # Serialize with comments
554
+ header = f"# Auto-generated by: prograph infer-schema\n"
555
+ return header + yaml.dump(config, default_flow_style=False, sort_keys=False)
556
+
557
+
558
+ def _generate_ddl(
559
+ node_tables: List[TableDef],
560
+ rel_tables: List[RelTableDef],
561
+ dialect: str = 'postgresql',
562
+ catalog: Optional[str] = None,
563
+ db_schema: Optional[str] = None,
564
+ ) -> str:
565
+ """Generate SQL DDL (CREATE TABLE statements)."""
566
+ lines = [f"-- Auto-generated by: prograph infer-schema"]
567
+ lines.append(f"-- Dialect: {dialect}")
568
+ lines.append("")
569
+
570
+ id_type = 'VARCHAR(255)' if dialect == 'postgresql' else 'STRING'
571
+
572
+ def qualified(name: str) -> str:
573
+ parts = []
574
+ if catalog:
575
+ parts.append(catalog)
576
+ if db_schema:
577
+ parts.append(db_schema)
578
+ parts.append(name)
579
+ return '.'.join(parts)
580
+
581
+ # Node tables
582
+ for t in node_tables:
583
+ lines.append(f"CREATE TABLE IF NOT EXISTS {qualified(t.table_name)} (")
584
+ cols = [f" id {id_type} PRIMARY KEY"]
585
+ if t.has_discriminator:
586
+ disc_type = 'VARCHAR(100)' if dialect == 'postgresql' else 'STRING'
587
+ cols.append(f" {t.discriminator_column} {disc_type} NOT NULL")
588
+ # Add label column (always useful)
589
+ cols.append(f" label {id_type}")
590
+ for col_name, col_type in sorted(t.columns.items()):
591
+ if col_name in ('id', 'label'):
592
+ continue
593
+ cols.append(f" {col_name} {col_type}")
594
+ lines.append(',\n'.join(cols))
595
+ lines.append(");")
596
+ lines.append("")
597
+
598
+ # Relationship tables
599
+ for t in rel_tables:
600
+ lines.append(f"CREATE TABLE IF NOT EXISTS {qualified(t.table_name)} (")
601
+ cols = [
602
+ f" start_id {id_type} NOT NULL",
603
+ f" end_id {id_type} NOT NULL",
604
+ ]
605
+ for col_name, col_type in sorted(t.columns.items()):
606
+ cols.append(f" {col_name} {col_type}")
607
+ cols.append(f" PRIMARY KEY (start_id, end_id)")
608
+ lines.append(',\n'.join(cols))
609
+ lines.append(");")
610
+ lines.append("")
611
+
612
+ return '\n'.join(lines)
613
+
614
+
615
+ def _generate_summary(
616
+ node_tables: List[TableDef],
617
+ rel_tables: List[RelTableDef],
618
+ strategy: str,
619
+ files: List[str],
620
+ ) -> str:
621
+ """Generate a human-readable summary."""
622
+ lines = ["=== ProGraph Schema Inference Summary ===", ""]
623
+ lines.append(f"Source: {', '.join(Path(f).name for f in files)}")
624
+ lines.append(f"Strategy: {strategy}")
625
+ lines.append("")
626
+
627
+ lines.append(f"Node Tables ({len(node_tables)}):")
628
+ for t in node_tables:
629
+ labels_str = ', '.join(t.labels)
630
+ n_cols = len(t.columns) + 1 # +1 for id
631
+ if t.has_discriminator:
632
+ n_cols += 1 # +1 for type discriminator
633
+ lines.append(
634
+ f" {t.table_name:<25} -> {labels_str:<50} "
635
+ f"({n_cols} columns, filter: {t.discriminator_column})"
636
+ )
637
+ else:
638
+ lines.append(
639
+ f" {t.table_name:<25} -> {labels_str:<50} ({n_cols} columns)"
640
+ )
641
+ lines.append("")
642
+
643
+ lines.append(f"Relationship Tables ({len(rel_tables)}):")
644
+ for t in rel_tables:
645
+ start = t.start_label or '?'
646
+ end = t.end_label or '?'
647
+ lines.append(f" {t.table_name:<25} {start} -> {end}")
648
+ lines.append("")
649
+
650
+ lines.append(
651
+ f"Total: {len(node_tables)} node tables, {len(rel_tables)} relationship tables"
652
+ )
653
+ return '\n'.join(lines)
654
+
655
+
656
+ # =============================================================================
657
+ # Main entry point
658
+ # =============================================================================
659
+
660
+ def infer_schema(
661
+ files: List[str],
662
+ dialect: str = 'postgresql',
663
+ strategy: str = 'shared-tables',
664
+ catalog: Optional[str] = None,
665
+ db_schema: Optional[str] = None,
666
+ ) -> InferenceResult:
667
+ """Infer a ProGraph schema from TTL ontology and instance data.
668
+
669
+ Args:
670
+ files: List of TTL file paths (ontology + optional instance data).
671
+ dialect: SQL dialect for DDL ('postgresql' or 'spark').
672
+ strategy: Table grouping strategy ('shared-tables' or 'one-table-per-class').
673
+ catalog: Optional catalog prefix for qualified table names.
674
+ db_schema: Optional schema prefix for qualified table names.
675
+
676
+ Returns:
677
+ InferenceResult with yaml_config, ddl, summary strings.
678
+
679
+ Raises:
680
+ ImportError: If rdflib is not installed.
681
+ """
682
+ if not RDFLIB_AVAILABLE:
683
+ raise ImportError(
684
+ "rdflib is required for infer-schema. Install it with: "
685
+ "pip install prograph[cli]"
686
+ )
687
+
688
+ # Parse all files
689
+ g = Graph()
690
+ for fpath in files:
691
+ g.parse(fpath, format='turtle')
692
+
693
+ # Phase 1: OWL analysis
694
+ classes, obj_props, data_props = _analyze_ontology(g)
695
+
696
+ # Phase 1b: Scan instance data for undeclared properties
697
+ _scan_instance_properties(g, classes, data_props)
698
+
699
+ # Phase 2: Table strategy
700
+ if strategy == 'one-table-per-class':
701
+ node_tables = _group_one_table_per_class(classes, data_props, dialect)
702
+ else:
703
+ node_tables = _group_shared_tables(classes, data_props, dialect)
704
+
705
+ rel_tables = _build_rel_tables(obj_props, classes)
706
+
707
+ # Detect graph name from ontology label
708
+ graph_name = 'inferred_graph'
709
+ ontology_comment = None
710
+ for s in g.subjects(RDF.type, OWL.Ontology):
711
+ for _, _, lbl in g.triples((s, RDFS.label, None)):
712
+ # Convert label to snake_case identifier
713
+ graph_name = column_from_local_name(str(lbl).replace(' ', '_').replace('-', '_'))
714
+ break
715
+ for _, _, cmt in g.triples((s, RDFS.comment, None)):
716
+ ontology_comment = str(cmt).strip().split('\n')[0].strip()
717
+ break
718
+ break
719
+
720
+ # Phase 4-6: Generate outputs
721
+ yaml_config = _generate_yaml(node_tables, rel_tables, graph_name, ontology_comment)
722
+ ddl = _generate_ddl(node_tables, rel_tables, dialect, catalog, db_schema)
723
+ summary = _generate_summary(node_tables, rel_tables, strategy, files)
724
+
725
+ return InferenceResult(
726
+ yaml_config=yaml_config,
727
+ ddl=ddl,
728
+ summary=summary,
729
+ node_tables={t.table_name: t for t in node_tables},
730
+ relationship_tables={t.table_name: t for t in rel_tables},
731
+ )
732
+
733
+
734
+ def write_inference_result(result: InferenceResult, output_dir: str) -> None:
735
+ """Write inference results to files.
736
+
737
+ Args:
738
+ result: InferenceResult from infer_schema()
739
+ output_dir: Directory to write output files to
740
+ """
741
+ out = Path(output_dir)
742
+ out.mkdir(parents=True, exist_ok=True)
743
+
744
+ (out / 'graph.yaml').write_text(result.yaml_config)
745
+ (out / 'create_tables.sql').write_text(result.ddl)
746
+ (out / 'summary.txt').write_text(result.summary)