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
prograph/logging.py ADDED
@@ -0,0 +1,550 @@
1
+ """Structured logging for ProGraph query planning and execution.
2
+
3
+ This module provides structured logging using structlog (if available) to help
4
+ diagnose query planning decisions, execution routing, and performance issues.
5
+
6
+ Usage:
7
+ from prograph.logging import get_logger
8
+
9
+ logger = get_logger(__name__)
10
+ logger.debug("vl_traversal_start", start_label="Person", rel_type="KNOWS", hops="1..3")
11
+
12
+ If structlog is not installed, falls back to a no-op logger that discards all
13
+ log messages (zero performance overhead when logging is not needed).
14
+
15
+ To enable debug logging:
16
+ import prograph.logging
17
+ prograph.logging.configure(level='DEBUG')
18
+
19
+ Or with environment variable:
20
+ export PROGRAPH_LOG_LEVEL=DEBUG
21
+ """
22
+
23
+ import contextlib
24
+ import contextvars
25
+ import os
26
+ from typing import Any, Iterator, List, Optional
27
+
28
+ # Try to import structlog
29
+ try:
30
+ import structlog
31
+ STRUCTLOG_AVAILABLE = True
32
+ except ImportError:
33
+ STRUCTLOG_AVAILABLE = False
34
+ structlog = None
35
+
36
+
37
+ # Global configuration
38
+ _configured = False
39
+ _log_level = os.environ.get('PROGRAPH_LOG_LEVEL', 'WARNING').upper()
40
+ _original_log_level = _log_level # Saved for restore after capture
41
+
42
+
43
+ class NoOpLogger:
44
+ """A logger that discards all messages. Zero overhead when logging disabled."""
45
+
46
+ def debug(self, event: str = None, **kwargs: Any) -> None:
47
+ pass
48
+
49
+ def info(self, event: str = None, **kwargs: Any) -> None:
50
+ pass
51
+
52
+ def warning(self, event: str = None, **kwargs: Any) -> None:
53
+ pass
54
+
55
+ def error(self, event: str = None, **kwargs: Any) -> None:
56
+ pass
57
+
58
+ def exception(self, event: str = None, **kwargs: Any) -> None:
59
+ pass
60
+
61
+ def bind(self, **kwargs: Any) -> 'NoOpLogger':
62
+ return self
63
+
64
+ def unbind(self, *keys: str) -> 'NoOpLogger':
65
+ return self
66
+
67
+ def new(self, **kwargs: Any) -> 'NoOpLogger':
68
+ return NoOpLogger()
69
+
70
+
71
+ class StdlibLogger:
72
+ """A logger using standard library logging (fallback when structlog unavailable)."""
73
+
74
+ def __init__(self, name: str = None):
75
+ import logging
76
+ self._logger = logging.getLogger(name or 'prograph')
77
+
78
+ def _format_msg(self, event: str, kwargs: dict) -> str:
79
+ if kwargs:
80
+ params = ' '.join(f'{k}={v}' for k, v in kwargs.items())
81
+ return f"{event} {params}"
82
+ return event
83
+
84
+ def debug(self, event: str = None, **kwargs: Any) -> None:
85
+ self._logger.debug(self._format_msg(event, kwargs))
86
+
87
+ def info(self, event: str = None, **kwargs: Any) -> None:
88
+ self._logger.info(self._format_msg(event, kwargs))
89
+
90
+ def warning(self, event: str = None, **kwargs: Any) -> None:
91
+ self._logger.warning(self._format_msg(event, kwargs))
92
+
93
+ def error(self, event: str = None, **kwargs: Any) -> None:
94
+ self._logger.error(self._format_msg(event, kwargs))
95
+
96
+ def exception(self, event: str = None, **kwargs: Any) -> None:
97
+ self._logger.exception(self._format_msg(event, kwargs))
98
+
99
+ def bind(self, **kwargs: Any) -> 'StdlibLogger':
100
+ return self
101
+
102
+ def unbind(self, *keys: str) -> 'StdlibLogger':
103
+ return self
104
+
105
+ def new(self, **kwargs: Any) -> 'StdlibLogger':
106
+ return StdlibLogger()
107
+
108
+
109
+ _noop_logger = NoOpLogger()
110
+
111
+
112
+ def configure(
113
+ level: str = 'WARNING',
114
+ json_format: bool = False,
115
+ add_timestamp: bool = True,
116
+ colors: Optional[bool] = None,
117
+ ) -> None:
118
+ """Configure ProGraph logging.
119
+
120
+ Args:
121
+ level: Log level ('DEBUG', 'INFO', 'WARNING', 'ERROR')
122
+ json_format: If True, output JSON logs (useful for log aggregation)
123
+ add_timestamp: If True, add timestamp to log entries
124
+ colors: If True, use ANSI color codes in console output.
125
+ If False, disable colors (useful for log files or non-TTY output).
126
+ If None (default), reads PROGRAPH_LOG_COLORS env var
127
+ ('0'/'false'/'no' to disable), falling back to True.
128
+
129
+ Example:
130
+ >>> import prograph.logging
131
+ >>> prograph.logging.configure(level='DEBUG')
132
+ >>> engine.execute("MATCH (p:Person)-[:KNOWS*1..3]->(f) RETURN f")
133
+ # Will now output debug logs showing execution decisions
134
+
135
+ >>> # Disable ANSI colors for log files
136
+ >>> prograph.logging.configure(level='DEBUG', colors=False)
137
+
138
+ >>> # Or via environment variable
139
+ >>> # export PROGRAPH_LOG_COLORS=false
140
+ """
141
+ global _configured, _log_level
142
+
143
+ _log_level = level.upper()
144
+ _configured = True
145
+
146
+ import logging
147
+
148
+ # Only configure prograph loggers, not the root logger
149
+ # This prevents flooding output with debug logs from other libraries
150
+ prograph_logger = logging.getLogger('prograph')
151
+ prograph_logger.setLevel(getattr(logging, _log_level, logging.WARNING))
152
+
153
+ # Add handler if none exists
154
+ if not prograph_logger.handlers:
155
+ handler = logging.StreamHandler()
156
+ handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
157
+ prograph_logger.addHandler(handler)
158
+
159
+ # Prevent propagation to root logger (avoids duplicate messages)
160
+ prograph_logger.propagate = False
161
+
162
+ if not STRUCTLOG_AVAILABLE:
163
+ # Using stdlib logger fallback
164
+ return
165
+
166
+ # Build processor chain for structlog
167
+ processors = [
168
+ structlog.stdlib.filter_by_level,
169
+ structlog.stdlib.add_logger_name,
170
+ structlog.stdlib.add_log_level,
171
+ ]
172
+
173
+ if add_timestamp:
174
+ processors.append(structlog.processors.TimeStamper(fmt="iso"))
175
+
176
+ processors.extend([
177
+ structlog.processors.StackInfoRenderer(),
178
+ structlog.processors.UnicodeDecoder(),
179
+ ])
180
+
181
+ if json_format:
182
+ processors.append(structlog.processors.JSONRenderer())
183
+ else:
184
+ use_colors = colors
185
+ if use_colors is None:
186
+ env_val = os.environ.get('PROGRAPH_LOG_COLORS', '').lower()
187
+ use_colors = env_val not in ('0', 'false', 'no') if env_val else True
188
+ processors.append(structlog.dev.ConsoleRenderer(colors=use_colors))
189
+
190
+ structlog.configure(
191
+ processors=processors,
192
+ wrapper_class=structlog.stdlib.BoundLogger,
193
+ context_class=dict,
194
+ logger_factory=structlog.stdlib.LoggerFactory(),
195
+ cache_logger_on_first_use=True,
196
+ )
197
+
198
+
199
+ def is_debug_enabled() -> bool:
200
+ """Check if debug logging is enabled.
201
+
202
+ Use this to avoid expensive computations for debug messages:
203
+
204
+ if is_debug_enabled():
205
+ logger.debug("expensive_info", data=expensive_computation())
206
+
207
+ Returns:
208
+ True if DEBUG level logging is enabled
209
+ """
210
+ return _log_level == 'DEBUG' or _scoped_capture.get() is not None
211
+
212
+
213
+ def get_plan_logger() -> Any:
214
+ """Get logger for query planning."""
215
+ return get_logger("prograph.plan")
216
+
217
+
218
+ def get_backend_logger() -> Any:
219
+ """Get logger for backend execution."""
220
+ return get_logger("prograph.backend")
221
+
222
+
223
+ # =============================================================================
224
+ # Testing Support
225
+ # =============================================================================
226
+
227
+ class CapturingLogger:
228
+ """A logger that captures all log events with full context accumulation.
229
+
230
+ Supports structlog-style context binding - each bind() call adds to the
231
+ accumulated context, and every log event includes all accumulated context.
232
+
233
+ Usage:
234
+ >>> logger = CapturingLogger()
235
+ >>> logger.debug("event_name", key="value")
236
+ >>> assert logger.has_event("event_name")
237
+ >>> assert logger.get_event("event_name")["key"] == "value"
238
+
239
+ Context accumulation:
240
+ >>> logger = CapturingLogger()
241
+ >>> logger = logger.bind(query_id="q1", operations=5)
242
+ >>> logger = logger.bind(pattern={"nodes": 2})
243
+ >>> logger.debug("decision", choice="sql")
244
+ >>> # Event has: query_id, operations, pattern, AND choice
245
+ >>> event = logger.get_event("decision")
246
+ >>> assert event["query_id"] == "q1"
247
+ >>> assert event["pattern"]["nodes"] == 2
248
+ """
249
+
250
+ def __init__(self, context: Optional[dict] = None, event_store: Optional[list] = None):
251
+ """Initialize logger with optional initial context and shared event store.
252
+
253
+ Args:
254
+ context: Initial context dict (for bound loggers)
255
+ event_store: Shared event list (for bound loggers to share events)
256
+ """
257
+ self._context = dict(context) if context else {}
258
+ # All bound loggers share the same event store
259
+ self.events = event_store if event_store is not None else []
260
+
261
+ def _log(self, level: str, event: str = None, **kwargs: Any) -> None:
262
+ """Log an event with full accumulated context."""
263
+ self.events.append({
264
+ 'level': level,
265
+ 'event': event,
266
+ **self._context, # Include all accumulated context
267
+ **kwargs # Event-specific data (can override context)
268
+ })
269
+
270
+ def debug(self, event: str = None, **kwargs: Any) -> None:
271
+ self._log('debug', event, **kwargs)
272
+
273
+ def info(self, event: str = None, **kwargs: Any) -> None:
274
+ self._log('info', event, **kwargs)
275
+
276
+ def warning(self, event: str = None, **kwargs: Any) -> None:
277
+ self._log('warning', event, **kwargs)
278
+
279
+ def error(self, event: str = None, **kwargs: Any) -> None:
280
+ self._log('error', event, **kwargs)
281
+
282
+ def exception(self, event: str = None, **kwargs: Any) -> None:
283
+ self._log('exception', event, **kwargs)
284
+
285
+ def bind(self, **kwargs: Any) -> 'CapturingLogger':
286
+ """Return a new logger with additional context bound.
287
+
288
+ The new logger shares the same event store, so all events
289
+ are captured in one place regardless of which bound logger
290
+ emitted them.
291
+ """
292
+ new_context = {**self._context, **kwargs}
293
+ return CapturingLogger(context=new_context, event_store=self.events)
294
+
295
+ def unbind(self, *keys: str) -> 'CapturingLogger':
296
+ """Return a new logger with specified keys removed from context."""
297
+ new_context = {k: v for k, v in self._context.items() if k not in keys}
298
+ return CapturingLogger(context=new_context, event_store=self.events)
299
+
300
+ def new(self, **kwargs: Any) -> 'CapturingLogger':
301
+ """Return a new logger with fresh context but shared event store."""
302
+ return CapturingLogger(context=kwargs, event_store=self.events)
303
+
304
+ def clear(self) -> None:
305
+ """Clear all captured events and context."""
306
+ self.events.clear()
307
+ self._context.clear()
308
+
309
+ def get_context(self) -> dict:
310
+ """Get the current accumulated context."""
311
+ return dict(self._context)
312
+
313
+ def has_event(self, event_name: str) -> bool:
314
+ """Check if an event with the given name was logged."""
315
+ return any(e.get('event') == event_name for e in self.events)
316
+
317
+ def get_event(self, event_name: str) -> Optional[dict]:
318
+ """Get the first event with the given name, or None."""
319
+ for e in self.events:
320
+ if e.get('event') == event_name:
321
+ return e
322
+ return None
323
+
324
+ def get_events(self, event_name: str) -> list:
325
+ """Get all events with the given name."""
326
+ return [e for e in self.events if e.get('event') == event_name]
327
+
328
+ def get_all_events(self) -> list:
329
+ """Get all captured events."""
330
+ return list(self.events)
331
+
332
+
333
+ # Global capturing logger for testing
334
+ _capturing_logger: Optional[CapturingLogger] = None
335
+
336
+
337
+ def enable_capture(accumulate: bool = False) -> CapturingLogger:
338
+ """Enable log capture.
339
+
340
+ Returns a CapturingLogger that will receive all log events.
341
+ Call disable_capture() when done.
342
+
343
+ Args:
344
+ accumulate: If True, reuse existing logger and append events.
345
+ If False (default), create fresh logger.
346
+
347
+ Usage:
348
+ >>> from prograph.logging import enable_capture, disable_capture
349
+ >>> captured = enable_capture()
350
+ >>> # ... run code that logs ...
351
+ >>> assert captured.has_event("vl_mode_selected")
352
+ >>> disable_capture()
353
+
354
+ For session-scoped accumulation:
355
+ >>> captured = enable_capture()
356
+ >>> engine.execute(query1)
357
+ >>> engine.execute(query2) # Events accumulate
358
+ >>> all_events = captured.get_all_events()
359
+ >>> disable_capture()
360
+
361
+ Or with explicit accumulation across enable/disable cycles:
362
+ >>> captured = enable_capture()
363
+ >>> engine.execute(query1)
364
+ >>> disable_capture()
365
+ >>> captured = enable_capture(accumulate=True) # Preserves previous events
366
+ >>> engine.execute(query2)
367
+ >>> all_events = captured.get_all_events() # Has events from both queries
368
+ """
369
+ global _capturing_logger, _log_level, _configured, _original_log_level
370
+
371
+ if accumulate and _capturing_logger is not None:
372
+ # Reuse existing logger, events accumulate
373
+ pass
374
+ else:
375
+ # Create fresh logger
376
+ _capturing_logger = CapturingLogger()
377
+
378
+ # Save original level before switching to DEBUG (only on first enable)
379
+ if _log_level != 'DEBUG':
380
+ _original_log_level = _log_level
381
+ _log_level = 'DEBUG'
382
+ _configured = True
383
+ return _capturing_logger
384
+
385
+
386
+ def disable_capture(clear: bool = True) -> None:
387
+ """Disable log capture and optionally restore normal logging.
388
+
389
+ Args:
390
+ clear: If True (default), clear the capturing logger.
391
+ If False, preserve events for later retrieval with enable_capture(accumulate=True).
392
+ """
393
+ global _capturing_logger, _configured, _log_level, _original_log_level
394
+
395
+ if clear:
396
+ _capturing_logger = None
397
+ # Restore original log level to prevent DEBUG leak
398
+ _log_level = _original_log_level
399
+ _configured = False
400
+
401
+
402
+ # The capture of the block the current context is in (capture_events), if
403
+ # any. A ContextVar and not a module global: another thread, or another
404
+ # task, has its own context, so its events are neither taken into this
405
+ # capture nor kept from its own log.
406
+ _scoped_capture: contextvars.ContextVar[Optional[CapturingLogger]] = contextvars.ContextVar(
407
+ "prograph_scoped_capture", default=None)
408
+
409
+
410
+ class _TeeLogger:
411
+ """Logs to the logger that would have been used, and to a capture.
412
+
413
+ Made by get_logger() inside a capture_events block, for use inside it.
414
+ An object that takes a logger in __init__ and outlives the block would
415
+ go on feeding a capture nobody reads: fetch the logger where it is used.
416
+ """
417
+
418
+ def __init__(self, logger: Any, capture: CapturingLogger):
419
+ self._logger = logger
420
+ self._capture = capture
421
+
422
+ def _log(self, level: str, event: str = None, **kwargs: Any) -> None:
423
+ getattr(self._capture, level)(event, **kwargs)
424
+ getattr(self._logger, level)(event, **kwargs)
425
+
426
+ def debug(self, event: str = None, **kwargs: Any) -> None:
427
+ self._log('debug', event, **kwargs)
428
+
429
+ def info(self, event: str = None, **kwargs: Any) -> None:
430
+ self._log('info', event, **kwargs)
431
+
432
+ def warning(self, event: str = None, **kwargs: Any) -> None:
433
+ self._log('warning', event, **kwargs)
434
+
435
+ def error(self, event: str = None, **kwargs: Any) -> None:
436
+ self._log('error', event, **kwargs)
437
+
438
+ def exception(self, event: str = None, **kwargs: Any) -> None:
439
+ self._log('exception', event, **kwargs)
440
+
441
+ def bind(self, **kwargs: Any) -> '_TeeLogger':
442
+ return _TeeLogger(self._logger.bind(**kwargs), self._capture.bind(**kwargs))
443
+
444
+ def unbind(self, *keys: str) -> '_TeeLogger':
445
+ return _TeeLogger(self._logger.unbind(*keys), self._capture.unbind(*keys))
446
+
447
+ def new(self, **kwargs: Any) -> '_TeeLogger':
448
+ return _TeeLogger(self._logger.new(**kwargs), self._capture.new(**kwargs))
449
+
450
+
451
+ @contextlib.contextmanager
452
+ def capture_events() -> Iterator[CapturingLogger]:
453
+ """Capture the events logged inside the block, and only those.
454
+
455
+ Unlike `enable_capture` / `disable_capture`, which switch the whole
456
+ process over to one capturing logger, this belongs to the context it is
457
+ entered in: the block's events are captured and also logged as they
458
+ would have been (to a capture `enable_capture` has on, or to the
459
+ configured logger), and a thread or task outside the block is not
460
+ touched. Its events do not enter this capture, and none of its lines
461
+ are lost. Blocks nest: an outer one sees what an inner one sees.
462
+ `prograph.plan.run_record.observe` uses it.
463
+
464
+ Captured are the events of loggers fetched inside the block
465
+ (get_logger and the get_*_logger helpers, called where they log). A
466
+ module that took its logger once at import logs through that one, and
467
+ its events are not in the capture; the same was true of
468
+ `enable_capture` unless it was on before the import.
469
+ """
470
+ inner = CapturingLogger()
471
+ token = _scoped_capture.set(inner)
472
+ try:
473
+ yield inner
474
+ finally:
475
+ _scoped_capture.reset(token)
476
+ outer = _scoped_capture.get()
477
+ if outer is not None:
478
+ outer.events.extend(inner.events)
479
+
480
+
481
+ def get_captured_events() -> List[dict]:
482
+ """Get all captured events without disabling capture.
483
+
484
+ Useful for inspecting events mid-session.
485
+
486
+ Returns:
487
+ List of captured event dictionaries, or empty list if not capturing.
488
+ """
489
+ if _capturing_logger is not None:
490
+ return _capturing_logger.get_all_events()
491
+ return []
492
+
493
+
494
+ def clear_captured_events() -> None:
495
+ """Clear captured events without disabling capture.
496
+
497
+ Useful for resetting between operations while keeping capture enabled.
498
+ """
499
+ if _capturing_logger is not None:
500
+ _capturing_logger.clear()
501
+
502
+
503
+ def get_logger(name: str = None) -> Any:
504
+ """Get a logger instance.
505
+
506
+ If structlog is installed and logging is enabled, returns a structlog logger.
507
+ If structlog is not installed but logging is configured, returns a stdlib logger.
508
+ Otherwise returns a no-op logger with zero overhead.
509
+
510
+ Args:
511
+ name: Logger name (typically __name__)
512
+
513
+ Returns:
514
+ Logger instance
515
+
516
+ Example:
517
+ >>> from prograph.logging import get_logger
518
+ >>> logger = get_logger(__name__)
519
+ >>> logger.debug("vl_mode_selected", mode="adjacency", reason="index available")
520
+ """
521
+ scoped = _scoped_capture.get()
522
+ if scoped is not None:
523
+ return _TeeLogger(_unscoped_logger(name), scoped)
524
+ return _unscoped_logger(name)
525
+
526
+
527
+ def _unscoped_logger(name: str = None) -> Any:
528
+ """The logger for `name` with no capture_events block considered."""
529
+ global _configured, _capturing_logger
530
+
531
+ # If capturing is enabled, return the capturing logger
532
+ if _capturing_logger is not None:
533
+ return _capturing_logger
534
+
535
+ # Auto-configure on first use if not already configured
536
+ if not _configured:
537
+ configure(level=_log_level)
538
+
539
+ # At WARNING/ERROR level, use no-op logger for efficiency
540
+ # This avoids the structlog overhead when debug logging is disabled
541
+ # Warnings and errors from prograph itself are rare and typically
542
+ # indicate bugs that should be fixed in code, not logged at runtime
543
+ if _log_level in ('WARNING', 'ERROR'):
544
+ return _noop_logger
545
+
546
+ # Use structlog if available, otherwise fall back to stdlib
547
+ if STRUCTLOG_AVAILABLE:
548
+ return structlog.get_logger(name)
549
+ else:
550
+ return StdlibLogger(name)
@@ -0,0 +1,29 @@
1
+ """ProGraph MCP server.
2
+
3
+ Exposes a ProGraph engine over the Model Context Protocol so any
4
+ MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) can
5
+ execute Cypher / SPARQL queries against the engine's
6
+ configured data sources.
7
+
8
+ Typical use from a client config:
9
+
10
+ {
11
+ "mcpServers": {
12
+ "prograph": {
13
+ "command": "python",
14
+ "args": ["-m", "prograph.mcp", "--config", "/path/to/graph.yaml"]
15
+ }
16
+ }
17
+ }
18
+
19
+ Programmatic embedding:
20
+
21
+ from prograph.mcp import build_server
22
+ server = build_server(engine)
23
+ await server.run_stdio_async()
24
+ """
25
+
26
+ from prograph.mcp.server import build_server
27
+ from prograph.mcp.bootstrap import load_engine
28
+
29
+ __all__ = ["build_server", "load_engine"]