kqlbridge 0.1.0__tar.gz

kqlbridge-0.1.0/LICENSE

@@ -0,0 +1,93 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship made available under
+   the License.
+
+   "Derivative Works" shall mean any work that is based on the Work.
+
+   "Contribution" shall mean any work of authorship submitted to the Licensor.
+
+   "Contributor" shall mean Licensor and any Legal Entity on behalf of
+   whom a Contribution has been received by the Licensor.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative
+       Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work; and
+
+   (d) If the Work includes a "NOTICE" text file, include a readable
+       copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   shall be under the terms and conditions of this License, without any
+   additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work on an "AS IS"
+   BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+8. Limitation of Liability. In no event and under no legal theory
+   shall any Contributor be liable for any damages arising as a result
+   of this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations consistent of this License.
+
+Copyright 2026 Navakanth — KQLBridge Contributors

kqlbridge-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: kqlbridge
+Version: 0.1.0
+Summary: KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks
+License: Apache License
+        Version 2.0, January 2004
+        http://www.apache.org/licenses/
+        
+        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+        1. Definitions.
+        
+           "License" shall mean the terms and conditions for use, reproduction,
+           and distribution as defined by Sections 1 through 9 of this document.
+        
+           "Licensor" shall mean the copyright owner or entity authorized by
+           the copyright owner that is granting the License.
+        
+           "Legal Entity" shall mean the union of the acting entity and all
+           other entities that control, are controlled by, or are under common
+           control with that entity.
+        
+           "You" (or "Your") shall mean an individual or Legal Entity
+           exercising permissions granted by this License.
+        
+           "Source" form shall mean the preferred form for making modifications,
+           including but not limited to software source code, documentation
+           source, and configuration files.
+        
+           "Object" form shall mean any form resulting from mechanical
+           transformation or translation of a Source form, including but
+           not limited to compiled object code, generated documentation,
+           and conversions to other media types.
+        
+           "Work" shall mean the work of authorship made available under
+           the License.
+        
+           "Derivative Works" shall mean any work that is based on the Work.
+        
+           "Contribution" shall mean any work of authorship submitted to the Licensor.
+        
+           "Contributor" shall mean Licensor and any Legal Entity on behalf of
+           whom a Contribution has been received by the Licensor.
+        
+        2. Grant of Copyright License. Subject to the terms and conditions of
+           this License, each Contributor hereby grants to You a perpetual,
+           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+           copyright license to reproduce, prepare Derivative Works of,
+           publicly display, publicly perform, sublicense, and distribute the
+           Work and such Derivative Works in Source or Object form.
+        
+        3. Grant of Patent License. Subject to the terms and conditions of
+           this License, each Contributor hereby grants to You a perpetual,
+           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+           patent license to make, have made, use, offer to sell, sell,
+           import, and otherwise transfer the Work.
+        
+        4. Redistribution. You may reproduce and distribute copies of the
+           Work or Derivative Works thereof in any medium, with or without
+           modifications, and in Source or Object form, provided that You
+           meet the following conditions:
+        
+           (a) You must give any other recipients of the Work or Derivative
+               Works a copy of this License; and
+        
+           (b) You must cause any modified files to carry prominent notices
+               stating that You changed the files; and
+        
+           (c) You must retain, in the Source form of any Derivative Works
+               that You distribute, all copyright, patent, trademark, and
+               attribution notices from the Source form of the Work; and
+        
+           (d) If the Work includes a "NOTICE" text file, include a readable
+               copy of the attribution notices contained within such NOTICE file.
+        
+        5. Submission of Contributions. Unless You explicitly state otherwise,
+           any Contribution intentionally submitted for inclusion in the Work
+           shall be under the terms and conditions of this License, without any
+           additional terms or conditions.
+        
+        6. Trademarks. This License does not grant permission to use the trade
+           names, trademarks, service marks, or product names of the Licensor.
+        
+        7. Disclaimer of Warranty. Unless required by applicable law or
+           agreed to in writing, Licensor provides the Work on an "AS IS"
+           BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+        
+        8. Limitation of Liability. In no event and under no legal theory
+           shall any Contributor be liable for any damages arising as a result
+           of this License or out of the use or inability to use the Work.
+        
+        9. Accepting Warranty or Additional Liability. While redistributing
+           the Work or Derivative Works thereof, You may choose to offer,
+           and charge a fee for, acceptance of support, warranty, indemnity,
+           or other liability obligations consistent of this License.
+        
+        Copyright 2026 Navakanth — KQLBridge Contributors
+        
+Project-URL: Homepage, https://github.com/navakanth1984/kqlbridge
+Project-URL: Repository, https://github.com/navakanth1984/kqlbridge
+Project-URL: Issues, https://github.com/navakanth1984/kqlbridge/issues
+Keywords: kql,kusto,spark,databricks,fabric,transpiler,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.1.9
+Requires-Dist: sqlglot>=25.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# KQLBridge
+
+**KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks**
+
+[![PyPI version](https://badge.fury.io/py/kqlbridge.svg)](https://badge.fury.io/py/kqlbridge)
+[![Eval Score](https://img.shields.io/badge/eval-85%25-brightgreen)](tests/eval/prepare.py)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+KQLBridge lets data engineers write queries in **Kusto Query Language (KQL)** and compile them to **Spark SQL** (Databricks, Microsoft Fabric Spark notebooks) or **T-SQL** (Fabric SQL Warehouse, Synapse Analytics).
+
+```python
+from kqlbridge import translate
+
+kql = "AppLogs | where Level == 'Error' | summarize count() by ServiceName"
+sql = translate(kql, target="spark")
+# → SELECT ServiceName, COUNT(*) FROM AppLogs WHERE Level = 'Error' GROUP BY ServiceName
+```
+
+---
+
+## Why KQLBridge?
+
+Microsoft Fabric runs two query engines side by side: **Eventhouse** (KQL) and **Spark notebooks / SQL Warehouse** (Spark SQL / T-SQL). Teams that wrote years of KQL analytics can't simply copy-paste those queries into a Spark cell. KQLBridge automates the translation.
+
+**Use cases:**
+- Migrate ADX / Eventhouse KQL workloads to Databricks or Fabric Spark
+- Build routing agents that pick the right engine per query at runtime
+- Teach polyglot data engineering — learn one language, compile to all targets
+
+---
+
+## Installation
+
+```bash
+pip install kqlbridge
+```
+
+**Requires**: Python 3.10+, no external services, no API keys.
+
+---
+
+## Quick Start
+
+```python
+from kqlbridge import translate, detect_operators, is_supported
+
+# Translate KQL to Spark SQL
+sql = translate(
+    "AppLogs | where TimeGenerated > ago(24h) | project Message, Level",
+    target="spark"
+)
+
+# Check which operators are used
+ops = detect_operators("AppLogs | where Level == 'Error' | summarize count() by Host")
+# → ['where', 'summarize']
+
+# Check if a query is fully translatable
+if is_supported("AppLogs | make-series count() on TimeGenerated"):
+    sql = translate(...)
+else:
+    print("Unsupported operators — keep in KQL engine")
+```
+
+---
+
+## Supported Operators (v0.1)
+
+| KQL Operator | Spark SQL Output | Status |
+|---|---|---|
+| `where` | `WHERE clause` | ✅ v0.1 |
+| `project` | `SELECT columns` | ✅ v0.1 |
+| `summarize count()` | `SELECT COUNT(*) GROUP BY` | ✅ v0.1 |
+| `summarize sum/avg/min/max` | Aggregation functions | ✅ v0.1 |
+| `bin(col, 1h)` | `DATE_TRUNC('hour', col)` | ✅ v0.1 |
+| `ago(1h)` | `CURRENT_TIMESTAMP - INTERVAL '1 hours'` | ✅ v0.1 |
+| `extend` | `SELECT *, expr AS alias` | ✅ v0.1 |
+| `order by` / `sort by` | `ORDER BY col ASC/DESC` | ✅ v0.1 |
+| `take` / `limit` | `LIMIT n` | ✅ v0.1 |
+| `distinct` | `SELECT DISTINCT` | ✅ v0.1 |
+| `join` (inner) | `INNER JOIN ON key` | ✅ v0.1 |
+| `union` | `UNION ALL` | ✅ v0.1 |
+| `let` variables | CTEs (`WITH … AS`) | ✅ v0.1 |
+| `count()` | `COUNT(*)` scalar | ✅ v0.1 |
+
+See [supported_operators.md](docs/supported_operators.md) for full reference.
+See [unsupported_operators.md](docs/unsupported_operators.md) for operators with no SQL equivalent.
+
+---
+
+## Eval Score
+
+KQLBridge measures accuracy against a **locked 100-query benchmark** (70 standard, 20 edge-case, 10 adversarial). The eval script is the single source of truth — it is never modified by the agent loop.
+
+```bash
+python tests/eval/prepare.py
+# SCORE: 85.0% (85/100)
+```
+
+---
+
+## Architecture
+
+```
+KQL input
+  → Lark lexer (LOCKED grammar: kql.lark)
+  → Parser (MODIFIABLE: parser.py)
+  → AST nodes (LOCKED: ast_nodes.py)
+  → Semantic check (LOCKED: semantic.py)
+  → Generator (MODIFIABLE: generators/spark_sql.py)
+  → Spark SQL / T-SQL output
+```
+
+**Locked files** (oracle, grammar, types) are never touched by the agentic build loop.
+**Modifiable files** (parser, generators) are where improvements happen.
+
+---
+
+## Contributing
+
+All contributions must include a corresponding test case in `tests/eval/benchmark.json`.
+PRs that do not include a new test case will not be merged.
+
+```bash
+git clone https://github.com/navakanth1984/kqlbridge
+cd kqlbridge
+pip install -e ".[dev]"
+python tests/eval/prepare.py  # baseline score
+pytest tests/                 # unit tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+---
+
+## Companion Projects
+
+- **PipeQL** — Pipe-first SQL syntax that compiles to the same Spark SQL target (v0.2 roadmap)
+- **DE-Context Kit** — Routing agent + CDLC skill packages using KQLBridge under the hood
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

kqlbridge-0.1.0/README.md

@@ -0,0 +1,145 @@
+# KQLBridge
+
+**KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks**
+
+[![PyPI version](https://badge.fury.io/py/kqlbridge.svg)](https://badge.fury.io/py/kqlbridge)
+[![Eval Score](https://img.shields.io/badge/eval-85%25-brightgreen)](tests/eval/prepare.py)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+KQLBridge lets data engineers write queries in **Kusto Query Language (KQL)** and compile them to **Spark SQL** (Databricks, Microsoft Fabric Spark notebooks) or **T-SQL** (Fabric SQL Warehouse, Synapse Analytics).
+
+```python
+from kqlbridge import translate
+
+kql = "AppLogs | where Level == 'Error' | summarize count() by ServiceName"
+sql = translate(kql, target="spark")
+# → SELECT ServiceName, COUNT(*) FROM AppLogs WHERE Level = 'Error' GROUP BY ServiceName
+```
+
+---
+
+## Why KQLBridge?
+
+Microsoft Fabric runs two query engines side by side: **Eventhouse** (KQL) and **Spark notebooks / SQL Warehouse** (Spark SQL / T-SQL). Teams that wrote years of KQL analytics can't simply copy-paste those queries into a Spark cell. KQLBridge automates the translation.
+
+**Use cases:**
+- Migrate ADX / Eventhouse KQL workloads to Databricks or Fabric Spark
+- Build routing agents that pick the right engine per query at runtime
+- Teach polyglot data engineering — learn one language, compile to all targets
+
+---
+
+## Installation
+
+```bash
+pip install kqlbridge
+```
+
+**Requires**: Python 3.10+, no external services, no API keys.
+
+---
+
+## Quick Start
+
+```python
+from kqlbridge import translate, detect_operators, is_supported
+
+# Translate KQL to Spark SQL
+sql = translate(
+    "AppLogs | where TimeGenerated > ago(24h) | project Message, Level",
+    target="spark"
+)
+
+# Check which operators are used
+ops = detect_operators("AppLogs | where Level == 'Error' | summarize count() by Host")
+# → ['where', 'summarize']
+
+# Check if a query is fully translatable
+if is_supported("AppLogs | make-series count() on TimeGenerated"):
+    sql = translate(...)
+else:
+    print("Unsupported operators — keep in KQL engine")
+```
+
+---
+
+## Supported Operators (v0.1)
+
+| KQL Operator | Spark SQL Output | Status |
+|---|---|---|
+| `where` | `WHERE clause` | ✅ v0.1 |
+| `project` | `SELECT columns` | ✅ v0.1 |
+| `summarize count()` | `SELECT COUNT(*) GROUP BY` | ✅ v0.1 |
+| `summarize sum/avg/min/max` | Aggregation functions | ✅ v0.1 |
+| `bin(col, 1h)` | `DATE_TRUNC('hour', col)` | ✅ v0.1 |
+| `ago(1h)` | `CURRENT_TIMESTAMP - INTERVAL '1 hours'` | ✅ v0.1 |
+| `extend` | `SELECT *, expr AS alias` | ✅ v0.1 |
+| `order by` / `sort by` | `ORDER BY col ASC/DESC` | ✅ v0.1 |
+| `take` / `limit` | `LIMIT n` | ✅ v0.1 |
+| `distinct` | `SELECT DISTINCT` | ✅ v0.1 |
+| `join` (inner) | `INNER JOIN ON key` | ✅ v0.1 |
+| `union` | `UNION ALL` | ✅ v0.1 |
+| `let` variables | CTEs (`WITH … AS`) | ✅ v0.1 |
+| `count()` | `COUNT(*)` scalar | ✅ v0.1 |
+
+See [supported_operators.md](docs/supported_operators.md) for full reference.
+See [unsupported_operators.md](docs/unsupported_operators.md) for operators with no SQL equivalent.
+
+---
+
+## Eval Score
+
+KQLBridge measures accuracy against a **locked 100-query benchmark** (70 standard, 20 edge-case, 10 adversarial). The eval script is the single source of truth — it is never modified by the agent loop.
+
+```bash
+python tests/eval/prepare.py
+# SCORE: 85.0% (85/100)
+```
+
+---
+
+## Architecture
+
+```
+KQL input
+  → Lark lexer (LOCKED grammar: kql.lark)
+  → Parser (MODIFIABLE: parser.py)
+  → AST nodes (LOCKED: ast_nodes.py)
+  → Semantic check (LOCKED: semantic.py)
+  → Generator (MODIFIABLE: generators/spark_sql.py)
+  → Spark SQL / T-SQL output
+```
+
+**Locked files** (oracle, grammar, types) are never touched by the agentic build loop.
+**Modifiable files** (parser, generators) are where improvements happen.
+
+---
+
+## Contributing
+
+All contributions must include a corresponding test case in `tests/eval/benchmark.json`.
+PRs that do not include a new test case will not be merged.
+
+```bash
+git clone https://github.com/navakanth1984/kqlbridge
+cd kqlbridge
+pip install -e ".[dev]"
+python tests/eval/prepare.py  # baseline score
+pytest tests/                 # unit tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+---
+
+## Companion Projects
+
+- **PipeQL** — Pipe-first SQL syntax that compiles to the same Spark SQL target (v0.2 roadmap)
+- **DE-Context Kit** — Routing agent + CDLC skill packages using KQLBridge under the hood
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

kqlbridge-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kqlbridge"
+version = "0.1.0"
+description = "KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+keywords = ["kql", "kusto", "spark", "databricks", "fabric", "transpiler", "sql"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Compilers",
+]
+dependencies = [
+    "lark>=1.1.9",
+    "sqlglot>=25.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/navakanth1984/kqlbridge"
+Repository = "https://github.com/navakanth1984/kqlbridge"
+Issues = "https://github.com/navakanth1984/kqlbridge/issues"
+
+[project.scripts]
+kqlbridge = "kqlbridge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"kqlbridge" = ["grammar/*.lark"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src/kqlbridge"]
+omit = ["tests/eval/*"]  # Never instrument the locked oracle

kqlbridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kqlbridge-0.1.0/src/kqlbridge/__init__.py

@@ -0,0 +1,115 @@
+"""
+kqlbridge — KQL to Spark SQL / T-SQL transpiler
+================================================
+Public API:
+
+    translate(kql, target="spark") → str
+    detect_operators(kql) → list[str]
+    is_supported(kql) → bool
+    check(kql) → SemanticResult
+"""
+
+from __future__ import annotations
+from typing import Literal
+
+from .parser import parse
+from .semantic import check as _semantic_check, SemanticResult
+from .generators.spark_sql import SparkSQLGenerator
+from .generators.tsql import TSQLGenerator
+
+__version__ = "0.1.0"
+__all__ = ["translate", "detect_operators", "is_supported", "check", "__version__"]
+
+_SPARK_GEN = SparkSQLGenerator()
+_TSQL_GEN = TSQLGenerator()
+
+
+def translate(
+    kql: str,
+    target: Literal["spark", "tsql"] = "spark",
+) -> str:
+    """
+    Translate a KQL query string to the target SQL dialect.
+
+    Args:
+        kql:    KQL query string
+        target: "spark" (default) or "tsql"
+
+    Returns:
+        SQL string in the target dialect
+
+    Raises:
+        lark.exceptions.UnexpectedInput: on KQL parse error
+        NotImplementedError: if target generator is not implemented
+        ValueError: if query contains unsupported operators (check first)
+    """
+    query = parse(kql)
+    if target == "spark":
+        return _SPARK_GEN.generate(query)
+    if target == "tsql":
+        return _TSQL_GEN.generate(query)
+    raise ValueError(f"Unknown target: {target!r}. Use 'spark' or 'tsql'.")
+
+
+def detect_operators(kql: str) -> list[str]:
+    """
+    Return the list of KQL operators used in a query string.
+
+    Useful for routing agents that need to decide which engine to use.
+
+    Example:
+        detect_operators("T | where x == 1 | summarize count() by y")
+        → ['where', 'summarize']
+    """
+    from .ast_nodes import (
+        WhereOp, ProjectOp, SummarizeOp, OrderOp, TakeOp,
+        DistinctOp, ExtendOp, JoinOp, UnionOp, CountOp,
+    )
+    _OP_NAMES = {
+        WhereOp: "where",
+        ProjectOp: "project",
+        SummarizeOp: "summarize",
+        OrderOp: "order by",
+        TakeOp: "take",
+        DistinctOp: "distinct",
+        ExtendOp: "extend",
+        JoinOp: "join",
+        UnionOp: "union",
+        CountOp: "count",
+    }
+
+    try:
+        query = parse(kql)
+        return [_OP_NAMES[type(op)] for op in query.pipes
+                if type(op) in _OP_NAMES]
+    except Exception:
+        return []
+
+
+def is_supported(kql: str) -> bool:
+    """
+    Return True if the query can be fully translated to Spark SQL.
+
+    Queries with unsupported operators (make-series, render, etc.)
+    return False — the caller should keep those in the native KQL engine.
+    """
+    try:
+        query = parse(kql)
+        result = _semantic_check(query)
+        return result.is_supported
+    except Exception:
+        return False
+
+
+def check(kql: str) -> SemanticResult:
+    """
+    Parse and semantically validate a KQL query.
+
+    Returns a SemanticResult with:
+    - is_valid: True if AST is structurally sound
+    - is_supported: True if query can be fully translated
+    - warnings: Non-blocking issues
+    - errors: Blocking issues (unsupported operators, ambiguities)
+    """
+    query = parse(kql)
+    return _semantic_check(query)