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,313 @@
1
+ """The property-graph schema a model writes Cypher from: the Cypher counterpart of the vocabulary
2
+ `ask` gives a model for SPARQL (`prograph.schema.context.render_sparql`).
3
+
4
+ It is read from the property-graph view the Cypher front end itself reads (`prograph.schema.lpg_view`),
5
+ so the names are the ones a query matches: each label with its property keys and their types, each
6
+ relationship type with its start and end labels, and, under an ontology, the labels and types the
7
+ ontology adds (a superclass, a property's domain or range, an inverse, a stored OWL RL fact).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ from dataclasses import dataclass, field, replace
14
+ from typing import Any, Dict, List, Tuple
15
+
16
+ from prograph.rules import home
17
+ from prograph.schema import xsd
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class LabelInfo:
22
+ """A label: its property keys with their types, and where it comes from."""
23
+ name: str
24
+ keys: Dict[str, Tuple[str, ...]] = field(default_factory=dict)
25
+ origin: Tuple[str, ...] = () # () for a mapped label; else why the ontology gives it
26
+ kinds: Tuple[str, ...] = () # the labels whose nodes are all nodes of this one too (its rows)
27
+ key_columns: Tuple[str, ...] = () # its keys that are a node mapping's key columns (`lpg_view.with_key_properties`)
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class RelInfo:
32
+ """A relationship type: the labels its starts and ends have, its keys, and where it comes from."""
33
+ name: str
34
+ starts: Tuple[str, ...] = ()
35
+ ends: Tuple[str, ...] = ()
36
+ keys: Dict[str, Tuple[str, ...]] = field(default_factory=dict)
37
+ origin: Tuple[str, ...] = ()
38
+ mappings: int = 1 # the edge maps that give it
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class GraphDescription:
43
+ """The labels and relationship types a Cypher query over the engine matches."""
44
+ labels: Tuple[LabelInfo, ...] = ()
45
+ rels: Tuple[RelInfo, ...] = ()
46
+ ontology: bool = False
47
+
48
+ def label(self, name: str) -> LabelInfo:
49
+ return next(l for l in self.labels if l.name == name)
50
+
51
+ def rel(self, name: str) -> RelInfo:
52
+ return next(r for r in self.rels if r.name == name)
53
+
54
+
55
+ # Why the ontology gives a label or a type, as the description says it.
56
+ INFERRED = "a superclass of mapped labels"
57
+ TYPED = "by a property's domain or range"
58
+ DERIVED = "from stored OWL RL facts"
59
+ EVERY_NODE = "every node has it"
60
+ INVERSE = "an inverse or symmetric property, read reversed"
61
+ SUPER_PROPERTY = "a super-property of mapped types"
62
+
63
+
64
+ def _type_of(t: Any, m: Any, column: Any, datatype: Any) -> str:
65
+ """A property's type as the mapping declares it (`cypher_apoc_meta._type_name`, apoc.meta's names),
66
+ with a DECIMAL column named `Decimal`: Cypher compares and orders it but does no arithmetic on it."""
67
+ from prograph.plan.ir.cypher_apoc_meta import _type_name
68
+ held = datatype
69
+ if held is None and column is not None:
70
+ try:
71
+ held = t.held(m.source.table, column)[0]
72
+ except Exception: # noqa: BLE001 - a column of no recorded type: apoc's reading below
73
+ held = None
74
+ if held == xsd.DECIMAL:
75
+ return "Decimal"
76
+ return _type_name(t, m, column, datatype)
77
+
78
+
79
+ @home("cypher-schema-view", "The property-graph schema a model writes Cypher from (ask)",
80
+ terms=("graph schema", "Cypher prompt", "labels and keys", "relationship start and end labels",
81
+ "describe_graph", "render_graph", "ontology labels in the prompt"))
82
+ def describe_graph(engine: Any) -> GraphDescription:
83
+ """The labels and relationship types of `engine` as its Cypher queries read them: the view of
84
+ `cypher_front._view` over the maps a query sees (`dataset.maps_seen`), each property's type as
85
+ apoc.meta gives it (`cypher_apoc_meta`). A label or type the mapped data alone does not give is
86
+ marked with why the ontology gives it. Refused over a schema with no property-graph view (R2RML)."""
87
+ from prograph.plan.ir import cypher_front
88
+ from prograph.plan.ir.cypher_apoc_meta import _end_labels
89
+ from prograph.plan.ir.dataset import maps_seen
90
+ from prograph.plan.ir.entry import _held, ontology_of, source_maps
91
+ from prograph.r2rml.schema import require_property_graph
92
+ from prograph.schema.lpg_view import view_of
93
+
94
+ schema = engine._schema
95
+ require_property_graph(schema, "Cypher")
96
+ onto = ontology_of(engine)
97
+ view = cypher_front._view(maps_seen(engine, onto), onto)
98
+ t = cypher_front._Translator(view, _held(schema), None)
99
+ mapped = view_of(source_maps(schema)) if onto is not None else view
100
+ from prograph.schema.lpg_view import node_identity
101
+ # Labels in the mapping's order, then those the ontology adds (by name).
102
+ names = list(dict.fromkeys([n for m in view.nodes for n in view.node_labels.get(m.id, ())
103
+ if n in mapped.labels] + sorted(view.labels)))
104
+
105
+ def kinds_of(name: str) -> Tuple[str, ...]:
106
+ # The other labels each of whose maps reads only rows a map of `name` reads, as the same nodes.
107
+ own = view.node_maps(name)
108
+ found = []
109
+ for other in names:
110
+ theirs = view.node_maps(other)
111
+ if other != name and other in mapped.labels and theirs and all(
112
+ any(o.source.rows_within(m.source) and node_identity(o) == node_identity(m) for m in own)
113
+ for o in theirs) and not all(
114
+ any(m.source.rows_within(o.source) for o in theirs) for m in own):
115
+ found.append(other)
116
+ return tuple(found)
117
+
118
+ labels: List[LabelInfo] = []
119
+ for name in names:
120
+ keys: Dict[str, List[str]] = {}
121
+ key_columns: List[str] = []
122
+ for m in view.node_maps(name):
123
+ for key, pos in view.properties.get(m.id, {}).items():
124
+ if all(po.predicate is None for po in pos) and key not in key_columns:
125
+ key_columns.append(key)
126
+ for po in pos:
127
+ kind = _type_of(t, m, po.object.column, po.object.datatype)
128
+ if kind not in keys.setdefault(key, []):
129
+ keys[key].append(kind)
130
+ origin: List[str] = []
131
+ if name not in mapped.labels:
132
+ if view.node_maps(name):
133
+ origin.append(INFERRED)
134
+ if name in view.typed and name not in view.derived_labels:
135
+ origin.append(TYPED)
136
+ if name in view.derived_labels:
137
+ origin.append(DERIVED)
138
+ labels.append(LabelInfo(name, {k: tuple(sorted(v)) for k, v in keys.items()}, tuple(origin),
139
+ kinds_of(name) if name in mapped.labels else (), tuple(key_columns)))
140
+ for name in sorted(view.everything):
141
+ labels.append(LabelInfo(name, {}, (EVERY_NODE,)))
142
+ rels: List[RelInfo] = []
143
+ rel_names = list(dict.fromkeys([n for e in view.edges for n, es in view.rel_types.items() if e in es
144
+ and n in mapped.rel_types] + sorted(view.rel_types)))
145
+ for name in rel_names:
146
+ starts: List[str] = []
147
+ ends: List[str] = []
148
+ keys = {}
149
+ for e in view.rel_types[name]:
150
+ for s in _end_labels(t, e.start):
151
+ if s not in starts:
152
+ starts.append(s)
153
+ for x in _end_labels(t, e.end):
154
+ if x not in ends:
155
+ ends.append(x)
156
+ for key, column in e.property_columns:
157
+ kind = _type_of(t, e, column, None)
158
+ if kind not in keys.setdefault(key, []):
159
+ keys[key].append(kind)
160
+ origin = []
161
+ if name not in mapped.rel_types:
162
+ edges = view.rel_types[name]
163
+ if any(e.id.startswith("stored-fact:") for e in edges):
164
+ origin.append(DERIVED)
165
+ if any("~" in e.id for e in edges):
166
+ origin.append(INVERSE)
167
+ if not origin:
168
+ origin.append(SUPER_PROPERTY)
169
+ rels.append(RelInfo(name, tuple(starts), tuple(ends), {k: tuple(sorted(v)) for k, v in keys.items()},
170
+ tuple(origin), len(view.rel_types[name])))
171
+ # A kind's nodes are nodes of the label it is within, so they have that label's keys too (a query's rows
172
+ # with no properties of their own, `HighWearComponent`, return the component's).
173
+ within = {k: l for l in labels for k in l.kinds}
174
+ labels = [replace(l, keys={**within[l.name].keys, **l.keys}) if l.name in within else l for l in labels]
175
+ return GraphDescription(tuple(labels), tuple(rels), onto is not None)
176
+
177
+
178
+ def _keys(keys: Dict[str, Tuple[str, ...]]) -> str:
179
+ return ", ".join(f"{k}: {'|'.join(v)}" for k, v in keys.items())
180
+
181
+
182
+ def _ends(names: Tuple[str, ...]) -> str:
183
+ return "(" + (":" + "|".join(names) if names else "") + ")"
184
+
185
+
186
+ def render_graph(desc: GraphDescription) -> str:
187
+ """The description as the prompt's `## Graph schema` section."""
188
+ lines = ["## Graph schema", "",
189
+ "Labels, each with its property keys and their types (a node has the keys of every label it has):"]
190
+ groups: Dict[Tuple[Tuple[Tuple[str, Tuple[str, ...]], ...], bool], List[str]] = {}
191
+ for l in desc.labels:
192
+ if not l.origin:
193
+ own = any(k not in l.key_columns for k in l.keys)
194
+ groups.setdefault((tuple(l.keys.items()), own), []).append(l.name)
195
+ for (keys, own), names in groups.items():
196
+ # A label whose only keys are its key columns (a query's rows of other labels' nodes): its nodes have the
197
+ # other labels' keys.
198
+ lines.append("- " + ", ".join(f"(:{n})" for n in names) +
199
+ (f" {{{_keys(dict(keys))}}}" if keys else ": no keys of its own") +
200
+ ("" if own else "; its nodes have their other labels' keys"))
201
+ within = [l for l in desc.labels if l.kinds]
202
+ if within:
203
+ lines += ["", "Kinds within a label (a node of a kind has the label too):"]
204
+ lines += [f"- (:{l.name}): {', '.join(l.kinds)}" for l in within]
205
+ lines += ["", "Relationship types, each from its start labels to its end labels:"]
206
+ for r in desc.rels:
207
+ if r.origin:
208
+ continue
209
+ lines.append(f"- {_ends(r.starts)}-[:{r.name}" + (f" {{{_keys(r.keys)}}}" if r.keys else "") +
210
+ f"]->{_ends(r.ends)}")
211
+ added_labels = [l for l in desc.labels if l.origin]
212
+ added_rels = [r for r in desc.rels if r.origin]
213
+ if added_labels or added_rels:
214
+ lines += ["", "Labels and relationship types the ontology adds (match them like the ones above):"]
215
+ for l in added_labels:
216
+ lines.append(f"- (:{l.name})" + (f" {{{_keys(l.keys)}}}" if l.keys else "") + f": {'; '.join(l.origin)}")
217
+ for r in added_rels:
218
+ lines.append(f"- {_ends(r.starts)}-[:{r.name}]->{_ends(r.ends)}: {'; '.join(r.origin)}")
219
+ return "\n".join(lines) + "\n"
220
+
221
+
222
+ def _name_key(l: LabelInfo) -> Any:
223
+ """The key that names a node of `l`: `label`, else `name`, else one ending in `name`; None where none does."""
224
+ keys = list(l.keys)
225
+ return next((k for k in keys if k == "label"), None) or next((k for k in keys if k == "name"), None) or \
226
+ next((k for k in keys if k.lower().endswith("name")), None)
227
+
228
+
229
+ def _var(label: str) -> str:
230
+ # A variable named after what it holds (the prompt's rule).
231
+ word = re.sub(r"\W", "_", label)
232
+ return (word[:1].lower() + word[1:]) if word else "n"
233
+
234
+
235
+ def _a(word: str) -> str:
236
+ return ("an " if word[:1].upper() in "AEIOU" else "a ") + word
237
+
238
+
239
+ def _camel(key: str) -> str:
240
+ head, *rest = key.split("_")
241
+ return head + "".join(w[:1].upper() + w[1:] for w in rest)
242
+
243
+
244
+ def cypher_examples(desc: GraphDescription, *, n: int = 5) -> List[Any]:
245
+ """Cypher examples over the graph schema, the questions of the SPARQL examples (`sparql_examples`)
246
+ answered in Cypher: a lookup, a join over a relationship type, a count of the kinds within a label, a
247
+ variable-length relationship where a type's ends can be its starts again, and a key that may be null;
248
+ then the three with the most of a relationship. The join and the count read a type one mapping gives,
249
+ from one label to another, so each row is one relationship."""
250
+ from prograph.schema.examples import QueryExample
251
+ mapped = [l for l in desc.labels if not l.origin]
252
+ rels = [r for r in desc.rels if not r.origin and r.starts and r.ends]
253
+ by_name = {l.name: l for l in desc.labels}
254
+ out: List[Any] = []
255
+
256
+ def add(question: str, query: str, tags: List[str]) -> None:
257
+ out.append(QueryExample(question=question, query=query, language="cypher", tags=tags))
258
+
259
+ def named(label: str, v: str) -> str:
260
+ """The node and its name beside it, as RETURN items."""
261
+ key = _name_key(by_name[label]) if label in by_name else None
262
+ return f"{v}, {v}.{key} AS {v}Name" if key else v
263
+
264
+ def others(l: LabelInfo) -> List[str]:
265
+ """Its keys but its name and its key columns."""
266
+ return [k for k in l.keys if k != _name_key(l) and k not in l.key_columns]
267
+
268
+ keyed = next((l for l in mapped if others(l)), None)
269
+ if keyed is not None:
270
+ key = others(keyed)[0]
271
+ v = _var(keyed.name)
272
+ order = f"{v}Name" if _name_key(keyed) else f"{v}.{key}"
273
+ add(f"Show ten {keyed.name}s with their {key}",
274
+ f"MATCH ({v}:{keyed.name}) RETURN {named(keyed.name, v)}, {v}.{key} AS {_camel(key)} "
275
+ f"ORDER BY {order} LIMIT 10", ["lookup"])
276
+ # A join and a count over a type of one mapping, from one label to another: a type several mappings give
277
+ # over one table can read a row once per mapping, and an example must answer right.
278
+ single = next((r for r in rels if r.mappings == 1 and len(r.starts) == 1 and len(r.ends) == 1
279
+ and r.starts != r.ends), None)
280
+ if single is not None:
281
+ a, b = single.starts[0], single.ends[0]
282
+ x, y = _var(a), _var(b)
283
+ add(f"Which {b} is each {a} linked to by {single.name}?",
284
+ f"MATCH ({x}:{a})-[:{single.name}]->({y}:{b}) RETURN {named(a, x)}, {named(b, y)}", ["join"])
285
+ parent = next((l for l in mapped if l.kinds), None)
286
+ if parent is not None:
287
+ add(f"How many {parent.name}s are there of each kind?",
288
+ f"MATCH (x:{parent.name}) UNWIND labels(x) AS kind RETURN kind, count(x) AS n", ["aggregation", "hierarchy"])
289
+ # A chain's answer is DISTINCT, so a type of several mappings answers right too; one of one mapping first.
290
+ chains = [r for r in rels if set(r.ends) & set(r.starts)]
291
+ chained = next((r for r in chains if r.mappings == 1), chains[0] if chains else None)
292
+ if chained is not None:
293
+ end = next((o for o in chained.ends if o not in chained.starts), chained.ends[0])
294
+ start = chained.starts[0]
295
+ add(f"What does each {start} reach by {chained.name} one or more times, as far as {_a(end)}?",
296
+ f"MATCH (x:{start})-[:{chained.name}*1..]->(y:{end}) RETURN DISTINCT x, y", ["path"])
297
+ optional = next((l for l in reversed(mapped) if l.kinds and others(l)), None)
298
+ if optional is not None and len(out) < n:
299
+ key = others(optional)[-1]
300
+ add(f"List every {optional.name} and its {key} where it has one",
301
+ f"MATCH (x:{optional.name}) RETURN x, x.{key} AS {_camel(key)}", ["optional"])
302
+ if single is not None:
303
+ a, b = single.starts[0], single.ends[0]
304
+ x, y = _var(a), _var(b)
305
+ key = _name_key(by_name[a]) if a in by_name else None
306
+ order = f"count DESC, {x}Name" if key else "count DESC"
307
+ add(f"Which 3 {a}s have the most {b}s?",
308
+ f"MATCH ({x}:{a})-[:{single.name}]->({y}:{b}) RETURN {named(a, x)}, count({y}) AS count "
309
+ f"ORDER BY {order} LIMIT 3", ["top", "aggregation"])
310
+ return out[:n]
311
+
312
+
313
+ __all__ = ["GraphDescription", "LabelInfo", "RelInfo", "cypher_examples", "describe_graph", "render_graph"]