uqal-core 0.1.0__tar.gz

uqal_core-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# UQAL secrets template
+# Copy this file to .env and fill in your real values
+# Never commit .env to git
+
+# Example for a connection named "db1":
+# UQAL_DB1_USER=
+# UQAL_DB1_PASSWORD=
+# UQAL_DB1_SSL_CERT=
+
+# Example for a connection named "graph":
+# UQAL_GRAPH_USER=
+# UQAL_GRAPH_PASSWORD=

uqal_core-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug Report
+description: Something is not working as expected in uqal-core.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: uqal-core version
+      placeholder: "e.g. 0.3.1"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Load module ...
+        2. Run query ...
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output / stack trace
+      render: shell

uqal_core-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature Request
+description: Suggest an improvement or new capability for uqal-core.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the limitation or gap you are running into.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How should it work? Include example syntax or API if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about and why you ruled them out.
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Affected area
+      options:
+        - label: Parser / Grammar
+        - label: AST / Transformer
+        - label: Module interface
+        - label: Module loader
+        - label: CLI
+        - label: Dev tooling

uqal_core-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What
+
+<!-- What does this PR change? -->
+
+## Why
+
+<!-- Why is this change needed? Link an issue if one exists. Closes #... -->
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] `uv run pytest` passes locally
+- [ ] No debug code or temporary files included

uqal_core-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

uqal_core-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+test_grammar.py
+test_grammar_files.py
+
+test_grammar_builder.py
+
+tests/logs/
+tests/coverage_html/
+
+.env
+
+uqal_config.json
+
+.coverage
+tests/coverage_html/
+
+.uqal/

uqal_core-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14.0

