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,414 @@
|
|
|
1
|
+
"""Dataclass types for the Genie integration.
|
|
2
|
+
|
|
3
|
+
Defines the contract between the view generator, the instruction
|
|
4
|
+
generator, the sample-query generator, the Space emitter, and the
|
|
5
|
+
CLI. Every later module produces or consumes these types.
|
|
6
|
+
|
|
7
|
+
Design principles:
|
|
8
|
+
|
|
9
|
+
- **Frozen**, once produced, an artifact doesn't change. Generators
|
|
10
|
+
rebuild from scratch; callers don't mutate. Mutation would imply
|
|
11
|
+
the artifact has a lifecycle separate from the schema it came from.
|
|
12
|
+
- **JSON-serializable**, every type roundtrips through dict/JSON via
|
|
13
|
+
``to_dict``/``from_dict``. The Space emitter writes YAML; YAML is
|
|
14
|
+
JSON-compatible structured data.
|
|
15
|
+
- **No engine references**. These types describe outputs, not
|
|
16
|
+
inputs. They don't carry pointers to ``ProGraph`` instances,
|
|
17
|
+
connections, or schemas. That keeps them serializable and
|
|
18
|
+
diff-friendly.
|
|
19
|
+
|
|
20
|
+
See ``docs/guides/genie.md`` for the user-facing workflow.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
from dataclasses import asdict, dataclass, field
|
|
26
|
+
from enum import Enum
|
|
27
|
+
from typing import Any, Dict, List, Optional
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
# ─── View definitions ────────────────────────────────────────────────
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class ViewSource(str, Enum):
|
|
34
|
+
"""Where a generated view came from.
|
|
35
|
+
|
|
36
|
+
Decision 3 in the Genie integration spike enumerates the four
|
|
37
|
+
sources of views (subclass closure, OWL defined class, SHACL
|
|
38
|
+
violation, metric). The fifth value ``SCHEMA_LABEL`` covers the
|
|
39
|
+
trivial "one view per node label" case the view generator emits
|
|
40
|
+
by default.
|
|
41
|
+
|
|
42
|
+
The enum is a ``str`` subclass so ``ViewSource.OWL_DEFINED_CLASS ==
|
|
43
|
+
"owl_defined_class"`` is True, convenient for JSON serialization
|
|
44
|
+
and equality checks.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
SCHEMA_LABEL = "schema_label"
|
|
48
|
+
"""A view projecting one NodeMapping's rows. Trivial case."""
|
|
49
|
+
|
|
50
|
+
SUBCLASS_CLOSURE = "subclass_closure"
|
|
51
|
+
"""A view unioning all subclasses of a parent label."""
|
|
52
|
+
|
|
53
|
+
OWL_DEFINED_CLASS = "owl_defined_class"
|
|
54
|
+
"""A view projecting an OWL-entailed class (RL+ restriction)."""
|
|
55
|
+
|
|
56
|
+
SHACL_VIOLATION = "shacl_violation"
|
|
57
|
+
"""A view exposing the latest SHACL run's violations."""
|
|
58
|
+
|
|
59
|
+
METRIC = "metric"
|
|
60
|
+
"""An aggregation view (Phase 5 measure/dimension; placeholder)."""
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass(frozen=True)
|
|
64
|
+
class ViewDefinition:
|
|
65
|
+
"""A single generated SQL view.
|
|
66
|
+
|
|
67
|
+
Carries the SQL needed to ``CREATE OR REPLACE VIEW`` it plus the
|
|
68
|
+
provenance to know where the definition came from.
|
|
69
|
+
|
|
70
|
+
The ``sql`` field is the bare SELECT body, callers
|
|
71
|
+
(e.g. ``view_writer.py``) wrap it in ``CREATE OR REPLACE VIEW
|
|
72
|
+
{namespace}.{name} AS {sql}`` for the target dialect.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
name: str
|
|
76
|
+
"""The view's local name (no schema/catalog prefix).
|
|
77
|
+
|
|
78
|
+
Conventionally ``snake_case``; the namespace prefix is added at
|
|
79
|
+
write time so the same ``ViewDefinition`` works against Databricks
|
|
80
|
+
SQL (``catalog.schema.name``), Postgres (``schema.name``), or
|
|
81
|
+
DuckDB (``name``).
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
sql: str
|
|
85
|
+
"""The SELECT body that defines the view.
|
|
86
|
+
|
|
87
|
+
Does **not** include the ``CREATE OR REPLACE VIEW {fqn} AS``
|
|
88
|
+
wrapper, that's the writer's job. Leaving it off lets the same
|
|
89
|
+
definition emit to different dialects with different quoting
|
|
90
|
+
rules.
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
source: ViewSource
|
|
94
|
+
"""Which kind of source produced this view.
|
|
95
|
+
|
|
96
|
+
Used by the Space emitter to group views in instructions ("OWL-
|
|
97
|
+
inferred classes:" vs "Data-quality views:") and by the writer
|
|
98
|
+
to decide ordering (closure views before defined-class views,
|
|
99
|
+
etc.).
|
|
100
|
+
"""
|
|
101
|
+
|
|
102
|
+
description: str = ""
|
|
103
|
+
"""Human-readable summary. Goes into the SQL ``COMMENT`` and into
|
|
104
|
+
Genie Space instructions. One sentence; no trailing period
|
|
105
|
+
required.
|
|
106
|
+
"""
|
|
107
|
+
|
|
108
|
+
source_label: Optional[str] = None
|
|
109
|
+
"""For label-derived views (``SCHEMA_LABEL``, ``SUBCLASS_CLOSURE``,
|
|
110
|
+
``OWL_DEFINED_CLASS``), the originating label. ``None`` for
|
|
111
|
+
others.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
source_shape_iri: Optional[str] = None
|
|
115
|
+
"""For ``SHACL_VIOLATION`` views, the SHACL shape IRI. ``None``
|
|
116
|
+
otherwise."""
|
|
117
|
+
|
|
118
|
+
source_metric_name: Optional[str] = None
|
|
119
|
+
"""For ``METRIC`` views, the metric definition name. ``None``
|
|
120
|
+
otherwise."""
|
|
121
|
+
|
|
122
|
+
columns: List[str] = field(default_factory=list)
|
|
123
|
+
"""The view's projected columns, in order. Lets callers introspect
|
|
124
|
+
without parsing the SQL. Optional: if empty, the writer can
|
|
125
|
+
leave column comments off."""
|
|
126
|
+
|
|
127
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
128
|
+
d = asdict(self)
|
|
129
|
+
# Normalize the enum to its string value for JSON.
|
|
130
|
+
d["source"] = self.source.value
|
|
131
|
+
return d
|
|
132
|
+
|
|
133
|
+
@classmethod
|
|
134
|
+
def from_dict(cls, data: Dict[str, Any]) -> "ViewDefinition":
|
|
135
|
+
kwargs = dict(data)
|
|
136
|
+
kwargs["source"] = ViewSource(kwargs["source"])
|
|
137
|
+
return cls(**kwargs)
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
# ─── Sample queries ──────────────────────────────────────────────────
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
@dataclass(frozen=True)
|
|
144
|
+
class SampleQuery:
|
|
145
|
+
"""A natural-language question paired with its expected SQL.
|
|
146
|
+
|
|
147
|
+
Genie uses these as few-shot examples when reasoning about how to
|
|
148
|
+
answer user questions. The generator (W4) produces 10-30 of these
|
|
149
|
+
per schema, covering common patterns over each generated view.
|
|
150
|
+
"""
|
|
151
|
+
|
|
152
|
+
question: str
|
|
153
|
+
"""The natural-language question Genie should learn to answer.
|
|
154
|
+
|
|
155
|
+
Written in the voice of a real user: "Which components are at
|
|
156
|
+
high wear risk?" not "Project the OWL-entailed
|
|
157
|
+
:HighWearComponent class."
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
sql: str
|
|
161
|
+
"""The expected SQL answer.
|
|
162
|
+
|
|
163
|
+
Should reference generated views (``prograph_views.*``) where
|
|
164
|
+
appropriate, so Genie learns to use them rather than rolling its
|
|
165
|
+
own filters over the base tables.
|
|
166
|
+
"""
|
|
167
|
+
|
|
168
|
+
description: str = ""
|
|
169
|
+
"""Optional context for the Genie operator who reviews these
|
|
170
|
+
samples. Not consumed by Genie itself."""
|
|
171
|
+
|
|
172
|
+
tags: List[str] = field(default_factory=list)
|
|
173
|
+
"""Optional taxonomy for filtering/grouping (e.g. ``["high-wear",
|
|
174
|
+
"maintenance"]``). The Space emitter can use these to organize
|
|
175
|
+
the sample-query list."""
|
|
176
|
+
|
|
177
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
178
|
+
return asdict(self)
|
|
179
|
+
|
|
180
|
+
@classmethod
|
|
181
|
+
def from_dict(cls, data: Dict[str, Any]) -> "SampleQuery":
|
|
182
|
+
return cls(**data)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
# ─── Instructions ────────────────────────────────────────────────────
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
@dataclass(frozen=True)
|
|
189
|
+
class InstructionsSection:
|
|
190
|
+
"""One section of the auto-generated instructions doc.
|
|
191
|
+
|
|
192
|
+
Genie's instructions field accepts a single text blob; we model it
|
|
193
|
+
as sections internally so different generators can contribute
|
|
194
|
+
pieces independently and the assembler can order them sensibly.
|
|
195
|
+
"""
|
|
196
|
+
|
|
197
|
+
heading: str
|
|
198
|
+
"""Section heading, e.g. ``"Entities"``, ``"Relationships"``,
|
|
199
|
+
``"Defined Classes"``, ``"Data Quality"``."""
|
|
200
|
+
|
|
201
|
+
body: str
|
|
202
|
+
"""Markdown-formatted body. Will be rendered verbatim into the
|
|
203
|
+
Genie Space's instructions field. Length: a paragraph to a few
|
|
204
|
+
paragraphs; the assembler caps the full doc at ~4000 tokens."""
|
|
205
|
+
|
|
206
|
+
order: int = 0
|
|
207
|
+
"""Sort key for ordering sections in the final doc. Lower goes
|
|
208
|
+
first. Conventional values:
|
|
209
|
+
|
|
210
|
+
- 10: introduction / overview
|
|
211
|
+
- 20: entities (node labels)
|
|
212
|
+
- 30: relationships
|
|
213
|
+
- 40: subclass / type hierarchies
|
|
214
|
+
- 50: OWL-defined classes
|
|
215
|
+
- 60: SHACL constraints / data quality
|
|
216
|
+
- 70: metrics (Phase 5)
|
|
217
|
+
- 80: example query patterns
|
|
218
|
+
- 90: glossary / terms
|
|
219
|
+
"""
|
|
220
|
+
|
|
221
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
222
|
+
return asdict(self)
|
|
223
|
+
|
|
224
|
+
@classmethod
|
|
225
|
+
def from_dict(cls, data: Dict[str, Any]) -> "InstructionsSection":
|
|
226
|
+
return cls(**data)
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
@dataclass(frozen=True)
|
|
230
|
+
class InstructionsDoc:
|
|
231
|
+
"""The full set of instructions for one Genie Space.
|
|
232
|
+
|
|
233
|
+
Composed of sections (independent generators contribute their own)
|
|
234
|
+
plus a final assembled body. The Space emitter consumes
|
|
235
|
+
``rendered`` for the actual Genie Space configuration; the
|
|
236
|
+
sections are kept around for round-tripping and user editing.
|
|
237
|
+
"""
|
|
238
|
+
|
|
239
|
+
sections: List[InstructionsSection] = field(default_factory=list)
|
|
240
|
+
"""The component sections, in arbitrary order. The assembler
|
|
241
|
+
sorts by ``section.order`` before rendering."""
|
|
242
|
+
|
|
243
|
+
rendered: str = ""
|
|
244
|
+
"""The fully-assembled markdown body, sections ordered and
|
|
245
|
+
concatenated with ``\\n\\n`` separators. Truncated at the
|
|
246
|
+
configured token budget (default ~4000 Genie tokens, set by the
|
|
247
|
+
assembler). This is what goes into the Genie Space."""
|
|
248
|
+
|
|
249
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
250
|
+
return {
|
|
251
|
+
"sections": [s.to_dict() for s in self.sections],
|
|
252
|
+
"rendered": self.rendered,
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
@classmethod
|
|
256
|
+
def from_dict(cls, data: Dict[str, Any]) -> "InstructionsDoc":
|
|
257
|
+
return cls(
|
|
258
|
+
sections=[InstructionsSection.from_dict(s) for s in data["sections"]],
|
|
259
|
+
rendered=data.get("rendered", ""),
|
|
260
|
+
)
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
# ─── MCP server registration ─────────────────────────────────────────
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
@dataclass(frozen=True)
|
|
267
|
+
class McpServerRegistration:
|
|
268
|
+
"""Registration of an MCP server in a Genie Space.
|
|
269
|
+
|
|
270
|
+
Path B from the spike: the existing ProGraph MCP server registered
|
|
271
|
+
so Genie can call it as an escape hatch for graph-shaped queries.
|
|
272
|
+
|
|
273
|
+
Authentication is described, not stored: this dataclass carries
|
|
274
|
+
the *method* (``"databricks_pat"``, ``"oauth"``, etc.); the actual
|
|
275
|
+
secret is supplied separately at Space-import time.
|
|
276
|
+
"""
|
|
277
|
+
|
|
278
|
+
name: str
|
|
279
|
+
"""Identifier Genie uses to reference the server.
|
|
280
|
+
Conventionally ``"prograph"`` for the primary registration; if
|
|
281
|
+
multiple ProGraph engines are registered, use
|
|
282
|
+
``"prograph_<domain>"`` (e.g. ``"prograph_turbofan"``)."""
|
|
283
|
+
|
|
284
|
+
endpoint: str
|
|
285
|
+
"""The MCP server's URL or local invocation. URL for hosted
|
|
286
|
+
deployments; for local-stdio deployments, the equivalent
|
|
287
|
+
command string."""
|
|
288
|
+
|
|
289
|
+
description: str = ""
|
|
290
|
+
"""Human-readable purpose. Genie's tool-selection reasoning reads
|
|
291
|
+
this; phrase it for the model that has to decide whether to call
|
|
292
|
+
this server vs. answer with SQL."""
|
|
293
|
+
|
|
294
|
+
auth_method: str = "databricks_pat"
|
|
295
|
+
"""How Genie authenticates. ``"databricks_pat"`` (default),
|
|
296
|
+
``"oauth"``, ``"service_principal"``, or ``"none"`` for local
|
|
297
|
+
deployments without auth.
|
|
298
|
+
|
|
299
|
+
The actual secret is supplied at import time; this field only
|
|
300
|
+
documents the expected method.
|
|
301
|
+
"""
|
|
302
|
+
|
|
303
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
304
|
+
return asdict(self)
|
|
305
|
+
|
|
306
|
+
@classmethod
|
|
307
|
+
def from_dict(cls, data: Dict[str, Any]) -> "McpServerRegistration":
|
|
308
|
+
return cls(**data)
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
# ─── Genie Space ─────────────────────────────────────────────────────
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
@dataclass(frozen=True)
|
|
315
|
+
class GenieSpace:
|
|
316
|
+
"""A complete Genie Space configuration.
|
|
317
|
+
|
|
318
|
+
The output of ``prograph emit-genie-space``. Serializes to the
|
|
319
|
+
YAML/JSON shape Databricks Genie consumes natively. Decision 7 in
|
|
320
|
+
the spike commits to emitting Genie's documented format rather
|
|
321
|
+
than inventing our own.
|
|
322
|
+
|
|
323
|
+
Fields beyond the Genie-required minimum (``tables``, ``instructions``,
|
|
324
|
+
``sample_queries``) are namespaced under ``metadata`` to avoid
|
|
325
|
+
collisions with future Databricks-side schema additions.
|
|
326
|
+
"""
|
|
327
|
+
|
|
328
|
+
name: str
|
|
329
|
+
"""Display name of the Space."""
|
|
330
|
+
|
|
331
|
+
description: str = ""
|
|
332
|
+
"""Short description shown in the Genie UI."""
|
|
333
|
+
|
|
334
|
+
tables: List[str] = field(default_factory=list)
|
|
335
|
+
"""Fully-qualified table names included in the Space.
|
|
336
|
+
|
|
337
|
+
Mix of user tables (``catalog.schema.engines``) and ProGraph-
|
|
338
|
+
generated views (``catalog.prograph_views.high_wear_components``).
|
|
339
|
+
Order doesn't matter to Genie but the emitter conventionally
|
|
340
|
+
lists user tables first, generated views second.
|
|
341
|
+
"""
|
|
342
|
+
|
|
343
|
+
instructions: InstructionsDoc = field(default_factory=InstructionsDoc)
|
|
344
|
+
"""Natural-language instructions. The ``rendered`` field's
|
|
345
|
+
contents go into the Genie Space's instructions slot."""
|
|
346
|
+
|
|
347
|
+
sample_queries: List[SampleQuery] = field(default_factory=list)
|
|
348
|
+
"""Few-shot NL→SQL pairs. Genie consumes these as exemplars."""
|
|
349
|
+
|
|
350
|
+
mcp_servers: List[McpServerRegistration] = field(default_factory=list)
|
|
351
|
+
"""MCP server registrations for the escape-hatch path. Usually
|
|
352
|
+
one (the ProGraph MCP server)."""
|
|
353
|
+
|
|
354
|
+
views: List[ViewDefinition] = field(default_factory=list)
|
|
355
|
+
"""The ProGraph-generated views referenced by this Space.
|
|
356
|
+
|
|
357
|
+
Stored on the Space object so consumers can also issue the
|
|
358
|
+
``CREATE OR REPLACE VIEW`` statements through ``view_writer.py``
|
|
359
|
+
as part of importing the Space. The views are also the
|
|
360
|
+
provenance of the ``catalog.prograph_views.*`` entries in
|
|
361
|
+
``tables``.
|
|
362
|
+
"""
|
|
363
|
+
|
|
364
|
+
metadata: Dict[str, Any] = field(default_factory=dict)
|
|
365
|
+
"""Free-form metadata. Conventional keys:
|
|
366
|
+
|
|
367
|
+
- ``"generated_by"``: ``"prograph"``
|
|
368
|
+
- ``"generated_at"``: ISO-8601 timestamp
|
|
369
|
+
- ``"prograph_version"``: the version that produced this Space
|
|
370
|
+
- ``"source_config"``: path to the ``graph.yaml`` it was emitted from
|
|
371
|
+
"""
|
|
372
|
+
|
|
373
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
374
|
+
return {
|
|
375
|
+
"name": self.name,
|
|
376
|
+
"description": self.description,
|
|
377
|
+
"tables": list(self.tables),
|
|
378
|
+
"instructions": self.instructions.to_dict(),
|
|
379
|
+
"sample_queries": [q.to_dict() for q in self.sample_queries],
|
|
380
|
+
"mcp_servers": [s.to_dict() for s in self.mcp_servers],
|
|
381
|
+
"views": [v.to_dict() for v in self.views],
|
|
382
|
+
"metadata": dict(self.metadata),
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
@classmethod
|
|
386
|
+
def from_dict(cls, data: Dict[str, Any]) -> "GenieSpace":
|
|
387
|
+
return cls(
|
|
388
|
+
name=data["name"],
|
|
389
|
+
description=data.get("description", ""),
|
|
390
|
+
tables=list(data.get("tables", [])),
|
|
391
|
+
instructions=InstructionsDoc.from_dict(
|
|
392
|
+
data.get("instructions", {"sections": [], "rendered": ""})
|
|
393
|
+
),
|
|
394
|
+
sample_queries=[
|
|
395
|
+
SampleQuery.from_dict(q) for q in data.get("sample_queries", [])
|
|
396
|
+
],
|
|
397
|
+
mcp_servers=[
|
|
398
|
+
McpServerRegistration.from_dict(s)
|
|
399
|
+
for s in data.get("mcp_servers", [])
|
|
400
|
+
],
|
|
401
|
+
views=[ViewDefinition.from_dict(v) for v in data.get("views", [])],
|
|
402
|
+
metadata=dict(data.get("metadata", {})),
|
|
403
|
+
)
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
__all__ = [
|
|
407
|
+
"ViewSource",
|
|
408
|
+
"ViewDefinition",
|
|
409
|
+
"SampleQuery",
|
|
410
|
+
"InstructionsSection",
|
|
411
|
+
"InstructionsDoc",
|
|
412
|
+
"McpServerRegistration",
|
|
413
|
+
"GenieSpace",
|
|
414
|
+
]
|