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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- 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)
|