uqal_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UQAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uqal_core-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: uqal-core
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: click>=8.4.2
+Requires-Dist: lark>=1.3.1
+Requires-Dist: neo4j>=6.2.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: psycopg2-binary>=2.9.12
+Requires-Dist: pymongo>=4.17.0
+Requires-Dist: textual>=8.2.8
+Description-Content-Type: text/markdown
+
+# uqal-core
+
+The core engine of [UQAL](https://uqal-lang.github.io/uqal-docs) — a unified query abstraction layer that lets you write one query syntax and run it against any supported database.
+
+`uqal-core` contains the parser, grammar builder, AST, module loader, and CLI. It is the runtime that all UQAL modules plug into.
+
+---
+
+## What is UQAL?
+
+UQAL is a database-agnostic query language. Instead of writing SQL for PostgreSQL, Cypher for Neo4j, and MQL for MongoDB separately, you write UQAL once and the appropriate module translates it into the native query for the connected database.
+
+```
+mydb.users.get_table(where active = true, fields id, name)
+```
+
+---
+
+## Installation
+
+```bash
+uv add uqal-core
+```
+
+Requires Python 3.12+.
+
+---
+
+## Quick Start
+
+```bash
+# Start the interactive UQAL shell
+uqal shell
+
+# Run a query file
+uqal run query.uqal
+
+# List loaded modules
+uqal list-modules
+```
+
+---
+
+## Modules
+
+Database support comes from modules. Standard modules ship with `uqal-core`. Community modules are installed separately:
+
+```bash
+uv add uqal-postgis
+uqal add-module community.postgis
+```
+
+Browse available modules: [uqal-lang/uqal-modules](https://github.com/uqal-lang/uqal-modules)
+
+---
+
+## Development Setup
+
+```bash
+git clone https://github.com/uqal-lang/uqal-core
+cd uqal-core
+uv sync
+uv run pytest
+```
+
+Dev scripts are in `scripts/dev/`:
+
+```bash
+# Parse and translate a query
+uv run python scripts/dev/check_query.py "mydb.users.get_table()"
+
+# Inspect the combined grammar
+uv run python scripts/dev/inspect_grammar.py
+
+# Validate a module implementation
+uv run python scripts/dev/validate_module.py standard.postgresql
+```
+
+---
+
+## Contributing
+
+`uqal-core` is maintained by the core team. See [CONTRIBUTING](https://uqal-lang.github.io/uqal-docs/contributing) for the development workflow.
+
+To contribute a new database module, head to [uqal-lang/uqal-modules](https://github.com/uqal-lang/uqal-modules).
+
+---
+
+## License
+
+[MIT](LICENSE)

uqal_core-0.1.0/README.md

@@ -0,0 +1,91 @@
+# uqal-core
+
+The core engine of [UQAL](https://uqal-lang.github.io/uqal-docs) — a unified query abstraction layer that lets you write one query syntax and run it against any supported database.
+
+`uqal-core` contains the parser, grammar builder, AST, module loader, and CLI. It is the runtime that all UQAL modules plug into.
+
+---
+
+## What is UQAL?
+
+UQAL is a database-agnostic query language. Instead of writing SQL for PostgreSQL, Cypher for Neo4j, and MQL for MongoDB separately, you write UQAL once and the appropriate module translates it into the native query for the connected database.
+
+```
+mydb.users.get_table(where active = true, fields id, name)
+```
+
+---
+
+## Installation
+
+```bash
+uv add uqal-core
+```
+
+Requires Python 3.12+.
+
+---
+
+## Quick Start
+
+```bash
+# Start the interactive UQAL shell
+uqal shell
+
+# Run a query file
+uqal run query.uqal
+
+# List loaded modules
+uqal list-modules
+```
+
+---
+
+## Modules
+
+Database support comes from modules. Standard modules ship with `uqal-core`. Community modules are installed separately:
+
+```bash
+uv add uqal-postgis
+uqal add-module community.postgis
+```
+
+Browse available modules: [uqal-lang/uqal-modules](https://github.com/uqal-lang/uqal-modules)
+
+---
+
+## Development Setup
+
+```bash
+git clone https://github.com/uqal-lang/uqal-core
+cd uqal-core
+uv sync
+uv run pytest
+```
+
+Dev scripts are in `scripts/dev/`:
+
+```bash
+# Parse and translate a query
+uv run python scripts/dev/check_query.py "mydb.users.get_table()"
+
+# Inspect the combined grammar
+uv run python scripts/dev/inspect_grammar.py
+
+# Validate a module implementation
+uv run python scripts/dev/validate_module.py standard.postgresql
+```
+
+---
+
+## Contributing
+
+`uqal-core` is maintained by the core team. See [CONTRIBUTING](https://uqal-lang.github.io/uqal-docs/contributing) for the development workflow.
+
+To contribute a new database module, head to [uqal-lang/uqal-modules](https://github.com/uqal-lang/uqal-modules).
+
+---
+
+## License
+
+[MIT](LICENSE)

uqal_core-0.1.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| latest (`main`) | ✓ |
+| older releases | ✗ |
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Use GitHub's private vulnerability reporting instead:
+**[Report a vulnerability](https://github.com/uqal-lang/uqal-core/security/advisories/new)**
+
+Please include:
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- A suggested fix if you have one
+
+We will respond within **72 hours** and aim to release a fix within **14 days** depending on severity.

uqal_core-0.1.0/hr_schema.uqal

@@ -0,0 +1 @@
+uqal_hr.sql("SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = 'public' ORDER BY table_name, ordinal_position")

uqal_core-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "uqal-core"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.4.2",
+    "lark>=1.3.1",
+    "neo4j>=6.2.0",
+    "prompt-toolkit>=3.0.52",
+    "psycopg2-binary>=2.9.12",
+    "pymongo>=4.17.0",
+    "textual>=8.2.8",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uqal_core"]
+
+[project.scripts]
+uqal = "uqal_core.cli.main:cli"
+
+[tool.pytest.ini_options]
+addopts = "-v --tb=short --cov=src/uqal_core --cov-report=term-missing --cov-report=html:tests/coverage_html"
+testpaths = ["tests"]
+log_cli = true
+log_cli_level = "INFO"
+log_file = "tests/logs/test_results.log"
+log_file_level = "INFO"
+log_file_format = "%(asctime)s %(levelname)s %(message)s"
+log_file_date_format = "%Y-%m-%d %H:%M:%S"
+markers = [
+    "unit: fast isolated tests with no external dependencies",
+    "integration: tests combining multiple components",
+    "e2e: full end-to-end workflow tests",
+]

uqal_core-0.1.0/scripts/dev/check_query.py

@@ -0,0 +1,102 @@
+"""
+Parse and translate a UQAL query — shows the parse tree, AST nodes,
+and the translated native query output.
+
+Useful for testing module translation during development without
+needing a real database connection.
+
+Usage:
+    uv run python scripts/dev/check_query.py "mydb.users.get_table()"
+    uv run python scripts/dev/check_query.py "mydb.users.get_table(where active = true, fields id, name)"
+    uv run python scripts/dev/check_query.py "let x = 1 + 2  output x"
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+
+def header(title: str) -> None:
+    print(f"\n\033[1;34m{'─' * 60}\033[0m")
+    print(f"\033[1;34m  {title}\033[0m")
+    print(f"\033[1;34m{'─' * 60}\033[0m")
+
+
+def check_query(query: str, module_names: list[str] | None = None) -> None:
+    from uqal_core.module_loader import ModuleLoader
+    from uqal_core.registry.module_registry import ModuleRegistry
+    from uqal_core.parser.grammar_builder import GrammarBuilder
+    from uqal_core.ast.transformer import UQALTransformer
+
+    modules_to_load = module_names or ["standard.postgresql", "standard.mongodb", "standard.neo4j"]
+
+    registry = ModuleRegistry()
+    loader = ModuleLoader(registry=registry)
+    loader.load(modules_to_load)
+
+    # Use all registered modules (includes transitive dependencies)
+    loaded_modules = [registry.get_module(m) for m in registry.list_modules()]
+
+    builder = GrammarBuilder()
+    parser = builder.build(loaded_modules)
+    transformer = UQALTransformer()
+
+    header("Input query")
+    print(f"  {query}")
+
+    header("Parse tree")
+    try:
+        tree = parser.parse(query)
+        print(tree.pretty())
+    except Exception as e:
+        print(f"\033[91m  ✗ Parse failed: {e}\033[0m")
+        return
+
+    header("AST nodes")
+    try:
+        program = transformer.transform(tree)
+        for i, stmt in enumerate(program.statements):
+            print(f"  [{i}] {type(stmt).__name__}: {stmt}")
+    except Exception as e:
+        print(f"\033[91m  ✗ Transform failed: {e}\033[0m")
+        return
+
+    header("Translation")
+    try:
+        for i, stmt in enumerate(program.statements):
+            # Find the module that handles this statement
+            for module in loaded_modules:
+                try:
+                    result = module.translate(stmt)
+                    if result is not None:
+                        query_str, params = result
+                        print(f"  Module:  {module.get_manifest().name}")
+                        print(f"  Query:   {query_str}")
+                        if params:
+                            print(f"  Params:  {params}")
+                        break
+                except (NotImplementedError, AttributeError):
+                    continue
+    except Exception as e:
+        print(f"  (translation not available for this statement type: {e})")
+
+    print()
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: uv run python scripts/dev/check_query.py \"<query>\"")
+        print("       uv run python scripts/dev/check_query.py \"<query>\" --module standard.neo4j")
+        sys.exit(1)
+
+    query = sys.argv[1]
+    modules = None
+
+    if "--module" in sys.argv:
+        idx = sys.argv.index("--module")
+        modules = sys.argv[idx + 1:]
+
+    check_query(query, modules)

uqal_core-0.1.0/scripts/dev/inspect_grammar.py

@@ -0,0 +1,80 @@
+"""
+Print the complete combined UQAL grammar for all (or selected) modules.
+Useful for debugging grammar rules, extension points, and conflicts.
+
+Usage:
+    uv run python scripts/dev/inspect_grammar.py
+    uv run python scripts/dev/inspect_grammar.py standard.neo4j
+    uv run python scripts/dev/inspect_grammar.py standard.postgresql standard.neo4j
+    uv run python scripts/dev/inspect_grammar.py --extension-points
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+_EXTENSION_POINTS = [
+    "condition",
+    "expr",
+    "statement",
+    "db_call",
+]
+
+
+def inspect_grammar(module_names: list[str], show_extension_points: bool = False) -> None:
+    from uqal_core.module_loader import ModuleLoader
+    from uqal_core.registry.module_registry import ModuleRegistry
+    from uqal_core.parser.grammar_builder import GrammarBuilder
+
+    registry = ModuleRegistry()
+    loader = ModuleLoader(registry=registry)
+    loader.load(module_names)
+    loaded = [registry.get_module(m) for m in module_names if registry.get_module(m)]
+
+    builder = GrammarBuilder()
+
+    if show_extension_points:
+        print("\n\033[1;34mExtension points and their contributors:\033[0m\n")
+        for point in _EXTENSION_POINTS:
+            contributors = []
+            for module in loaded:
+                caps = module.get_capabilities()
+                exts = getattr(caps, "grammar_extensions", {})
+                rules = exts.get(point, [])
+                if rules:
+                    contributors.append(f"{module.get_manifest().name}: {rules}")
+            if contributors:
+                print(f"  \033[33m{point}\033[0m")
+                for c in contributors:
+                    print(f"    → {c}")
+            else:
+                print(f"  \033[90m{point}  (no extensions)\033[0m")
+        print()
+        return
+
+    print(f"\n\033[1;34mLoaded modules: {[m.get_manifest().name for m in loaded]}\033[0m\n")
+
+    try:
+        grammar_text = builder.get_combined_grammar(loaded)
+        print(grammar_text)
+    except AttributeError:
+        # Fallback: build and show what we can
+        parser = builder.build(loaded)
+        print("(Grammar built successfully — source text not directly accessible)")
+        print(f"\nParser type: {type(parser)}")
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+
+    show_ext_points = "--extension-points" in args
+    if show_ext_points:
+        args = [a for a in args if a != "--extension-points"]
+
+    if not args:
+        args = ["standard.postgresql", "standard.mongodb", "standard.neo4j"]
+
+    inspect_grammar(args, show_extension_points=show_ext_points)