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
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)
|
prograph/mcp/__init__.py
ADDED
|
@@ -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"]
|