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,339 @@
1
+ """An ontology over the source maps (docs/architecture/t-mappings.md; decided 2026-11-10).
2
+
3
+ The ontology rewrites the maps, not the query (Ontop's T-mappings): `saturate` gives each node map its
4
+ classes' superclasses and each map that gives a property a copy under each of its super-properties,
5
+ so every pattern reads them as it reads any map. `rdfs:domain` and `rdfs:range` type a term only where
6
+ its property's triple exists, which a map cannot state row by row; the front end gives `?x a :C` a
7
+ branch over that property's own triple pattern (`Translator.typed_by_property`), with its existence
8
+ checks and graphs. RDF 1.1 Semantics 9.2: rdfs2, rdfs3 (domain, range), rdfs5 and rdfs7
9
+ (subPropertyOf), rdfs9 and rdfs11 (subClassOf); owl:equivalentClass and owl:equivalentProperty are the
10
+ two directions of one. The ontology's own triples are not data (SPARQL 1.1 Entailment Regimes 4, C2:
11
+ no axiomatic triples); the `SaturationReport` says which kinds were applied and which were not, and an
12
+ engine refuses (or drops) the axioms its profile does not answer (`profiles.check`)."""
13
+
14
+ from __future__ import annotations
15
+
16
+ from dataclasses import dataclass, field, replace
17
+ from typing import Any, Dict, FrozenSet, Iterable, List, Set, Tuple
18
+
19
+ from prograph.rules import module_home
20
+ from prograph.schema.source_map import EdgeMap, NodeMap, SourceMaps # noqa: F401
21
+
22
+ module_home("t-mapping-saturation", "An ontology's subClassOf, subPropertyOf, domain and range over the maps",
23
+ terms=("ontology", "T-mapping", "subClassOf", "subPropertyOf", "rdfs:domain", "rdfs:range",
24
+ "equivalentClass", "saturate", "RDFS", "saturation report", "ignored axioms"))
25
+
26
+ RDFS = "http://www.w3.org/2000/01/rdf-schema#"
27
+ OWL = "http://www.w3.org/2002/07/owl#"
28
+ RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
29
+ SUB_CLASS, SUB_PROPERTY = RDFS + "subClassOf", RDFS + "subPropertyOf"
30
+ DOMAIN, RANGE = RDFS + "domain", RDFS + "range"
31
+ RESOURCE = RDFS + "Resource"
32
+ EQ_CLASS, EQ_PROPERTY = OWL + "equivalentClass", OWL + "equivalentProperty"
33
+ _READ = {SUB_CLASS, SUB_PROPERTY, DOMAIN, RANGE, EQ_CLASS, EQ_PROPERTY}
34
+ # Declarations and annotations: no axiom to apply.
35
+ _SILENT = {RDF_TYPE, RDFS + "label", RDFS + "comment", RDFS + "seeAlso", RDFS + "isDefinedBy",
36
+ OWL + "imports", OWL + "versionInfo", OWL + "versionIRI", OWL + "priorVersion"}
37
+
38
+
39
+ # A property's characteristics, stated as its rdf:type: axioms the maps do not apply (OWL 2 Structural
40
+ # Specification 9.2; owl:TransitiveProperty was dropped unnamed as a declaration).
41
+ _CHARACTERISTICS = {OWL + k for k in ("TransitiveProperty", "SymmetricProperty", "AsymmetricProperty",
42
+ "ReflexiveProperty", "IrreflexiveProperty", "FunctionalProperty",
43
+ "InverseFunctionalProperty")}
44
+
45
+
46
+ EXAMPLES = 3
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class AxiomKind:
51
+ """One kind of axiom (its predicate, or for a property characteristic its class), how many of
52
+ the ontology's axioms are of it, and the first few of them as N-Triples-like text."""
53
+ kind: str
54
+ count: int
55
+ examples: Tuple[str, ...] = ()
56
+
57
+
58
+ @dataclass(frozen=True)
59
+ class SaturationReport:
60
+ """What 1.0 does with an ontology: the axiom kinds the maps apply (`applied`) and
61
+ the kinds they do not (`ignored`), each with a count and examples. Declarations and annotations
62
+ (rdf:type owl:Class, rdfs:label ...) are neither."""
63
+ applied: Tuple[AxiomKind, ...] = ()
64
+ ignored: Tuple[AxiomKind, ...] = ()
65
+
66
+ def summary(self) -> str:
67
+ def kinds(ks):
68
+ return ", ".join(f"<{k.kind}> ({k.count})" for k in ks) or "none"
69
+ return f"applied: {kinds(self.applied)}; not applied: {kinds(self.ignored)}"
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class Ontology:
74
+ """What the plan reads of an ontology: each class's superclasses and each property's
75
+ super-properties (both closed, each including itself), and each property's domain and range
76
+ classes (through its super-properties, closed under superclasses)."""
77
+ superclasses: Dict[str, FrozenSet[str]] = field(default_factory=dict)
78
+ superproperties: Dict[str, FrozenSet[str]] = field(default_factory=dict)
79
+ domains: Dict[str, FrozenSet[str]] = field(default_factory=dict)
80
+ ranges: Dict[str, FrozenSet[str]] = field(default_factory=dict)
81
+ ignored: Tuple[Tuple[str, int], ...] = ()
82
+ report: SaturationReport = SaturationReport()
83
+ # The ontology's triples closed under the RDFS core (`rdfs.close`): the default graph's ontology triples
84
+ # (`dataset.ontology_triples`); None for an Ontology built by hand.
85
+ closure: Any = field(default=None, compare=False, repr=False)
86
+ # Under profile="ql" the QL axioms closed (`ql.QLTBox`: inverse sub-properties, reflexive properties, the
87
+ # classes of every individual, the consistency checks); None under "rl" and for an Ontology built by hand.
88
+ ql: Any = field(default=None, compare=False, repr=False)
89
+
90
+ def classes_of(self, cls: str) -> FrozenSet[str]:
91
+ """`cls` and its superclasses; with the RDFS core (`closure`) `rdfs:Resource` too: a term typed `cls`
92
+ is a resource (rdfs4a), however the ontology names the class."""
93
+ held = self.superclasses.get(cls, frozenset({cls}))
94
+ return held | {RESOURCE} if self.closure is not None else held
95
+
96
+ def properties_of(self, prop: str) -> FrozenSet[str]:
97
+ return self.superproperties.get(prop, frozenset({prop}))
98
+
99
+
100
+ def _closure(edges: Dict[str, Set[str]]) -> Dict[str, FrozenSet[str]]:
101
+ """Each node's reachable set, itself included (cycles allowed: an equivalence is a cycle)."""
102
+ out: Dict[str, FrozenSet[str]] = {}
103
+ for start in edges:
104
+ seen, todo = {start}, [start]
105
+ while todo:
106
+ for n in edges.get(todo.pop(), ()):
107
+ if n not in seen:
108
+ seen.add(n)
109
+ todo.append(n)
110
+ out[start] = frozenset(seen)
111
+ return out
112
+
113
+
114
+ def read_ontology(graph, consumed=frozenset(), rl: bool = False, kept: Any = None) -> Ontology:
115
+ """The axioms of an rdflib graph the maps apply, IRIs only (a blank-node class, an OWL
116
+ restriction, is another axiom kind); the rest counted by predicate. The triples of `consumed` (those
117
+ OWL RL's rules apply, `owl_rl_rules.RuleSet.consumed`, under profile="rl") are applied too.
118
+ The graph's triples are closed under the RDFS core (`rdfs.close`; `rl`: with OWL 2 RL's schema rules, the
119
+ default graph's ontology triples), and the RDFS core's subClassOf, subPropertyOf, domain and range between
120
+ IRIs are applied too (rdfs:Resource, rdfs:isDefinedBy under rdfs:seeAlso, rdf:_n under rdfs:member ...).
121
+ Under profile="ql" (`rl` False) every OWL 2 QL axiom of `kept` (the graph less the axioms
122
+ `on_unsupported="ignore"` dropped; `graph` where not given) is read and closed by `ql.read`, whose closure
123
+ gives the maps' classes, super-properties, domains and ranges, and the ontology's own assertions closed
124
+ join the RDFS core's closure."""
125
+ from rdflib import URIRef
126
+ sub_c: Dict[str, Set[str]] = {}
127
+ sub_p: Dict[str, Set[str]] = {}
128
+ dom: Dict[str, Set[str]] = {}
129
+ rng: Dict[str, Set[str]] = {}
130
+ ignored: Dict[str, int] = {}
131
+ applied: Dict[str, int] = {}
132
+ examples: Dict[str, List[str]] = {}
133
+
134
+ def seen(counts: Dict[str, int], kind: str, s, p, o) -> None:
135
+ counts[kind] = counts.get(kind, 0) + 1
136
+ held = examples.setdefault(kind, [])
137
+ if len(held) < EXAMPLES:
138
+ held.append(f"{s.n3()} {p.n3()} {o.n3()}")
139
+
140
+ tbox = None
141
+ if not rl:
142
+ # Under "ql" the QL axioms read (`ql.read`) are the applied ones.
143
+ from prograph.plan.ir import ql
144
+ tbox = ql.read(graph if kept is None else kept)
145
+ consumed = tbox.consumed
146
+ for s, pred, o in graph:
147
+ p = str(pred)
148
+ if consumed and (s, pred, o) in consumed:
149
+ if p not in _SILENT or p == RDF_TYPE:
150
+ seen(applied, str(o) if p == RDF_TYPE else p, s, pred, o)
151
+ continue
152
+ if p in _READ and isinstance(s, URIRef) and isinstance(o, URIRef):
153
+ seen(applied, p, s, pred, o)
154
+ a, b = str(s), str(o)
155
+ if p == SUB_CLASS:
156
+ sub_c.setdefault(a, set()).add(b)
157
+ elif p == EQ_CLASS:
158
+ sub_c.setdefault(a, set()).add(b)
159
+ sub_c.setdefault(b, set()).add(a)
160
+ elif p == SUB_PROPERTY:
161
+ sub_p.setdefault(a, set()).add(b)
162
+ elif p == EQ_PROPERTY:
163
+ sub_p.setdefault(a, set()).add(b)
164
+ sub_p.setdefault(b, set()).add(a)
165
+ elif p == DOMAIN:
166
+ dom.setdefault(a, set()).add(b)
167
+ else:
168
+ rng.setdefault(a, set()).add(b)
169
+ elif p == RDF_TYPE and str(o) in _CHARACTERISTICS:
170
+ seen(ignored, str(o), s, pred, o) # named by the characteristic
171
+ elif p.startswith(RDFS) and p not in _SILENT:
172
+ seen(applied, p, s, pred, o) # RDFS's own vocabulary: the RDFS core applies it (`rdfs`)
173
+ elif p not in _SILENT and (p.startswith(OWL) or p in _READ):
174
+ seen(ignored, p, s, pred, o)
175
+ from prograph.plan.ir import rdfs
176
+ triples = rdfs.from_rdflib(graph)
177
+ if tbox is not None:
178
+ # The ontology's own assertions closed under its QL axioms join the RDFS core's closure.
179
+ triples += rdfs.from_rdflib(tbox.abox)
180
+ closure = rdfs.close(triples, rl=rl, ql=not rl, direct=not rl)
181
+ # The maps read the RDFS core's closure alone: under "rl" what OWL 2 RL's schema rules add over class
182
+ # expressions is the materialization's to apply (its rules name what they derive); under "ql" what Direct
183
+ # semantics adds for typed variables (the built-ins, scm-cls) is the typed patterns' alone (`typed-variables`).
184
+ core = rdfs.close(triples) if rl else rdfs.close(triples, ql=True)
185
+ if not rl:
186
+ closure.direct_only = frozenset(closure.triples - core.triples)
187
+ closure.plain = core # the witnessed triples extend the RDFS core alone (`dataset.ontology_triples`)
188
+ held = {SUB_CLASS: sub_c, SUB_PROPERTY: sub_p, DOMAIN: dom, RANGE: rng}
189
+ if tbox is not None:
190
+ extra = [(a[1], kind, b[1]) for kind in held for a, b in core.pairs(rdfs.iri(kind))
191
+ if a[0] == "i" and b[0] == "i" and a != b]
192
+ tbox = ql.read(graph if kept is None else kept, extra)
193
+
194
+ def kinds_(counts: Dict[str, int]) -> Tuple[AxiomKind, ...]:
195
+ return tuple(AxiomKind(k, n, tuple(examples[k])) for k, n in sorted(counts.items()))
196
+ return Ontology(tbox.superclasses, tbox.superproperties, tbox.domains, tbox.ranges,
197
+ tuple(sorted(ignored.items())), SaturationReport(kinds_(applied), kinds_(ignored)), closure,
198
+ tbox)
199
+ for kind, edges in held.items():
200
+ for a, b in core.pairs(rdfs.iri(kind)):
201
+ if a[0] == "i" and b[0] == "i" and a != b:
202
+ edges.setdefault(a[1], set()).add(b[1])
203
+ for d in (dom, rng):
204
+ for props in list(d.values()):
205
+ for c in props:
206
+ sub_c.setdefault(c, set())
207
+ supers_c = _closure(sub_c)
208
+ supers_p = _closure({**{p: set() for p in list(dom) + list(rng)}, **sub_p})
209
+
210
+ def through(direct: Dict[str, Set[str]]) -> Dict[str, FrozenSet[str]]:
211
+ out = {}
212
+ for p, ups in supers_p.items():
213
+ classes = {c for q in ups for c in direct.get(q, ())}
214
+ if classes:
215
+ out[p] = frozenset(x for c in classes for x in supers_c.get(c, {c}))
216
+ return out
217
+ def kinds(counts: Dict[str, int]) -> Tuple[AxiomKind, ...]:
218
+ return tuple(AxiomKind(k, n, tuple(examples[k])) for k, n in sorted(counts.items()))
219
+ return Ontology(supers_c, supers_p, through(dom), through(rng), tuple(sorted(ignored.items())),
220
+ SaturationReport(kinds(applied), kinds(ignored)), closure)
221
+
222
+
223
+ def saturate(maps: SourceMaps, onto: Ontology) -> SourceMaps:
224
+ """`maps` with each node map's classes closed under subClassOf and each property copied under its
225
+ super-properties (a node map's predicate-object map, or an edge map with an id of its own)."""
226
+ nodes: List[NodeMap] = []
227
+ for m in maps.nodes:
228
+ classes = tuple(dict.fromkeys(c for cls in m.classes for c in sorted(onto.classes_of(cls))))
229
+ pos = list(m.predicate_objects)
230
+ for po in m.predicate_objects:
231
+ if po.predicate is None:
232
+ continue
233
+ # A copy keeps its declared name; the property-graph view names it by its predicate
234
+ # (`lpg_view.build`, which tells copies from the maps as declared).
235
+ pos += [replace(po, predicate=q) for q in sorted(onto.properties_of(po.predicate) - {po.predicate})]
236
+ nodes.append(replace(m, classes=classes, predicate_objects=tuple(pos)))
237
+ edges: List[EdgeMap] = list(maps.edges)
238
+ for m in maps.edges:
239
+ if m.predicate is None:
240
+ continue
241
+ for q in sorted(onto.properties_of(m.predicate) - {m.predicate}):
242
+ # A Cypher relationship has one type: the inferred triple is a relationship of its own, of the
243
+ # super-property's type, as it is a triple of its own in SPARQL.
244
+ # It keeps its source's relationship type, so its identity stays its row's
245
+ # (`relationship_identity`); the view names it by its predicate.
246
+ edges.append(replace(m, id=f"{m.id} via <{q}>", order=len(edges), predicate=q))
247
+ out = replace(maps, nodes=tuple(nodes), edges=tuple(edges))
248
+ # The maps as declared, for the property-graph view: a labelled map's declared classes are its label,
249
+ # the classes saturation added are inferred labels (`lpg_view.build`).
250
+ out.__dict__["saturated_from"] = maps
251
+ if "owned_store" in maps.__dict__:
252
+ out.__dict__["owned_store"] = maps.__dict__["owned_store"] # the owned store's view (`lpg_view.build`)
253
+ if "stored_facts" in maps.__dict__:
254
+ out.__dict__["stored_facts"] = maps.__dict__["stored_facts"] # Cypher's derived labels (`lpg_view.with_derived`)
255
+ return out
256
+
257
+
258
+ def typing_properties(onto: Ontology, given: Iterable[str], maps: Any = None) -> List[Tuple[str, FrozenSet[str], bool]]:
259
+ """(property, classes, as subject) for each property the maps give with a domain (True: its
260
+ subjects are of the classes) or a range (False: its IRI and blank-node objects). With the RDFS core
261
+ (`Ontology.closure`) every property's subjects and IRI and blank-node objects are `rdfs:Resource`
262
+ (rdfs4a, rdfs4b): with `maps`, only where some map giving it does not type them so already
263
+ (`resource_typed`)."""
264
+ out = []
265
+ core = frozenset({RESOURCE}) if onto.closure is not None else frozenset()
266
+ for p in sorted(set(given)):
267
+ if p == RDF_TYPE:
268
+ continue
269
+ for as_subject, held in ((True, onto.domains), (False, onto.ranges)):
270
+ extra = core
271
+ if core and maps is not None and all(resource_typed(maps, g, as_subject)
272
+ for g in maps.by_predicate.get(p, ())):
273
+ extra = frozenset()
274
+ # rdfs:Resource is every term's (rdfs4a, rdfs4b), whatever a domain or range says: `extra` decides it.
275
+ classes = (held.get(p, frozenset()) - core) | extra
276
+ if maps is not None and classes - core:
277
+ # A class every giver's term is typed by already (its node map has it, saturated) adds no row:
278
+ # the class branch gives those triples, which the pattern's Distinct keeps once.
279
+ givers = maps.by_predicate.get(p, ())
280
+ classes = frozenset(c for c in classes if c in core or not givers or not all(
281
+ resource_typed(maps, g, as_subject, c) for g in givers))
282
+ if classes:
283
+ out.append((p, classes, as_subject))
284
+ return out
285
+
286
+
287
+ def resource_typed(maps: SourceMaps, giver: Any, as_subject: bool, cls: Any = None) -> bool:
288
+ """Whether every triple of `giver` (a `SourceMaps.by_predicate` entry) has its subject (`as_subject`), or
289
+ its object, typed `rdfs:Resource` (with `cls`: typed `cls`) by the saturated maps already, in the same
290
+ graphs, or has a literal object (no typing): a node map with a class (`Ontology.classes_of` gives it
291
+ `rdfs:Resource`; `cls` among its classes), or an edge end whose row must exist in such a node map."""
292
+ def typed(classes: Tuple[str, ...]) -> bool:
293
+ return cls in classes if cls is not None else bool(classes)
294
+ m = giver.map
295
+ if isinstance(m, NodeMap):
296
+ po = giver.predicate_object
297
+ if not as_subject:
298
+ from prograph.schema.source_map import LITERAL
299
+ return po.object.term_type == LITERAL
300
+ return typed(m.classes) and po.graph == m.graph and po.graph_maps == m.graph_maps
301
+ end = m.start if as_subject else m.end
302
+ if not end.exists or end.map_id is None or end.peers:
303
+ return False
304
+ node = next((n for n in maps.nodes if n.id == end.map_id), None)
305
+ return node is not None and typed(node.classes) and m.graph == node.graph and m.graph_maps == node.graph_maps
306
+
307
+
308
+ def origins(maps: SourceMaps, onto: Ontology, read: Iterable[str] = ()) -> List[str]:
309
+ """Each saturated map's origin in words, for `explain`: the classes a
310
+ node map gains and from which, the copies of a map under a super-property, and the domain and
311
+ range typing; only the maps in `read` (the map ids the plan scans), all where it is empty."""
312
+ want = set(read)
313
+ out: List[str] = []
314
+ for m in maps.nodes:
315
+ if want and m.id not in want:
316
+ continue
317
+ for cls in m.classes:
318
+ gained = sorted(onto.classes_of(cls) - {cls})
319
+ if gained:
320
+ out.append(f"map {m.id}: <{cls}> is also " + ", ".join(f"<{c}>" for c in gained) +
321
+ " (subClassOf, equivalentClass)")
322
+ for po in m.predicate_objects:
323
+ if po.predicate is not None:
324
+ ups = sorted(onto.properties_of(po.predicate) - {po.predicate})
325
+ if ups:
326
+ out.append(f"map {m.id}: <{po.predicate}> also gives " + ", ".join(f"<{q}>" for q in ups) +
327
+ " (subPropertyOf, equivalentProperty)")
328
+ for m in maps.edges:
329
+ if (not want or m.id in want) and m.predicate is not None:
330
+ ups = sorted(onto.properties_of(m.predicate) - {m.predicate})
331
+ if ups:
332
+ out.append(f"map {m.id}: <{m.predicate}> also gives " + ", ".join(f"<{q}>" for q in ups) +
333
+ " (subPropertyOf, equivalentProperty)")
334
+ given = set(maps.by_predicate)
335
+ for p, classes, as_subject in typing_properties(onto, given):
336
+ what = "subjects" if as_subject else "IRI and blank-node objects"
337
+ out.append(f"<{p}>'s {what} are " + ", ".join(f"<{c}>" for c in sorted(classes)) +
338
+ (" (domain)" if as_subject else " (range)"))
339
+ return out
@@ -0,0 +1,103 @@
1
+ """Semantics profiles: which reading of SPARQL's operators a query is planned under.
2
+
3
+ A profile is a frozen `Semantics`, a named set of choices, each with a fixed set of values (one-plan.md
4
+ 1.2). It chooses operator behaviour only: which facts exist (RDFS saturation, OWL RL) is the
5
+ entailment setting, and what makes two cells one RDF term is not a profile field.
6
+
7
+ One field so far, `comparisons` (sparql-choices.md D1):
8
+
9
+ - `xpath`, the `default` profile: 17.3's operator table plus XPath's operators for the other XSD types
10
+ (dates, the g* types, types derived from xsd:string) and the W3C optional features
11
+ KnownTypesDefault2Neq (`1 != "abc"` is true) and LangTagAwareness (`"a"@en = "a"` is false);
12
+ YEAR, MONTH and DAY also take an xsd:date.
13
+ - `core`, strict SPARQL 1.1: only 17.3's operator table (numbers, simple literals and xsd:string,
14
+ xsd:boolean, xsd:dateTime); every other pair of literals goes through RDFterm-equal (17.4.1.7), true for
15
+ one term with itself and a type error otherwise, so `!=` is no more true than `=`; YEAR, MONTH and DAY
16
+ name xsd:dateTime only (17.4.5), so an xsd:date is an error.
17
+
18
+ The profile is set per engine (`ProGraph(..., semantics="core")`) or per query (`/*+ semantics=core */`,
19
+ which wins), read when the query is planned and lowered, and named by `explain`. It is read only at the
20
+ rule homes: `lower.compare` (rule `value-comparison`) and `dates.date_cell` / `dates.date_slot`
21
+ (`date-parts`), by `semantics().comparisons`, and by the facts that a comparison may be an error. A plan
22
+ cache, where one is built, keys on the profile's name.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import contextlib
28
+ import contextvars
29
+ from dataclasses import dataclass
30
+ from typing import Any, Iterator, Literal, Optional, Union
31
+
32
+ from prograph.rules import module_home
33
+
34
+ module_home("semantics-profile", "Which reading of SPARQL's operators a query is planned under",
35
+ terms=("semantics profile", "semantics", "core", "strict SPARQL", "XPath operators", "profile",
36
+ "KnownTypesDefault2Neq", "LangTagAwareness"))
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class Semantics:
41
+ """One profile: a choice per variable row of sparql-choices.md. A new row adds a field here, never a
42
+ free-form setting."""
43
+
44
+ comparisons: Literal["xpath", "core"] = "xpath"
45
+
46
+ def __post_init__(self) -> None:
47
+ if self.comparisons not in ("xpath", "core"):
48
+ raise ValueError(f"Semantics.comparisons is 'xpath' or 'core', not {self.comparisons!r}")
49
+
50
+ @property
51
+ def name(self) -> str:
52
+ """The profile's name where it is a named one, else a description of its choices."""
53
+ for name, profile in PROFILES.items():
54
+ if profile == self:
55
+ return name
56
+ return f"comparisons={self.comparisons}"
57
+
58
+
59
+ DEFAULT = Semantics()
60
+ CORE = Semantics(comparisons="core")
61
+ PROFILES = {"default": DEFAULT, "core": CORE}
62
+
63
+ _CURRENT: contextvars.ContextVar[Semantics] = contextvars.ContextVar("one_plan_semantics", default=DEFAULT)
64
+
65
+
66
+ def semantics() -> Semantics:
67
+ """The profile of the query being planned or lowered."""
68
+ return _CURRENT.get()
69
+
70
+
71
+ def named(value: Union[str, Semantics, None]) -> Semantics:
72
+ """The profile a name or a `Semantics` stands for (None: the default); an unknown name is refused by
73
+ name."""
74
+ if value is None:
75
+ return DEFAULT
76
+ if isinstance(value, Semantics):
77
+ return value
78
+ if isinstance(value, str) and value in PROFILES:
79
+ return PROFILES[value]
80
+ raise ValueError(f"unknown semantics profile {value!r}: the profiles are {', '.join(PROFILES)}")
81
+
82
+
83
+ def of_query(engine: Any, hints: Any) -> Semantics:
84
+ """The profile a query runs under: its `semantics` hint, else the engine's, else the default."""
85
+ asked = getattr(hints, "semantics", None)
86
+ if asked is not None:
87
+ return named(asked)
88
+ return getattr(engine, "semantics", None) or DEFAULT
89
+
90
+
91
+ @contextlib.contextmanager
92
+ def planning_under(profile: Semantics) -> Iterator[Semantics]:
93
+ """Plan and lower under `profile`."""
94
+ token = _CURRENT.set(profile)
95
+ try:
96
+ yield profile
97
+ finally:
98
+ _CURRENT.reset(token)
99
+
100
+
101
+ def comparisons_are_core() -> bool:
102
+ """Whether comparisons follow 17.3's operator table alone (the `core` profile)."""
103
+ return _CURRENT.get().comparisons == "core"