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,845 @@
1
+ """Schema description for LLM and agent consumption.
2
+
3
+ Provides a frozen, serializable projection of ``GraphSchema`` (``SchemaDescriptor``)
4
+ plus renderers that turn it into different string forms, markdown for humans,
5
+ compact for token-tight contexts, prompt for opinionated LLM system prompts.
6
+
7
+ The descriptor pattern keeps ``GraphSchema`` itself untouched: it owns mutation
8
+ state, indexes, and live DataFrame references that cannot cross a process
9
+ boundary. The descriptor is the form that MCP tools, JSON APIs, and external
10
+ agents can safely consume.
11
+
12
+ Typical use:
13
+
14
+ >>> desc = schema.describe()
15
+ >>> render_markdown(desc) # human/LLM-readable doc
16
+ >>> render_compact(desc) # token-efficient one-liner per type
17
+ >>> render_prompt(desc, role="agent") # opinionated system prompt
18
+ >>> desc.to_dict() # JSON-serializable
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import difflib
24
+ from dataclasses import asdict, dataclass, field
25
+ from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Set, Tuple
26
+ from prograph.rules import home
27
+
28
+ if TYPE_CHECKING:
29
+ from prograph.schema.mapping import GraphSchema, NodeMapping, RelationshipMapping
30
+
31
+
32
+ SUPPORTED_LANGUAGES: List[str] = ["cypher", "sparql"]
33
+
34
+ Role = Literal["nli", "agent", "explainer"]
35
+ Language = Literal["cypher", "sparql"]
36
+
37
+
38
+ # ──────────────────────────────────────────────────────────────────────────
39
+ # Descriptor: frozen, serializable projection of a GraphSchema
40
+ # ──────────────────────────────────────────────────────────────────────────
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class PropertyDescriptor:
45
+ """A property on a node or relationship."""
46
+
47
+ name: str
48
+ column: str
49
+ inferred_type: Optional[str] = None
50
+ sample_values: Optional[List[Any]] = None
51
+
52
+
53
+ @dataclass(frozen=True)
54
+ class NodeDescriptor:
55
+ """A node label and its mapped columns."""
56
+
57
+ label: str
58
+ id_columns: List[str]
59
+ properties: List[PropertyDescriptor]
60
+ source_table: str
61
+ qualified_source_table: Optional[str] = None
62
+ row_count: Optional[int] = None
63
+ filter_predicate: Optional[Dict[str, Any]] = None
64
+ mutable: bool = False
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class RelationshipDescriptor:
69
+ """A relationship type and its endpoints."""
70
+
71
+ rel_type: str
72
+ start_label: str
73
+ end_label: str
74
+ start_id_columns: List[str]
75
+ end_id_columns: List[str]
76
+ properties: List[PropertyDescriptor]
77
+ source_table: str
78
+ qualified_source_table: Optional[str] = None
79
+ row_count: Optional[int] = None
80
+ mutable: bool = False
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class PredicateDescriptor:
85
+ """An RDF predicate IRI mapped to LPG structure.
86
+
87
+ Used by SPARQL execution to resolve a concrete predicate URI to either
88
+ a node property (datatype property) or a relationship type (object
89
+ property). Surfaces what would otherwise be an opaque internal detail.
90
+ """
91
+
92
+ predicate_iri: str
93
+ kind: str # "datatype" | "object"
94
+ node_label: Optional[str] = None
95
+ property_name: Optional[str] = None
96
+ relationship_type: Optional[str] = None
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class ClassDescriptor:
101
+ """A node label as the RDF class SPARQL reads (`iri.class_iri`).
102
+ `within` are the IRIs of the classes whose rows hold every row of this
103
+ one (`mapping.rows_within`: a filtered label of a shared table is within
104
+ the label of the whole table), so a query over one of them covers it."""
105
+
106
+ iri: str
107
+ label: str
108
+ within: List[str] = field(default_factory=list)
109
+ filter_predicate: Optional[Dict[str, Any]] = None
110
+ # How an individual's IRI is written (`iri.node_iri_template`).
111
+ individuals: Optional[str] = None
112
+
113
+
114
+ @dataclass(frozen=True)
115
+ class TermDescriptor:
116
+ """A predicate as SPARQL reads it: its IRI (declared, else the default
117
+ vocabulary's: `iri.property_iri`, `iri.relationship_iri`), the classes
118
+ of its subjects, and a datatype predicate's literal datatype or an
119
+ object predicate's object classes."""
120
+
121
+ iri: str
122
+ kind: str # "datatype" | "object"
123
+ subject_classes: List[str] = field(default_factory=list)
124
+ datatype: Optional[str] = None
125
+ object_classes: List[str] = field(default_factory=list)
126
+
127
+
128
+ @dataclass(frozen=True)
129
+ class VocabularyDescriptor:
130
+ """The schema as the RDF vocabulary a SPARQL query is written in."""
131
+
132
+ prefixes: Dict[str, str] = field(default_factory=dict)
133
+ classes: List[ClassDescriptor] = field(default_factory=list)
134
+ predicates: List[TermDescriptor] = field(default_factory=list)
135
+
136
+
137
+ @dataclass(frozen=True)
138
+ class SchemaDescriptor:
139
+ """A frozen, serializable description of a graph schema."""
140
+
141
+ nodes: List[NodeDescriptor]
142
+ relationships: List[RelationshipDescriptor]
143
+ predicates: List[PredicateDescriptor] = field(default_factory=list)
144
+ languages: List[str] = field(default_factory=lambda: list(SUPPORTED_LANGUAGES))
145
+ graph_name: Optional[str] = None
146
+ vocabulary: Optional[VocabularyDescriptor] = None
147
+
148
+ def to_dict(self) -> Dict[str, Any]:
149
+ """Return a JSON-serializable dict representation."""
150
+ return asdict(self)
151
+
152
+ def node(self, label: str) -> Optional[NodeDescriptor]:
153
+ """Look up a node descriptor by label."""
154
+ for n in self.nodes:
155
+ if n.label == label:
156
+ return n
157
+ return None
158
+
159
+ def relationships_of(self, rel_type: str) -> List[RelationshipDescriptor]:
160
+ """Return all relationship descriptors with the given type."""
161
+ return [r for r in self.relationships if r.rel_type == rel_type]
162
+
163
+
164
+ # ──────────────────────────────────────────────────────────────────────────
165
+ # Builder: GraphSchema -> SchemaDescriptor
166
+ # ──────────────────────────────────────────────────────────────────────────
167
+
168
+
169
+ def _node_to_descriptor(
170
+ mapping: "NodeMapping", schema: "GraphSchema"
171
+ ) -> NodeDescriptor:
172
+ props = [
173
+ PropertyDescriptor(name=name, column=col)
174
+ for name, col in mapping.property_columns.items()
175
+ ]
176
+ stats = schema.get_table_stats(mapping.source_table)
177
+ return NodeDescriptor(
178
+ label=mapping.label,
179
+ id_columns=list(mapping.id_columns),
180
+ properties=props,
181
+ source_table=mapping.source_table,
182
+ qualified_source_table=mapping.qualified_source_table,
183
+ row_count=stats.row_count if stats else None,
184
+ filter_predicate=dict(mapping.filter_predicate) if mapping.filter_predicate else None,
185
+ mutable=mapping.mutable,
186
+ )
187
+
188
+
189
+ def _end_label(schema: "GraphSchema", label: Optional[str], identity: Optional[str]) -> str:
190
+ """A relationship end as a pattern writes it: its label, or for an end given by an identity the labels of
191
+ the node mappings declaring it (`Post|Comment`)."""
192
+ if label is not None or identity is None:
193
+ return label or ""
194
+ return "|".join(dict.fromkeys(m.label for m in schema.node_mappings
195
+ if getattr(m, "identity", None) == identity and m.label is not None))
196
+
197
+
198
+ def _relationship_to_descriptor(
199
+ mapping: "RelationshipMapping", schema: "GraphSchema"
200
+ ) -> RelationshipDescriptor:
201
+ props = [
202
+ PropertyDescriptor(name=name, column=col)
203
+ for name, col in mapping.property_columns.items()
204
+ ]
205
+ stats = schema.get_table_stats(mapping.source_table)
206
+ return RelationshipDescriptor(
207
+ rel_type=mapping.rel_type,
208
+ start_label=_end_label(schema, mapping.start_node_label, getattr(mapping, "start_node_identity", None)),
209
+ end_label=_end_label(schema, mapping.end_node_label, getattr(mapping, "end_node_identity", None)),
210
+ start_id_columns=list(mapping.start_id_columns),
211
+ end_id_columns=list(mapping.end_id_columns),
212
+ properties=props,
213
+ source_table=mapping.source_table,
214
+ qualified_source_table=mapping.qualified_source_table,
215
+ row_count=stats.row_count if stats else None,
216
+ mutable=mapping.mutable,
217
+ )
218
+
219
+
220
+ def _predicate_to_descriptor(mapping: "PredicateMapping") -> PredicateDescriptor:
221
+ return PredicateDescriptor(
222
+ predicate_iri=mapping.predicate_iri,
223
+ kind=mapping.kind.value if hasattr(mapping.kind, "value") else str(mapping.kind),
224
+ node_label=mapping.node_label,
225
+ property_name=mapping.property_name,
226
+ relationship_type=mapping.relationship_type,
227
+ )
228
+
229
+
230
+ def describe_schema(schema: "GraphSchema") -> SchemaDescriptor:
231
+ """Project a ``GraphSchema`` into a frozen ``SchemaDescriptor``.
232
+
233
+ Reads from the schema's mappings and table stats. Does not access live
234
+ DataFrames or the engine; safe to call from any thread or process.
235
+ """
236
+ nodes = [_node_to_descriptor(m, schema) for m in schema.node_mappings]
237
+ rels = [_relationship_to_descriptor(m, schema) for m in schema.relationship_mappings]
238
+ preds = [
239
+ _predicate_to_descriptor(pm)
240
+ for pm in (schema.predicate_mappings or {}).values()
241
+ ]
242
+ return SchemaDescriptor(
243
+ nodes=nodes,
244
+ relationships=rels,
245
+ predicates=preds,
246
+ languages=list(SUPPORTED_LANGUAGES),
247
+ graph_name=schema.name,
248
+ vocabulary=describe_vocabulary(schema),
249
+ )
250
+
251
+
252
+ @home("schema-vocabulary", "A schema as SPARQL vocabulary",
253
+ terms=("describe_vocabulary", "render_sparql", "vocabulary", "sparql_prefixes", "undeclared_iris"))
254
+ def describe_vocabulary(schema: "GraphSchema") -> VocabularyDescriptor:
255
+ """The classes and predicates a SPARQL query over `schema` names, each
256
+ by the IRI the engine reads it by, and the schema's prefixes."""
257
+ from prograph.schema import iri as I
258
+ from prograph.schema import xsd
259
+ from prograph.schema.mapping import rows_within
260
+
261
+ if getattr(schema, "property_graph", True) is False:
262
+ return _vocabulary_of_maps(schema)
263
+ nodes = [m for m in schema.node_mappings if I.is_rdf_class(m)]
264
+ by_label = {m.label: m for m in nodes}
265
+ classes = [ClassDescriptor(
266
+ iri=I.class_iri(m), label=m.label,
267
+ within=[I.class_iri(o) for o in nodes if o is not m and rows_within(m, o)
268
+ and not rows_within(o, m)],
269
+ filter_predicate=dict(m.filter_predicate) if m.filter_predicate else None,
270
+ individuals=I.node_iri_template(m))
271
+ for m in nodes]
272
+
273
+ terms: Dict[str, Dict[str, Any]] = {}
274
+
275
+ def add(iri: str, kind: str, subject: Optional[str], datatype: Optional[str] = None,
276
+ object_class: Optional[str] = None) -> None:
277
+ term = terms.setdefault(iri, {"kind": kind, "subjects": [], "datatype": datatype, "objects": []})
278
+ if subject and subject not in term["subjects"]:
279
+ term["subjects"].append(subject)
280
+ if object_class and object_class not in term["objects"]:
281
+ term["objects"].append(object_class)
282
+ if term["datatype"] is None:
283
+ term["datatype"] = datatype
284
+
285
+ declared = {(pm.node_label, pm.property_name): pm
286
+ for pm in (schema.predicate_mappings or {}).values() if pm.property_name}
287
+ for m in schema.node_mappings: # an unlabelled mapping's properties too, with no subject class
288
+ for name, column in m.property_columns.items():
289
+ pm = declared.get((m.label, name))
290
+ datatype = (getattr(pm, "datatype", None)
291
+ or xsd.datatype_of_type(schema.column_type(m, column)))
292
+ add(I.property_iri(schema, m.label, name), "datatype", I.class_iri(m) if I.is_rdf_class(m) else None,
293
+ datatype)
294
+
295
+ def end_classes(label: Optional[str], identity: Optional[str]) -> List[Optional[str]]:
296
+ """An end's classes: its label's, or those of the classed mappings declaring its identity."""
297
+ if identity is not None:
298
+ return [I.class_iri(m) for m in nodes if getattr(m, "identity", None) == identity] or [None]
299
+ return [I.class_iri(by_label[label])] if label in by_label else [None]
300
+ for r in schema.relationship_mappings:
301
+ starts = end_classes(r.start_node_label, getattr(r, "start_node_identity", None))
302
+ ends = end_classes(r.end_node_label, getattr(r, "end_node_identity", None))
303
+ for start in starts:
304
+ for end in ends:
305
+ add(I.relationship_iri(schema, r.rel_type), "object", start, object_class=end)
306
+ predicates = [TermDescriptor(iri=k, kind=v["kind"], subject_classes=v["subjects"],
307
+ datatype=v["datatype"], object_classes=v["objects"])
308
+ for k, v in terms.items()]
309
+ return VocabularyDescriptor(prefixes=dict(schema.prefixes or {}), classes=classes, predicates=predicates)
310
+
311
+
312
+ # ──────────────────────────────────────────────────────────────────────────
313
+ # Renderers: SchemaDescriptor -> string
314
+ # ──────────────────────────────────────────────────────────────────────────
315
+
316
+
317
+ def render_markdown(desc: SchemaDescriptor) -> str:
318
+ """Render a human/LLM-readable markdown description.
319
+
320
+ Format matches the body of the prior ``build_schema_description`` so that
321
+ existing prompts and tests see no behavioral change. Returns
322
+ ``"No schema available."`` when the descriptor is empty.
323
+ """
324
+ if not desc.nodes and not desc.relationships:
325
+ return "No schema available."
326
+
327
+ lines: List[str] = []
328
+
329
+ if desc.nodes:
330
+ lines.append("## Node Labels")
331
+ lines.append("")
332
+ for node in desc.nodes:
333
+ prop_names = [p.name for p in node.properties]
334
+ id_part = (
335
+ f"identifier: `{node.id_columns[0]}`"
336
+ if len(node.id_columns) == 1
337
+ else f"identifier: {', '.join(f'`{c}`' for c in node.id_columns)}"
338
+ )
339
+ if prop_names:
340
+ lines.append(
341
+ f"- **{node.label or '(no label)'}** ({id_part}): {', '.join(prop_names)}"
342
+ )
343
+ else:
344
+ lines.append(f"- **{node.label or '(no label)'}** ({id_part}): (no properties)")
345
+ lines.append("")
346
+
347
+ if desc.relationships:
348
+ lines.append("## Relationship Types")
349
+ lines.append("")
350
+ for rel in desc.relationships:
351
+ pattern = f"(:{rel.start_label})-[:{rel.rel_type}]->(:{rel.end_label})"
352
+ prop_names = [p.name for p in rel.properties]
353
+ suffix = f" with properties: {', '.join(prop_names)}" if prop_names else ""
354
+ lines.append(f"- {pattern}{suffix}")
355
+ lines.append("")
356
+
357
+ return "\n".join(lines)
358
+
359
+
360
+ from prograph.schema.xsd import XSD as _XSD_NAMESPACE # noqa: E402
361
+
362
+ # The namespaces a query may name terms of without the schema declaring them.
363
+ _STANDARD_NAMESPACES = (
364
+ "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
365
+ "http://www.w3.org/2000/01/rdf-schema#",
366
+ "http://www.w3.org/2002/07/owl#",
367
+ _XSD_NAMESPACE,
368
+ )
369
+
370
+
371
+ def undeclared_iris(schema: "GraphSchema", query: str, ontology: Any = None) -> List[Dict[str, Any]]:
372
+ """Each class or predicate IRI of the query the schema does not
373
+ declare, with the nearest declared ones. A triple with such an IRI
374
+ matches nothing (two IRIs are equal only when they are the same string,
375
+ RDF 1.1 Concepts 3.2), so the agent hears of it rather than reading an
376
+ empty answer as the data's. None of a query that does not parse."""
377
+ used = _query_terms(query)
378
+ if not used:
379
+ return []
380
+ known = _known_terms(schema, ontology)
381
+ warnings = []
382
+ for iri, kind in sorted(used):
383
+ if iri in known or iri.startswith(_STANDARD_NAMESPACES):
384
+ continue
385
+ # The nearest of its own kind: a class for a class.
386
+ candidates = sorted(k for k, v in known.items() if v == kind)
387
+ local = _local(iri)
388
+ by_local = {}
389
+ for k in candidates:
390
+ by_local.setdefault(_local(k), []).append(k)
391
+ near = [k for name in difflib.get_close_matches(local, list(by_local), n=3, cutoff=0.6)
392
+ for k in by_local[name]]
393
+ near += [k for k in difflib.get_close_matches(iri, candidates, n=3, cutoff=0.8) if k not in near]
394
+ warnings.append({"iri": iri, "used_as": kind,
395
+ "message": f"the schema declares no {kind} <{iri}>: it matches nothing",
396
+ "nearest": near[:3]})
397
+ return warnings
398
+
399
+
400
+ def _local(iri: str) -> str:
401
+ cut = max(iri.rfind("#"), iri.rfind("/"))
402
+ return iri[cut + 1:]
403
+
404
+
405
+ def _known_terms(schema: "GraphSchema", ontology: Any) -> Dict[str, str]:
406
+ """Each declared IRI and its kind, 'class' or 'predicate'."""
407
+ vocab = describe_vocabulary(schema)
408
+ known = {c.iri: "class" for c in vocab.classes}
409
+ known.update({t.iri: "predicate" for t in vocab.predicates})
410
+ if ontology is not None:
411
+ # A class or property of the ontology the mapping does not map
412
+ # (a superclass a query is expanded through) in a namespace of the
413
+ # vocabulary.
414
+ namespaces = {k[:len(k) - len(_local(k))] for k in known}
415
+ for kind, names in (("class", getattr(ontology, "classes", ()) or ()),
416
+ ("predicate", getattr(ontology, "properties", {}) or {})):
417
+ for ns in namespaces:
418
+ for name in names:
419
+ known.setdefault(ns + name, kind)
420
+ return known
421
+
422
+
423
+ def _query_terms(query: str) -> Set[Tuple[str, str]]:
424
+ """(IRI, 'class' or 'predicate') of each class a query types a term with
425
+ and each predicate it names, property paths included. Read with
426
+ rdflib's algebra; an empty set where it cannot read the query."""
427
+ try:
428
+ from rdflib import URIRef
429
+ from rdflib.namespace import RDF
430
+ from rdflib.paths import Path
431
+ from rdflib.plugins.sparql.algebra import translateQuery
432
+ from rdflib.plugins.sparql.parser import parseQuery, parseUpdate
433
+ try:
434
+ algebra = translateQuery(parseQuery(query)).algebra
435
+ except Exception: # noqa: BLE001 - an update, or text rdflib does not read
436
+ algebra = parseUpdate(query)
437
+ except Exception: # noqa: BLE001
438
+ return set()
439
+ found: Set[Tuple[str, str]] = set()
440
+
441
+ def path_terms(path: Any) -> None:
442
+ if isinstance(path, URIRef):
443
+ found.add((str(path), "predicate"))
444
+ elif isinstance(path, Path):
445
+ for value in vars(path).values():
446
+ for part in value if isinstance(value, (list, tuple)) else [value]:
447
+ path_terms(part)
448
+
449
+ seen: Set[int] = set()
450
+
451
+ def walk(node: Any) -> None:
452
+ if id(node) in seen:
453
+ return
454
+ seen.add(id(node))
455
+ if isinstance(node, dict):
456
+ for key, value in node.items():
457
+ if key == "triples" and isinstance(value, (list, tuple)):
458
+ for triple in value:
459
+ if isinstance(triple, (list, tuple)) and len(triple) == 3:
460
+ _, p, o = triple
461
+ path_terms(p)
462
+ if p == RDF.type and isinstance(o, URIRef):
463
+ found.add((str(o), "class"))
464
+ walk(value)
465
+ elif isinstance(node, (list, tuple)):
466
+ for value in node:
467
+ walk(value)
468
+ elif hasattr(node, "items") and not isinstance(node, (str, bytes)):
469
+ walk(dict(node.items()))
470
+
471
+ walk(algebra)
472
+ return found
473
+
474
+
475
+ _WELL_KNOWN_PREFIXES = {
476
+ "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
477
+ "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
478
+ "xsd": _XSD_NAMESPACE,
479
+ "owl": "http://www.w3.org/2002/07/owl#",
480
+ }
481
+
482
+
483
+ def _namespace(iri: str) -> str:
484
+ cut = max(iri.rfind("#"), iri.rfind("/"))
485
+ return iri[:cut + 1] if cut >= 0 else iri
486
+
487
+
488
+ def sparql_prefixes(vocab: VocabularyDescriptor) -> Dict[str, str]:
489
+ """The PREFIX lines for a query over `vocab`: the schema's own, the
490
+ well-known ones its IRIs use, and for any other namespace one of its
491
+ own, the most used the empty prefix `:`. A schema prefix no class,
492
+ predicate or datatype of the vocabulary is in is left out (R2RML's
493
+ `rr:`, which no published triple uses), but for `xsd:`, which a typed
494
+ literal is written with."""
495
+ iris = ([c.iri for c in vocab.classes] + [t.iri for t in vocab.predicates]
496
+ + [t.datatype for t in vocab.predicates if t.datatype])
497
+ prefixes = {name: namespace for name, namespace in vocab.prefixes.items()
498
+ if namespace == _WELL_KNOWN_PREFIXES.get("xsd")
499
+ or any(iri.startswith(namespace) for iri in iris)}
500
+ taken = set(prefixes.values())
501
+ counts: Dict[str, int] = {}
502
+ for iri in iris:
503
+ counts[_namespace(iri)] = counts.get(_namespace(iri), 0) + 1
504
+ for name, namespace in _WELL_KNOWN_PREFIXES.items():
505
+ if namespace in counts and namespace not in taken and name not in prefixes:
506
+ prefixes[name] = namespace
507
+ taken.add(namespace)
508
+ others = sorted((n for n in counts if n not in taken), key=lambda n: (-counts[n], n))
509
+ for i, namespace in enumerate(others):
510
+ name = "" if i == 0 and "" not in prefixes else f"ns{i}"
511
+ prefixes[name] = namespace
512
+ return prefixes
513
+
514
+
515
+ def curie(iri: str, prefixes: Dict[str, str]) -> str:
516
+ """`iri` as a prefixed name where a prefix's namespace and a plain local
517
+ name allow one, else `<iri>`."""
518
+ import re
519
+ for name, namespace in sorted(prefixes.items(), key=lambda p: -len(p[1])):
520
+ local = iri[len(namespace):] if iri.startswith(namespace) else None
521
+ if local is not None and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_-]*", local):
522
+ return f"{name}:{local}"
523
+ return f"<{iri}>"
524
+
525
+
526
+ def render_sparql(desc: SchemaDescriptor) -> str:
527
+ """The schema as a SPARQL writer reads it: the PREFIX lines, the
528
+ classes (a class within another listed under it), and each predicate
529
+ with its subjects' classes and its datatype or its objects' classes."""
530
+ vocab = desc.vocabulary
531
+ if vocab is None or not (vocab.classes or vocab.predicates):
532
+ return ""
533
+ prefixes = sparql_prefixes(vocab)
534
+ c = lambda iri: curie(iri, prefixes)
535
+ lines = ["## SPARQL vocabulary", "",
536
+ "Start every query with these PREFIX lines:", "```"]
537
+ lines += [f"PREFIX {name}: <{namespace}>" for name, namespace in prefixes.items()]
538
+ lines += ["```", "", "### Classes (`?x a <class>`)", ""]
539
+ within = {k.iri: k for k in vocab.classes}
540
+ for k in vocab.classes:
541
+ if k.within:
542
+ continue
543
+ lines.append(f"- {c(k.iri)}")
544
+ subs = [s for s in vocab.classes if k.iri in s.within]
545
+ if subs:
546
+ lines.append(f" - within it (each is some of its rows; a query over {c(k.iri)} "
547
+ f"covers them): " + ", ".join(c(s.iri) for s in subs))
548
+ templates: Dict[str, List[str]] = {}
549
+ for k in vocab.classes:
550
+ if k.individuals and not k.within:
551
+ templates.setdefault(k.individuals, []).append(c(k.iri))
552
+ if templates:
553
+ lines += ["", "### Individuals", "",
554
+ "Name one by its IRI in angle brackets, its key in place of the braces "
555
+ "(`<...#{id}>` for id `x-1` is `<...#x-1>`); a class within another names its "
556
+ "individuals as that one does. The key is the identifier in the IRI, not a value "
557
+ "of a property: an individual named by a property's value (a serial number, a "
558
+ "name) is matched on that property:", ""]
559
+ lines += [f"- {', '.join(names)}: `<{template}>`" for template, names in templates.items()]
560
+ lines += ["", "### Predicates (`?subject <predicate> ?object`)", ""]
561
+
562
+ def fold(classes: List[str]) -> List[str]:
563
+ # A subclass of a class listed beside it adds nothing.
564
+ return [k for k in classes if not any(w in classes for w in getattr(within.get(k), "within", []))]
565
+
566
+ for t in vocab.predicates:
567
+ subjects = ", ".join(c(k) for k in fold(t.subject_classes)) or "any"
568
+ if t.kind == "object":
569
+ objects = ", ".join(c(k) for k in fold(t.object_classes)) or "any"
570
+ lines.append(f"- {c(t.iri)}: {subjects} -> {objects}")
571
+ else:
572
+ lines.append(f"- {c(t.iri)}: {subjects} -> literal {c(t.datatype) if t.datatype else ''}".rstrip())
573
+ return "\n".join(lines)
574
+
575
+
576
+ def render_compact(desc: SchemaDescriptor) -> str:
577
+ """Render a token-efficient form, one line per node and relationship.
578
+
579
+ Useful for tool descriptions, system prompts under tight context budgets,
580
+ or anywhere a one-glance summary beats a markdown document.
581
+
582
+ Example output::
583
+
584
+ Person(id, name, age)
585
+ Company(id, name, industry)
586
+ (Person)-[KNOWS]->(Person)
587
+ (Person)-[WORKS_AT {since, role}]->(Company)
588
+ """
589
+ if not desc.nodes and not desc.relationships:
590
+ return ""
591
+
592
+ lines: List[str] = []
593
+ for node in desc.nodes:
594
+ prop_names = [p.name for p in node.properties]
595
+ cols = list(node.id_columns) + prop_names
596
+ lines.append(f"{node.label or '(no label)'}({', '.join(cols)})")
597
+ for rel in desc.relationships:
598
+ prop_names = [p.name for p in rel.properties]
599
+ prop_part = f" {{{', '.join(prop_names)}}}" if prop_names else ""
600
+ lines.append(f"({rel.start_label})-[{rel.rel_type}{prop_part}]->({rel.end_label})")
601
+ return "\n".join(lines)
602
+
603
+
604
+ _CYPHER_SYNTAX_GUIDE = """## Cypher Syntax Reference
605
+
606
+ ### Pattern Matching
607
+ - `MATCH (n:Label)` - Match nodes with label
608
+ - `MATCH (a)-[:REL_TYPE]->(b)` - Match relationships
609
+ - `MATCH (a)-[:REL*1..3]->(b)` - Variable-length paths
610
+
611
+ ### Filtering
612
+ - `WHERE n.property = value` - Equality
613
+ - `WHERE n.property > value` - Comparison
614
+ - `WHERE n.property IN [...]` - List membership
615
+ - `WHERE n.property CONTAINS 'text'` - String contains
616
+ - `WHERE n.property STARTS WITH 'text'` - String prefix
617
+
618
+ ### Aggregation
619
+ - `count(n)` - Count nodes
620
+ - `sum(n.prop)` - Sum values
621
+ - `avg(n.prop)` - Average
622
+ - `collect(n.prop)` - Collect into list
623
+
624
+ ### Ordering and Limiting
625
+ - `ORDER BY n.prop DESC` - Sort descending
626
+ - `LIMIT 10` - Limit results
627
+ - `SKIP 5` - Skip first N results"""
628
+
629
+
630
+ _SPARQL_SYNTAX_GUIDE = """## SPARQL Syntax Reference
631
+
632
+ ### Basic Pattern
633
+ - `SELECT ?var WHERE { ?s ?p ?o }` - Triple pattern
634
+ - `?s a :Label` - Type filter (shorthand for rdf:type)
635
+
636
+ ### Filtering
637
+ - `FILTER(?x > 10)` - Value filter
638
+ - `FILTER(regex(?name, "^A"))` - Regex match
639
+
640
+ ### Aggregation
641
+ - `SELECT (COUNT(?x) AS ?n) WHERE {...}`
642
+ - `GROUP BY ?label`
643
+
644
+ ### Ordering and Limiting
645
+ - `ORDER BY DESC(?x)`
646
+ - `LIMIT 10` / `OFFSET 5`"""
647
+
648
+
649
+ def _syntax_guide(language: str) -> str:
650
+ key = language.lower()
651
+ if key == "sparql":
652
+ return _SPARQL_SYNTAX_GUIDE
653
+ return _CYPHER_SYNTAX_GUIDE
654
+
655
+
656
+ def _nli_instructions(language: str) -> str:
657
+ lang_upper = language.upper()
658
+ return f"""## Instructions
659
+
660
+ 1. Analyze the user's question to understand what data they want
661
+ 2. Generate a valid {lang_upper} query that answers their question
662
+ 3. Use only the node labels, relationship types, and properties defined in the schema
663
+ 4. If the question cannot be answered with the available schema, explain why
664
+
665
+ ## Response Format
666
+
667
+ Respond with ONLY the query, no explanation. The query should be executable as-is.
668
+ If you need to explain something, prefix it with "-- " (comment).
669
+
670
+ Example response:
671
+ MATCH (p:Person) WHERE p.age > 30 RETURN p.name, p.age ORDER BY p.age DESC LIMIT 10
672
+ """
673
+
674
+
675
+ def _agent_instructions(language: str) -> str:
676
+ lang_upper = language.upper()
677
+ return f"""## Instructions
678
+
679
+ You are an agent with access to tools that can execute {lang_upper} queries against
680
+ the graph described above. When the user asks a data question:
681
+
682
+ 1. Decide which tool(s) to call and with what {lang_upper} query
683
+ 2. Use only the node labels, relationship types, and properties defined in the schema
684
+ 3. If the question cannot be answered with the available schema, say so
685
+ 4. Explain the result in natural language after the tool returns
686
+
687
+ You may call multiple tools, refine queries based on intermediate results, and
688
+ combine query results with other reasoning.
689
+ """
690
+
691
+
692
+ def _explainer_instructions(language: str) -> str:
693
+ lang_upper = language.upper()
694
+ return f"""## Instructions
695
+
696
+ Given a {lang_upper} query and its results below, explain in plain language what
697
+ the query asks and what the results mean. Reference specific labels, relationship
698
+ types, and properties from the schema. Do not generate new queries.
699
+ """
700
+
701
+
702
+ def render_prompt(
703
+ desc: SchemaDescriptor,
704
+ *,
705
+ language: str = "sparql",
706
+ role: Role = "agent",
707
+ examples: Optional[str] = None,
708
+ ) -> str:
709
+ """Render an opinionated system prompt with schema context.
710
+
711
+ ``role`` controls the instructions block:
712
+ - ``"nli"``: bare-query mode; the model returns only the query string.
713
+ Matches the legacy ``SchemaContextBuilder.build_system_prompt``.
714
+ - ``"agent"``: tool-using mode; the model is told it has tools and may
715
+ converse around results.
716
+ - ``"explainer"``: post-hoc mode, model explains an existing query/result.
717
+
718
+ ``examples`` is an optional pre-formatted examples block (see
719
+ ``prograph.schema.examples.render_examples``); it is inserted between the
720
+ schema description and the instructions if provided.
721
+ """
722
+ lang_lower = language.lower()
723
+ schema_desc = render_markdown(desc)
724
+ syntax = _syntax_guide(lang_lower)
725
+
726
+ if role == "nli":
727
+ instructions = _nli_instructions(lang_lower)
728
+ header = (
729
+ f"You are a graph database query assistant. Your task is to convert "
730
+ f"natural language questions into {lang_lower.upper()} queries."
731
+ )
732
+ elif role == "explainer":
733
+ instructions = _explainer_instructions(lang_lower)
734
+ header = (
735
+ f"You are a graph database query explainer. The graph below has the "
736
+ f"following schema."
737
+ )
738
+ else:
739
+ instructions = _agent_instructions(lang_lower)
740
+ header = (
741
+ f"You are an agent with access to a graph database. The graph has the "
742
+ f"following schema."
743
+ )
744
+
745
+ parts = [header, "", schema_desc, "", syntax]
746
+ if examples:
747
+ parts.extend(["", examples])
748
+ parts.extend(["", instructions])
749
+ return "\n".join(parts).strip()
750
+
751
+
752
+ __all__ = [
753
+ "PropertyDescriptor",
754
+ "NodeDescriptor",
755
+ "RelationshipDescriptor",
756
+ "PredicateDescriptor",
757
+ "SchemaDescriptor",
758
+ "describe_schema",
759
+ "render_markdown",
760
+ "render_compact",
761
+ "render_prompt",
762
+ "SUPPORTED_LANGUAGES",
763
+ ]
764
+
765
+
766
+ def shape_classes(maps) -> Dict[Any, Tuple[str, ...]]:
767
+ """For the schema description only: the classes an IRI of each template shape (`template_shape`:
768
+ one fixed text, the columns aside, so one IRI) is described with, where that is unambiguous: the
769
+ classed maps of that subject shape all state the same classes and none reads a query or a filter
770
+ (a subset of rows). Any other shape: no entry (described as `any`)."""
771
+ from prograph.plan.ir.slot import template_shape
772
+ seen: Dict[Any, set] = {}
773
+ partial = set()
774
+ for m in maps.nodes:
775
+ if not m.classes or m.subject.template is None:
776
+ continue
777
+ shape = template_shape(m.subject)
778
+ seen.setdefault(shape, set()).add(tuple(m.classes))
779
+ if m.source.query is not None or m.source.filter:
780
+ partial.add(shape)
781
+ return {shape: next(iter(sets)) for shape, sets in seen.items() if len(sets) == 1 and shape not in partial}
782
+
783
+
784
+ def _vocabulary_of_maps(schema: "GraphSchema") -> VocabularyDescriptor:
785
+ """An R2RML mapping's vocabulary from its source maps: the classes and predicates it states, by
786
+ IRI, a class's label its IRI (no invented label), a predicate's subject and object classes those
787
+ of the maps that give it. A map that states no class (a link's own triples map, `<#L_HAS_SUPPLIER>`)
788
+ is described with the classes its IRI shape implies (`shape_classes`): guidance for a query writer
789
+ only; the plan never reads it, and no class is invented for planning or answers."""
790
+ from prograph.plan.ir.slot import template_shape
791
+ from prograph.schema import xsd
792
+ from prograph.schema.source_map import IRI, LITERAL
793
+ maps = schema.source_maps()
794
+ by_shape = shape_classes(maps)
795
+
796
+ def classes_of_term(tm) -> List[str]:
797
+ return list(by_shape.get(template_shape(tm), ())) if tm.template is not None else []
798
+ classes, seen = [], set()
799
+ for m in maps.nodes:
800
+ for c in m.classes:
801
+ if c not in seen:
802
+ seen.add(c)
803
+ classes.append(ClassDescriptor(iri=c, label=c, individuals=m.subject.text()))
804
+ terms: Dict[str, Dict[str, Any]] = {}
805
+
806
+ def add(iri, kind, subjects, datatype=None, objects=()):
807
+ term = terms.setdefault(iri, {"kind": kind, "subjects": [], "datatype": datatype, "objects": []})
808
+ for c in subjects:
809
+ if c not in term["subjects"]:
810
+ term["subjects"].append(c)
811
+ for c in objects:
812
+ if c not in term["objects"]:
813
+ term["objects"].append(c)
814
+ if term["datatype"] is None:
815
+ term["datatype"] = datatype
816
+
817
+ for m in maps.nodes:
818
+ subjects = m.classes or classes_of_term(m.subject)
819
+ for po in m.predicate_objects:
820
+ if po.predicate is None:
821
+ continue
822
+ tm = po.object
823
+ if tm.term_type == LITERAL:
824
+ datatype = tm.datatype
825
+ if datatype is None and tm.language is None and tm.column is not None:
826
+ datatype = xsd.datatype_of_type(schema.table_column_type(m.source.table, tm.column))
827
+ add(po.predicate, "datatype", subjects, datatype)
828
+ else:
829
+ add(po.predicate, "object", subjects, objects=classes_of_term(tm) if tm.term_type == IRI else ())
830
+
831
+ def classes_of(ref):
832
+ node = maps.node(ref.map_id) if ref.map_id else None
833
+ if node is not None and node.classes:
834
+ return node.classes
835
+ # An end in a map that states no class (an R2RML link's own triples map): the classes of its
836
+ # term's template shape.
837
+ return classes_of_term(ref.term) if getattr(ref, "term", None) is not None else ()
838
+
839
+ for e in maps.edges:
840
+ if e.predicate is not None:
841
+ add(e.predicate, "object", classes_of(e.start), objects=classes_of(e.end))
842
+ predicates = [TermDescriptor(iri=k, kind=v["kind"], subject_classes=v["subjects"],
843
+ datatype=v["datatype"], object_classes=v["objects"])
844
+ for k, v in terms.items()]
845
+ return VocabularyDescriptor(prefixes=dict(schema.prefixes or {}), classes=classes, predicates=predicates)