style: enforce google docstrings and remove inline comments

Author: nadeem4

packages/core/src/nl2sql/common/event_logger.py

@@ -52,7 +52,6 @@ def log_event(
             tenant_id: Tenant/Customer ID.
         """
 
-        # Basic PII/Secret Redaction (Keys to scrub)
         sensitive_keys = {"api_key", "password", "secret", "authorization"}
         cleaned_payload = self._redact(payload, sensitive_keys)
 
@@ -67,7 +66,15 @@ def log_event(
         self.logger.info(json.dumps(event))
 
     def _redact(self, data: Any, keys_to_redact: set) -> Any:
-        """Recursively redact sensitive keys from dictionary."""
+        """Recursively redact sensitive keys from dictionary.
+
+        Args:
+            data: Input data (dict, list, or primitive).
+            keys_to_redact: Set of lowercase keys to match and redact.
+
+        Returns:
+            The sanitized data structure with sensitive values replaced by '***REDACTED***'.
+        """
         if isinstance(data, dict):
             return {
                 k: ("***REDACTED***" if k.lower() in keys_to_redact else self._redact(v, keys_to_redact))

packages/core/src/nl2sql/common/logger.py

@@ -94,10 +94,7 @@ def configure_logging(level: str = "INFO", json_format: bool = False):
     if json_format:
         handler.setFormatter(JsonFormatter())
     else:
-        # Include trace_id in standard format if present
-        # This is a bit tricky with dynamic formatting, usually easier to check record in formatter
-        # For simplicity, we stick to standard format but maybe prepend trace_id if possible?
-        # We'll stick to a standard format for text logs for now, trace_id mainly for JSON/Production
+        # Standard text format
         formatter = logging.Formatter(
             "%(asctime)s - [%(trace_id)s] - %(name)s - %(levelname)s - %(message)s"
         )

packages/core/src/nl2sql/common/metrics.py

@@ -5,11 +5,10 @@
 from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
 from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
 
-# Legacy in-memory logs (kept for CLI compatibility)
+# Legacy lists for CLI compatibility
 TOKEN_LOG: List[Dict[str, Any]] = []
 LATENCY_LOG: List[Dict[str, Any]] = []
 
-# OpenTelemetry Instruments
 _meter = metrics.get_meter("nl2sql.core")
 node_duration_histogram = _meter.create_histogram(
     name="nl2sql.node.duration",

packages/core/src/nl2sql/common/settings.py

@@ -108,8 +108,7 @@ def configure_env(self, env: str) -> None:
 
 settings = Settings()
 
-# Auto-configure logging based on settings
-# We want JSON logs in production (OTLP) to allow parsing by aggregators
+# Configure logging during import
 from nl2sql.common.logger import configure_logging
 configure_logging(
     level="INFO",

packages/core/src/nl2sql/pipeline/graph.py

@@ -24,13 +24,11 @@
 def traced_node(node: Callable):
     """Wraps a node to inject trace_id and tenant_id from state into the logging context."""
     def wrapper(state: Union[Dict, Any]):
-        # Extract trace_id and tenant_id from state
         tid = None
         tenant_id = None
 
         if isinstance(state, dict):
             tid = state.get("trace_id")
-            # user_context might be dict or object depending on serialization state in LangGraph
             uc = state.get("user_context")
             if isinstance(uc, dict):
                 tenant_id = uc.get("tenant_id")

packages/core/src/nl2sql/pipeline/nodes/decomposer/node.py

@@ -135,7 +135,6 @@ def __call__(self, state: GraphState) -> Dict[str, Any]:
             if state.semantic_analysis:
                 analysis = state.semantic_analysis
                 if analysis.keywords or analysis.synonyms:
-                    # Construct a search blob: Canonical + Keywords + Synonyms
                     expanded_query = f"{analysis.canonical_query} {' '.join(analysis.keywords)} {' '.join(analysis.synonyms)}"
                     print(f"Expanded Query: {expanded_query}")
 

packages/core/src/nl2sql/services/callbacks/monitor.py

@@ -6,11 +6,15 @@
 from langchain_core.outputs import LLMResult
 
 class PipelineMonitorCallback(BaseCallbackHandler):
+    """Callback handler for monitoring pipeline execution and auditing events.
+    
+    Integrates with OpenTelemetry for metrics and EventLogger for audit trails.
+    """
+    
     def __init__(self, presenter: ConsolePresenter):
         from nl2sql.common.settings import settings
         from nl2sql.common.metrics import configure_metrics
 
-        # One-time setup of metrics based on settings
         configure_metrics(
             exporter_type=settings.observability_exporter,
             otlp_endpoint=settings.otlp_endpoint
@@ -20,29 +24,31 @@ def __init__(self, presenter: ConsolePresenter):
         self.tokens = TokenHandler(self.node_handler.node_metrics)
 
     def on_chain_start(self, serialized: Dict[str, Any], inputs: Dict[str, Any], **kwargs: Any) -> Any:
+        """Called when a chain starts."""
         node_name = kwargs.get("metadata", {}).get("langgraph_node")
         run_id = str(kwargs.get("run_id"))
         parent_run_id = kwargs.get("parent_run_id")
         parent_run_id = str(parent_run_id) if parent_run_id else None
         self.node_handler.on_chain_start(run_id, parent_run_id, node_name, inputs)
 
     def on_chain_end(self, outputs: Dict[str, Any], **kwargs: Any) -> Any:
+        """Called when a chain ends."""
         run_id = str(kwargs.get("run_id"))
         self.node_handler.on_chain_end(run_id)
 
     def on_chain_error(self, error: BaseException, **kwargs: Any) -> Any:
+        """Called when a chain errors."""
         run_id = str(kwargs.get("run_id"))
         self.node_handler.on_chain_error(run_id, error)
 
     def on_llm_end(self, response: LLMResult, **kwargs: Any) -> Any:
+        """Called when an LLM ends."""
         from nl2sql.common.event_logger import event_logger
         from nl2sql.common.logger import _trace_id_ctx, _tenant_id_ctx
 
         tags = kwargs.get("tags", [])
         agent_name = next((t for t in tags if not t.startswith("seq:") and not t.startswith("langsmith:")), "unknown")
 
-        # Capture audit event
-        # Assuming single generation per call for simplicity in audit log
         text_output = ""
         model_name = "unknown"
         token_usage = {}
@@ -58,11 +64,10 @@ def on_llm_end(self, response: LLMResult, **kwargs: Any) -> Any:
         audit_payload = {
             "agent": agent_name,
             "model": model_name,
-            "response_snippet": text_output[:1000], # Trucate for sanity, full content maybe too big?
+            "response_snippet": text_output[:1000], 
             "token_usage": token_usage
         }
 
-        # Pull context directly from vars since we are in the same thread execution context
         event_logger.log_event(
             event_type="llm_interaction", 
             payload=audit_payload,

packages/core/src/nl2sql/services/callbacks/node_handlers.py

@@ -9,6 +9,8 @@
 
 
 class NodeHandler:
+    """Handles node execution lifecycle events and metrics recording."""
+
     def __init__(self, presenter: ConsolePresenter):
         self.presenter = presenter
 
@@ -116,7 +118,6 @@ def on_chain_end(self, run_id: str):
             }
         )
 
-        # OTeL Instrumentation
         node_duration_histogram.record(
             end - start,
             attributes={

packages/core/src/nl2sql/services/callbacks/token_handler.py

@@ -6,10 +6,13 @@
 
 
 class TokenHandler:
+    """Handles token usage tracking and metrics."""
+
     def __init__(self, node_metrics: dict[str, NodeMetrics]):
         self.node_metrics = node_metrics
 
     def on_llm_end(self, response: LLMResult, agent_name: str = "unknown", model_name: str = "unknown"):
+        """Records token usage from LLM response."""
         usage = None
         if response and response.llm_output:
             usage = response.llm_output.get("token_usage") or response.llm_output.get("usage")
@@ -36,7 +39,6 @@ def on_llm_end(self, response: LLMResult, agent_name: str = "unknown", model_nam
             }
         )
 
-        # OTeL Instrumentation
         token_usage_counter.add(
             t,
             attributes={