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,14 @@
1
+ """Bundled demos shipped with the prograph package.
2
+
3
+ Demos in this directory are *installable*, their assets (ontologies, PSL
4
+ rules, instance data, query templates) are bundled as package data so
5
+ downstream consumers (proact, prograph-studio) can resolve paths via
6
+ ``importlib.resources`` without copying files.
7
+
8
+ Currently bundled:
9
+ - ``prograph.demos.turbofan``, aircraft engine predictive maintenance.
10
+
11
+ Other demos under the top-level ``demos/`` directory are example scripts
12
+ intended for in-tree execution, not packaging. They graduate here when a
13
+ downstream project needs to consume their assets.
14
+ """
@@ -0,0 +1,74 @@
1
+ # Turbofan Engine Predictive Maintenance Demo
2
+
3
+ The data-layer half of the turbofan demo: an ontology, instance data, PSL rules, SHACL shapes, SPARQL queries and two ProGraph schemas for one aircraft-engine maintenance scenario. The decisions (the maintenance policy, its PSL program, actions and their record) live in the ProAct repository under `examples/turbofan/`. The walkthrough, with the answers each step gives, is [`docs/demos/turbofan.md`](../../../docs/demos/turbofan.md).
4
+
5
+ ## What's here
6
+
7
+ | Path | Purpose |
8
+ |------|---------|
9
+ | [`SCENARIO.md`](SCENARIO.md) | The narrative: ESN-1001 (degrading, desert routes) vs ESN-2001 (healthy baseline), three concurrent degradation chains, closed-loop maintenance story. |
10
+ | [`turbofan_schema.py`](turbofan_schema.py) | ProGraph schema (programmatic). 10 node tables, 51 labels via `filter_predicate` and 2 over a query, 17 relationship types in 17 tables (29 mappings). |
11
+ | [`graph.yaml`](graph.yaml) | Same schema as YAML for `ProGraph.from_config()` (Spark catalog tables). |
12
+ | [`load.py`](load.py) | Loads `data/engine-instances.ttl` into the full schema's 27 tables as DataFrames; `build_engine()` returns a DuckDB engine over them. |
13
+ | [`demo.py`](demo.py) | A six-component schema and data of the scenario (`build_schema()`, `build_dataframes()`). |
14
+ | [`validation_demo.py`](validation_demo.py) | SHACL validation: broken data, fix, conforming data. |
15
+ | [`shapes.ttl`](shapes.ttl) | The two SHACL shapes `validation_demo.py` uses. |
16
+ | [`genie_qa_notebook.py`](genie_qa_notebook.py) | Databricks notebook: the schema seeded into Unity Catalog and queried through a Genie space. |
17
+ | [`create_tables.sql`](create_tables.sql) | DDL for the 27 tables (PostgreSQL dialect; runs on DuckDB as is). |
18
+ | [`ontology/engine-maintenance.ttl`](ontology/engine-maintenance.ttl) | OWL TBox: ~50 classes, transitive/symmetric/inverse properties, property chains, defined classes (`HighWearComponent`, `CriticalPathComponent`, `MonitoredComponent`). |
19
+ | [`data/engine-instances.ttl`](data/engine-instances.ttl) | OWL ABox: two complete engines (ESN-1001 degrading, ESN-2001 baseline), components, sensors, degradation assertions, propagation edges, maintenance history. |
20
+ | [`data/sensor-timeseries.csv`](data/sensor-timeseries.csv) | 12 weeks of weekly sensor readings across both engines for trend ingestion. |
21
+ | [`queries/example-queries.sparql`](queries/example-queries.sparql) | 12 SPARQL queries written against the RDF files (hierarchy traversal, threshold alerts, propagation paths, engine comparison, the PSL-inferred named graph). Not all of them run on ProGraph; [the walkthrough](../../../docs/demos/turbofan.md#the-example-sparql-file) lists which do. |
22
+
23
+ ## Design docs
24
+
25
+ - [`docs/demos/turbofan.md`](../../../docs/demos/turbofan.md): the walkthrough, the answers in each query language, and what does not work yet.
26
+ - [`docs/demos/turbofan-storage.md`](../../../docs/demos/turbofan-storage.md): the table layout, why subtypes share a table, how writes reach it.
27
+ - [`docs/architecture/w3c.md`](../../../docs/architecture/w3c.md): the W3C/OWL/SHACL plan this demo exercises.
28
+
29
+ ## Two inference layers
30
+
31
+ | Layer | Technology | Role |
32
+ |-------|-----------|------|
33
+ | **Deductive** | OWL 2 RL | The ontology is an OWL 2 RL ontology, read under `profile="rl"` with an owned store ([OWL 2 RL](../../../docs/reference/owl-rl.md)): the class hierarchy, sub-properties, domains and ranges are rewrites, and the transitive, symmetric and inverse properties, the property chains and `MonitoredComponent` are materialized (`tables.rl_engine()`). `HighWearComponent` and `CriticalPathComponent` are the mapping's queries. |
34
+ | **Probabilistic** | PSL | Soft weighted rules. Infers graded beliefs about degradation, failure probability, health states, RUL, and maintenance urgency from sensor data + graph topology. |
35
+
36
+ PSL inference runs in ProAct (`prograph.psl` is not in 1.0); the maintenance program that scores components is ProAct's. ProAct mutates the graph when maintenance is performed (wear indices, health states, cycle counters) and re-runs PSL inference.
37
+
38
+ ## OWL feature requirements
39
+
40
+ `engine-maintenance.ttl` is an OWL 2 RL ontology: transitive properties, property chains and functional properties are OWL 2 RL's and not OWL 2 QL's, so every demo engine that reads it uses `profile="rl"`; under `profile="ql"` the engine refuses it, naming each axiom (`docs/demos/turbofan.md` shows the error). `MonitoredComponent` is the half of its definition OWL 2 RL has: a component a sensor monitors is one. `HighWearComponent` (a wear index of 0.7 or more) and `CriticalPathComponent` (degradation propagating to two things or more) need a datatype restriction and a minimum cardinality, which neither OWL 2 profile has: the ontology states them as subclasses of `Component`, and the mapping gives their members as queries, which SQL answers.
41
+
42
+ ## Run the demo
43
+
44
+ The six-component schema and data of `demo.py`, as DuckDB tables, with the ontology under `profile="rl"` and an owned store:
45
+
46
+ ```python
47
+ from prograph.demos.turbofan.demo import rl_engine
48
+
49
+ engine = rl_engine()
50
+ ```
51
+
52
+ SHACL validation, before and after a data fix:
53
+
54
+ ```bash
55
+ python -m prograph.demos.turbofan.validation_demo
56
+ ```
57
+
58
+ The full schema over the full instance data, on DuckDB:
59
+
60
+ ```python
61
+ from prograph.demos.turbofan.load import build_engine
62
+
63
+ engine = build_engine()
64
+ engine.execute("""
65
+ PREFIX : <http://example.org/engine-maintenance#>
66
+ SELECT ?c WHERE { ?c a :Component ; :wearIndex ?w FILTER(?w >= 0.7) }
67
+ """, return_type="list")
68
+ ```
69
+
70
+ ## Requirements
71
+
72
+ ```bash
73
+ pip install -e ".[duckdb,ontology,shacl]" # DuckDB engine, rdflib, pyshacl
74
+ ```
@@ -0,0 +1,209 @@
1
+ # Aircraft Engine Predictive Maintenance: Demo Scenario
2
+
3
+ ## Overview
4
+
5
+ This demo models a **turbofan jet engine** (loosely based on CFM56-class architecture) as a deeply nested part-whole graph, instrumented with sensors whose readings drive **two layers of inference**:
6
+
7
+ | Layer | Technology | Role |
8
+ |-------|-----------|------|
9
+ | **Deductive** | OWL (ProGraph: OWL 2 RL) | Class hierarchy, property chains, defined classes. Infers structural relationships (transitive `isPartOf`), auto-classifies `HighWearComponent`, propagates `monitors` through the part hierarchy. |
10
+ | **Probabilistic** | PSL | Soft weighted rules. Infers graded beliefs about degradation, failure probability, health states, remaining useful life, and maintenance urgency from sensor data + graph topology. |
11
+
12
+ The **virtual graph layer** materializes inferred triples (from both OWL and PSL) alongside asserted data, and the **action layer** closes the loop by mutating the graph when maintenance is performed (updating wear indices, health states, and cycle counters).
13
+
14
+ ---
15
+
16
+ ## Scenario Narrative
17
+
18
+ **Acme Airlines** operates a small fleet. Engine **ESN-1001**, installed on aircraft N701AA, has been flying **desert routes** for 18,200 cycles (27,300 hours). It was last overhauled ~6,100 cycles ago.
19
+
20
+ Over the past 12 weeks, multiple sensor trends have been developing **concurrently**:
21
+
22
+ ### Active Degradation Chains
23
+
24
+ ```
25
+ ┌─────────────────────────────────────────────────────────────────────┐
26
+ │ CHAIN 1: Bearing Wear Cascade │
27
+ │ │
28
+ │ No.3 Bearing (wear 0.82) ──propagatesTo──► HP Shaft │
29
+ │ │ Mid Bearing Seal │
30
+ │ │ │ │
31
+ │ ▼ ▼ │
32
+ │ ↑ Vibration (3.8 mm/s) Seal Leakage │
33
+ │ ↑ Oil debris (28 ppm) │ │
34
+ │ ▼ │
35
+ │ Oil System │
36
+ │ ↑ Oil temp (138°C) │
37
+ └─────────────────────────────────────────────────────────────────────┘
38
+
39
+ ┌─────────────────────────────────────────────────────────────────────┐
40
+ │ CHAIN 2: Hot Section Cascade │
41
+ │ │
42
+ │ Fuel Nozzle #3 (carbon) ──propagatesTo──► Combustor Liner (carbon) │
43
+ │ │ │
44
+ │ ▼ │
45
+ │ HPT Stage 1 Blades (thermal) │
46
+ │ wear 0.78 │ RUL 1,800 cycles │
47
+ │ │ │
48
+ │ ▼ │
49
+ │ HPT Stage 1 Disk (fatigue risk) │
50
+ │ │
51
+ │ Sensor evidence: EGT 649°C (↑31° in 12 weeks, above nominal max) │
52
+ └─────────────────────────────────────────────────────────────────────┘
53
+
54
+ ┌─────────────────────────────────────────────────────────────────────┐
55
+ │ CHAIN 3: Compressor Erosion (desert environment) │
56
+ │ │
57
+ │ HPC Stage 5 Blades (erosion, wear 0.72) │
58
+ │ │ │
59
+ │ ▼ │
60
+ │ HPC Stage 5 Disk (fatigue risk from blade imbalance) │
61
+ │ │
62
+ │ Sensor evidence: HPC pressure ratio 21.3 (was 25.8, declining) │
63
+ │ HPC vibration 4.2 mm/s (crossed caution @ 4.0) │
64
+ └─────────────────────────────────────────────────────────────────────┘
65
+ ```
66
+
67
+ Meanwhile, engine **ESN-2001** (temperate routes, 8,400 cycles) serves as a **healthy baseline**, with all sensors flat and nominal.
68
+
69
+ ---
70
+
71
+ ## What the Inference Layers Produce
72
+
73
+ ### OWL Reasoning (Deductive)
74
+
75
+ Given the ontology + instance data, an OWL DL reasoner will infer:
76
+
77
+ 1. **Transitive part-of**: `hpc-blade-1001-stg5 isPartOf engine-1001` (through HPC module)
78
+ 2. **Property chain, sensor monitoring**: `sensor-hpc-vib monitors engine-1001` (via `monitors ∘ isPartOf`)
79
+ 3. **Defined class membership** (over `data/engine-instances.ttl`):
80
+ - `bearing-1001-mid` → `HighWearComponent` (wearIndex 0.82 ≥ 0.7)
81
+ - `hpt-blade-1001-stg1` → `HighWearComponent` (wearIndex 0.78 ≥ 0.7)
82
+ - `hpc-blade-1001-stg5` → `HighWearComponent` (wearIndex 0.72 ≥ 0.7)
83
+ - `fuel-nozzle-1001-03` → `HighWearComponent` (wearIndex 0.70 ≥ 0.7)
84
+ - `bearing-1001-mid` → `CriticalPathComponent` (propagatesTo 2 targets: HP shaft, mid seal)
85
+ - `bearing-1001-fwd` → `CriticalPathComponent` (propagatesTo 2 targets: HP shaft, forward seal)
86
+ - `bearing-1001-mid`, `bearing-1001-fwd` → `MonitoredComponent` (a sensor monitors each)
87
+
88
+ `demo.py` runs these definitions on a six-component excerpt, which gives 3, 1 and 2 members.
89
+ 4. **Inverse property**: `hp-shaft-1001 receivesDriveFrom hpt-1001`
90
+
91
+ ### PSL Reasoning (Probabilistic)
92
+
93
+ The PSL rules produce soft truth values (0.0–1.0) for target predicates:
94
+
95
+ | Component | Health State | Failure Prob | Maint. Urgency | Recommended Action |
96
+ |-----------|-------------|-------------|----------------|-------------------|
97
+ | No.3 Bearing | **Warning** (high confidence) | **High** | **Immediate** | Replacement |
98
+ | HPT Stg1 Blades | **Warning** | **High** (cascade from fuel nozzle→combustor→HPT) | **Soon → Immediate** | Shop visit |
99
+ | HPC Stg5 Blades | **Advisory** | **High** (erosion + pressure ratio drop) | **Soon** | Boroscope → blend repair |
100
+ | Mid Bearing Seal | **Watch → Advisory** | Medium | **Soon** | Inspect → replace |
101
+ | Fuel Nozzle #3 | **Advisory** | Medium | **Soon** | Replacement |
102
+ | Combustor Liner | **Watch → Advisory** | Medium (propagation target) | **Scheduled** | Boroscope |
103
+ | HPC Stg9 Blades | **Watch** | Low-Medium | **Monitor** | Continue trending |
104
+ | Fwd Bearing | **Watch** | Low-Medium | **Monitor** | Oil analysis |
105
+
106
+ The PSL rules also flag **fleet-level correlation**: since ESN-1001 shows erosion in a desert environment, other fleet engines operating in similar conditions (if any) get a soft prior boost for erosion susceptibility.
107
+
108
+ ---
109
+
110
+ ## Closed-Loop Graph Mutation (Action Layer)
111
+
112
+ When maintenance is performed, the action layer mutates the graph:
113
+
114
+ ```
115
+ TRIGGER: maintenanceUrgency(bearing-1001-mid, "immediate")
116
+ ACTION: Perform Replacement
117
+ MUTATIONS:
118
+ - DELETE inst:bearing-1001-mid :wearIndex 0.82
119
+ - INSERT inst:bearing-1001-mid :wearIndex 0.0
120
+ - DELETE inst:bearing-1001-mid :hasHealthState [ a :Warning ]
121
+ - INSERT inst:bearing-1001-mid :hasHealthState [ a :Normal ]
122
+ - DELETE inst:bearing-1001-mid :exhibitsDegradation inst:degradation-wear
123
+ - DELETE inst:bearing-1001-mid :cyclesSinceLastOverhaul 6100
124
+ - INSERT inst:bearing-1001-mid :cyclesSinceLastOverhaul 0
125
+ - INSERT inst:maint-005 a :Replacement ;
126
+ :performedOn inst:bearing-1001-mid ;
127
+ :maintenanceDate "2026-02-13" ;
128
+ :addressesDegradation inst:degradation-wear .
129
+ ```
130
+
131
+ After mutation, PSL re-infers: the bearing's failure probability drops, which **lowers** the propagated risk to HP shaft and mid seal, potentially downgrading their urgency as well.
132
+
133
+ ---
134
+
135
+ ## File Inventory
136
+
137
+ The files of this directory are listed in [README.md](README.md).
138
+
139
+ ---
140
+
141
+ ## Integration Points
142
+
143
+ ### Grounding PSL from the Graph
144
+
145
+ PSL predicates are grounded from queries against the graph. The SPARQL below runs on ProGraph as written: with the ontology attached its triples are in the default graph, so `a/rdfs:subClassOf*` walks the class hierarchy, and the path gives one row per type of `?c` under `:Component` (use `SELECT DISTINCT` for one row per component). `?c a :Component` alone already matches every subclass.
146
+
147
+ ```sparql
148
+ # Ground: wearIndex(Component, Value)
149
+ SELECT ?c ?w WHERE {
150
+ ?c a/rdfs:subClassOf* :Component .
151
+ ?c :wearIndex ?w .
152
+ }
153
+
154
+ # Ground: sensorExceedsThreshold(Sensor, Level)
155
+ SELECT ?s "caution" WHERE {
156
+ ?s a/rdfs:subClassOf* :Sensor .
157
+ ?s :hasReading ?r .
158
+ ?r :readingValue ?v .
159
+ ?s :cautionThreshold ?t .
160
+ FILTER(?v > ?t)
161
+ }
162
+
163
+ # Ground: propagatesTo(A, B)
164
+ SELECT ?a ?b WHERE { ?a :propagatesTo ?b }
165
+
166
+ # Ground: monitors(Sensor, Component) : includes OWL-inferred via property chain
167
+ SELECT ?s ?c WHERE { ?s :monitors ?c }
168
+ ```
169
+
170
+ ### Virtual Graph Layer
171
+
172
+ The design has the graph expose:
173
+ - **Asserted triples** from the ABox
174
+ - **OWL-inferred triples** (transitive closure, property chains, class membership), which ProGraph's `profile="rl"` writes into the owned store's RL graph (transitive closure and property chains; the defined classes need RL+ extensions, which are not built)
175
+ - **PSL-inferred triples** as the named graph `<urn:psl:inferred>`, which nothing writes yet (queries Q11 and Q12 of `queries/example-queries.sparql` read it):
176
+ ```
177
+ GRAPH <urn:psl:inferred> {
178
+ inst:bearing-1001-mid :hasHealthState inst:state-warning .
179
+ inst:bearing-1001-mid :failureProbability "high" .
180
+ inst:bearing-1001-mid :maintenanceUrgency "immediate" .
181
+ inst:bearing-1001-mid :requiresMaintenance "replacement" .
182
+ }
183
+ ```
184
+
185
+ ### Action Layer Trigger Pattern
186
+
187
+ Pseudocode for the loop; ProAct's version is its turbofan policy, `examples/turbofan/` in the ProAct repository (see `docs/demos/turbofan.md`).
188
+
189
+ ```
190
+ ON INSERT { ?c :maintenanceUrgency "immediate" }
191
+ WHERE { ?c a :Bearing }
192
+ DO {
193
+ CREATE :Replacement for ?c ;
194
+ RESET :wearIndex, :cyclesSinceLastOverhaul ;
195
+ DELETE :exhibitsDegradation ;
196
+ NOTIFY "maintenance-queue" ;
197
+ RE-RUN PSL inference ;
198
+ }
199
+ ```
200
+
201
+ ---
202
+
203
+ ## Extending the Demo
204
+
205
+ - **Time-series trend detection.** Feed the CSV through a sliding-window anomaly detector; emit `sensorTrendAccelerating(S)` as an additional PSL predicate.
206
+ - **Cost optimization.** Add `maintenanceCost` data properties to PSL and optimize for minimal total cost subject to safety constraints.
207
+ - **Multi-engine fleet inference.** Add 10+ engines with shared environments to demonstrate fleet-level PSL correlation rules.
208
+ - **What-if simulation.** Use the action layer to simulate "what if we defer bearing replacement 500 cycles?" and observe how PSL re-scores risk.
209
+ - **Digital twin sync.** Connect the virtual graph to a real-time data feed (MQTT/Kafka) and run PSL in streaming mode.
@@ -0,0 +1,75 @@
1
+ """Turbofan engine predictive maintenance demo for ProGraph.
2
+
3
+ This is the canonical home for the demo's data-layer artifacts: OWL
4
+ ontology, instance data, sensor time series, SPARQL example queries,
5
+ schema, SHACL shapes and DDL. The maintenance PSL program, which drives
6
+ decisions, is ProAct's example (ProAct ``examples/turbofan/``). Downstream consumers (proact, prograph-studio)
7
+ source these via ``importlib.resources`` rather than duplicating them.
8
+
9
+ The companion :doc:`docs/demos/turbofan.md </docs/demos/turbofan>` design
10
+ doc explains the scenario; :doc:`SCENARIO.md </prograph/demos/turbofan/SCENARIO>`
11
+ contains the narrative.
12
+
13
+ Usage::
14
+
15
+ from prograph.demos.turbofan import asset_path
16
+ ontology_path = asset_path("ontology/engine-maintenance.ttl")
17
+
18
+ # Convenience aliases for the canonical artifacts:
19
+ from prograph.demos.turbofan import (
20
+ ONTOLOGY_PATH, INSTANCES_PATH,
21
+ SENSOR_CSV_PATH, QUERIES_PATH, SCHEMA_YAML_PATH, CREATE_TABLES_SQL_PATH,
22
+ )
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from importlib import resources
28
+ from pathlib import Path
29
+
30
+ __all__ = [
31
+ "asset_path",
32
+ "ONTOLOGY_PATH",
33
+ "INSTANCES_PATH",
34
+ "SENSOR_CSV_PATH",
35
+ "QUERIES_PATH",
36
+ "SCHEMA_YAML_PATH",
37
+ "CREATE_TABLES_SQL_PATH",
38
+ "SCENARIO_PATH",
39
+ "SHAPES_PATH",
40
+ "TURBOFAN_VOCAB_IRI",
41
+ "TURBOFAN_BASE_IRI",
42
+ ]
43
+
44
+
45
+ def asset_path(relative: str) -> Path:
46
+ """Resolve a demo asset to a filesystem ``Path``.
47
+
48
+ Works whether prograph is installed from a wheel or used from a
49
+ source checkout. ``relative`` is interpreted relative to this
50
+ package, e.g. ``"ontology/engine-maintenance.ttl"``.
51
+ """
52
+ root = resources.files(__name__)
53
+ target = root.joinpath(relative)
54
+ # ``resources.files`` returns a Traversable; in wheel-installs this
55
+ # may be a zip path. Most callers want a real ``Path``; ``as_file``
56
+ # would be the official API but is awkward for non-context-managed
57
+ # consumers. In practice both source and wheel installs produce a
58
+ # regular Path here since we ship no namespace packages.
59
+ return Path(str(target))
60
+
61
+
62
+ ONTOLOGY_PATH: Path = asset_path("ontology/engine-maintenance.ttl")
63
+ INSTANCES_PATH: Path = asset_path("data/engine-instances.ttl")
64
+ SENSOR_CSV_PATH: Path = asset_path("data/sensor-timeseries.csv")
65
+ QUERIES_PATH: Path = asset_path("queries/example-queries.sparql")
66
+ SCHEMA_YAML_PATH: Path = asset_path("graph.yaml")
67
+ CREATE_TABLES_SQL_PATH: Path = asset_path("create_tables.sql")
68
+ SCENARIO_PATH: Path = asset_path("SCENARIO.md")
69
+ SHAPES_PATH: Path = asset_path("shapes.ttl")
70
+
71
+ # IRI conventions used by the turbofan demo's SHACL shapes and OWL
72
+ # ontology. The schema's ``base_iri`` is TURBOFAN_BASE_IRI; the
73
+ # mapping declares class and predicate IRIs under TURBOFAN_VOCAB_IRI, which line up with the shapes file.
74
+ TURBOFAN_VOCAB_IRI: str = "http://example.org/engine-maintenance#"
75
+ TURBOFAN_BASE_IRI: str = "http://example.org/engine-maintenance/data/"
@@ -0,0 +1,206 @@
1
+ -- ==========================================================================
2
+ -- Turbofan Engine Predictive Maintenance: PostgreSQL DDL
3
+ -- ==========================================================================
4
+ --
5
+ -- 10 node tables + 17 relationship tables.
6
+ --
7
+ -- Shared tables (modules, components, sensors, degradation_modes,
8
+ -- maintenance_actions) use a `type` column as a discriminator.
9
+ -- ProGraph maps each subtype via filter_predicate={'type': 'SubType'}.
10
+ -- Columns match turbofan_schema.py and graph.yaml. For Spark/Delta, replace
11
+ -- TEXT with STRING, NUMERIC with DOUBLE or DECIMAL, and add USING DELTA.
12
+ -- ==========================================================================
13
+
14
+ -- ==========================================================================
15
+ -- Node Tables
16
+ -- ==========================================================================
17
+
18
+ CREATE TABLE engines (
19
+ id TEXT PRIMARY KEY,
20
+ label TEXT,
21
+ serial_number TEXT,
22
+ total_cycles_since_new INTEGER,
23
+ total_hours_since_new NUMERIC,
24
+ cycles_since_last_overhaul INTEGER,
25
+ hours_since_last_overhaul NUMERIC,
26
+ wear_index NUMERIC
27
+ );
28
+
29
+ CREATE TABLE modules (
30
+ id TEXT PRIMARY KEY,
31
+ type TEXT NOT NULL, -- FanModule, LPC, HPC, CombustionChamber, HPT, LPT, ExhaustNozzle, AccessoryGearbox, OilSystem, FuelSystem
32
+ label TEXT,
33
+ serial_number TEXT
34
+ );
35
+
36
+ CREATE TABLE components (
37
+ id TEXT PRIMARY KEY,
38
+ type TEXT NOT NULL, -- Blade, Disk, Shaft, Bearing, Seal, Combustor, FuelNozzle, OilPump, OilFilter, HeatExchanger, FADEC, Vane
39
+ label TEXT,
40
+ serial_number TEXT,
41
+ wear_index NUMERIC,
42
+ total_cycles_since_new INTEGER,
43
+ cycles_since_last_overhaul INTEGER,
44
+ remaining_useful_life_cycles INTEGER,
45
+ scheduled_interval INTEGER,
46
+ mean_time_between_failures NUMERIC,
47
+ has_health_state TEXT -- health state class, e.g. Warning, Advisory, Normal
48
+ );
49
+
50
+ CREATE TABLE sensors (
51
+ id TEXT PRIMARY KEY,
52
+ type TEXT NOT NULL, -- VibrationSensor, TemperatureSensor, PressureSensor, SpeedSensor, OilDebrisSensor, FlowSensor
53
+ label TEXT,
54
+ sensor_id TEXT,
55
+ nominal_min NUMERIC,
56
+ nominal_max NUMERIC,
57
+ caution_threshold NUMERIC,
58
+ warning_threshold NUMERIC,
59
+ critical_threshold NUMERIC
60
+ );
61
+
62
+ CREATE TABLE sensor_readings (
63
+ id TEXT PRIMARY KEY,
64
+ reading_timestamp TIMESTAMP,
65
+ reading_value NUMERIC,
66
+ reading_unit TEXT
67
+ );
68
+
69
+ CREATE TABLE degradation_modes (
70
+ id TEXT PRIMARY KEY,
71
+ type TEXT NOT NULL, -- Erosion, Corrosion, FatigueCracking, ThermalDegradation, ForeignObjectDamage, WearAbrasion, SealLeakage, CarbonBuildup
72
+ label TEXT
73
+ );
74
+
75
+ CREATE TABLE maintenance_actions (
76
+ id TEXT PRIMARY KEY,
77
+ type TEXT NOT NULL, -- BoroscopeInspection, OilAnalysis, BlendRepair, Replacement, ScheduledOverhaul
78
+ label TEXT,
79
+ comment TEXT,
80
+ maintenance_date DATE,
81
+ maintenance_cost NUMERIC,
82
+ maintenance_downtime_hours NUMERIC,
83
+ finding TEXT -- an inspection's result: within_limits, beyond_limits
84
+ );
85
+
86
+ CREATE TABLE fleets (
87
+ id TEXT PRIMARY KEY,
88
+ label TEXT
89
+ );
90
+
91
+ CREATE TABLE aircraft (
92
+ id TEXT PRIMARY KEY,
93
+ label TEXT
94
+ );
95
+
96
+ CREATE TABLE operating_environments (
97
+ id TEXT PRIMARY KEY,
98
+ label TEXT
99
+ );
100
+
101
+
102
+ -- ==========================================================================
103
+ -- Relationship Tables
104
+ -- ==========================================================================
105
+
106
+ CREATE TABLE is_part_of (
107
+ start_id TEXT NOT NULL,
108
+ end_id TEXT NOT NULL,
109
+ PRIMARY KEY (start_id, end_id)
110
+ );
111
+
112
+ CREATE TABLE downstream_of (
113
+ start_id TEXT NOT NULL,
114
+ end_id TEXT NOT NULL,
115
+ PRIMARY KEY (start_id, end_id)
116
+ );
117
+
118
+ CREATE TABLE connected_to (
119
+ start_id TEXT NOT NULL,
120
+ end_id TEXT NOT NULL,
121
+ PRIMARY KEY (start_id, end_id)
122
+ );
123
+
124
+ CREATE TABLE drives_shaft (
125
+ start_id TEXT NOT NULL,
126
+ end_id TEXT NOT NULL,
127
+ PRIMARY KEY (start_id, end_id)
128
+ );
129
+
130
+ CREATE TABLE supplies_fluid_to (
131
+ start_id TEXT NOT NULL,
132
+ end_id TEXT NOT NULL,
133
+ PRIMARY KEY (start_id, end_id)
134
+ );
135
+
136
+ CREATE TABLE monitors (
137
+ start_id TEXT NOT NULL, -- Sensor (or the FADEC component)
138
+ end_id TEXT NOT NULL, -- Component, Module or Engine
139
+ PRIMARY KEY (start_id, end_id)
140
+ );
141
+
142
+ CREATE TABLE installed_on (
143
+ start_id TEXT NOT NULL, -- Sensor
144
+ end_id TEXT NOT NULL, -- Component or Module
145
+ PRIMARY KEY (start_id, end_id)
146
+ );
147
+
148
+ CREATE TABLE has_reading (
149
+ start_id TEXT NOT NULL, -- Sensor
150
+ end_id TEXT NOT NULL, -- SensorReading
151
+ PRIMARY KEY (start_id, end_id)
152
+ );
153
+
154
+ CREATE TABLE exhibits_degradation (
155
+ start_id TEXT NOT NULL, -- Component
156
+ end_id TEXT NOT NULL, -- DegradationMode
157
+ PRIMARY KEY (start_id, end_id)
158
+ );
159
+
160
+ CREATE TABLE susceptible_to (
161
+ start_id TEXT NOT NULL, -- Component
162
+ end_id TEXT NOT NULL, -- DegradationMode
163
+ PRIMARY KEY (start_id, end_id)
164
+ );
165
+
166
+ CREATE TABLE indicated_by (
167
+ start_id TEXT NOT NULL, -- DegradationMode
168
+ end_id TEXT NOT NULL, -- Sensor
169
+ PRIMARY KEY (start_id, end_id)
170
+ );
171
+
172
+ CREATE TABLE propagates_to (
173
+ start_id TEXT NOT NULL,
174
+ end_id TEXT NOT NULL,
175
+ PRIMARY KEY (start_id, end_id)
176
+ );
177
+
178
+ CREATE TABLE performed_on (
179
+ start_id TEXT NOT NULL, -- MaintenanceAction
180
+ end_id TEXT NOT NULL, -- Component, Module or Engine
181
+ PRIMARY KEY (start_id, end_id)
182
+ );
183
+
184
+ CREATE TABLE addresses_degradation (
185
+ start_id TEXT NOT NULL, -- MaintenanceAction
186
+ end_id TEXT NOT NULL, -- DegradationMode
187
+ PRIMARY KEY (start_id, end_id)
188
+ );
189
+
190
+ CREATE TABLE installed_on_aircraft (
191
+ start_id TEXT NOT NULL, -- Engine
192
+ end_id TEXT NOT NULL, -- Aircraft
193
+ PRIMARY KEY (start_id, end_id)
194
+ );
195
+
196
+ CREATE TABLE belongs_to_fleet (
197
+ start_id TEXT NOT NULL, -- Aircraft
198
+ end_id TEXT NOT NULL, -- Fleet
199
+ PRIMARY KEY (start_id, end_id)
200
+ );
201
+
202
+ CREATE TABLE operates_in (
203
+ start_id TEXT NOT NULL, -- Engine
204
+ end_id TEXT NOT NULL, -- OperatingEnvironment
205
+ PRIMARY KEY (start_id, end_id)
206
+ );