rtgl 0.0.3__tar.gz

rtgl-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksii Kolesnichenko
+
+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.

rtgl-0.0.3/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: rtgl
+Version: 0.0.3
+Summary: RTGL: A framework providing a Relational Task Generation Language for Relational Deep Learning
+Keywords: relational-task-generation-language,predictive-query-language,sql,relational-deep-learning,deep-learning,relational-learning,machine-learning,temporal-data,task-generation
+Author-email: Oleksii Kolesnichenko <oleksii.kolesnichenko@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: antlr4-python3-runtime>=4.13.2
+Requires-Dist: duckdb>=1.0.0
+Requires-Dist: rtgl[test] ; extra == "dev"
+Requires-Dist: rtgl[notebook] ; extra == "dev"
+Requires-Dist: antlr4-tools>=0.2.1 ; extra == "dev"
+Requires-Dist: relbench>=1.1.0 ; extra == "dev"
+Requires-Dist: tqdm>=4.66.0 ; extra == "dev"
+Requires-Dist: ruff>=0.14.10 ; extra == "dev"
+Requires-Dist: ipykernel>=7.1.0 ; extra == "notebook"
+Requires-Dist: jupyter>=1.0.0 ; extra == "notebook"
+Requires-Dist: ipywidgets>=8.1.0 ; extra == "notebook"
+Requires-Dist: pytest>=8.0.0 ; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0 ; extra == "test"
+Project-URL: Issues, https://github.com/kolesole/RTGL/issues
+Project-URL: Repository, https://github.com/kolesole/RTGL
+Provides-Extra: dev
+Provides-Extra: notebook
+Provides-Extra: test
+
+# RTGL
+
+**RTGL** (Relational Task Generation Language) is a Python framework for writing compact, expressive predictive queries over relational data, especially for Relational Deep Learning.
+
+It lets you write shorter, more expressive queries by abstracting temporal joins and complex aggregations.
+
+## 🧠 Features
+
+- 🎯 **ANTLR-based Parser** 
+  - Lexer and parser for RTGL syntax
+
+- 🌳 **Structured parse-tree visitor**
+  - Converts parsed queries into normalized dictionaries with source positions.
+
+- 🔍 **Semantic validation**
+  - Schema-aware query validation with error reporting.
+
+- 🔀 **Two converters**
+  - 📌 `SConverter` for static prediction queries.
+  - ⏰ `TConverter` for temporal prediction queries with timestamp windows.
+
+- ⚙️ **Dual output mode**
+  - `execute=False` returns generated SQL.
+  - `execute=True` executes SQL and returns a `Table` object.
+
+## ⚙️ Installation
+
+Install RTGL via pip:
+
+```bash
+pip install rtgl
+```
+
+## 🚀 Quickstart
+
+### 1. Build your database as [RelBench](https://github.com/snap-stanford/relbench) `Database` object or use simplified RTGL version 
+
+```python
+# path to classes
+from rtgl.base import Database, Table
+```
+
+### 2. Static query with `SConverter`
+
+```python
+from rtgl.converter import SConverter
+
+converter = SConverter(db)
+
+rtgl_query = """
+    PREDICT COUNT_DISTINCT(votes.* 
+        WHERE votes.votetypeid == 2)
+    FOR EACH posts.* WHERE posts.PostTypeId == 1
+                       AND posts.OwnerUserId IS NOT NULL
+                       AND posts.OwnerUserId != -1;
+"""
+
+# SQL only
+sql_query = converter.convert(rtgl_query, execute=False)
+
+# execute and get Table(fk, label)
+table = converter.convert(rtgl_query, execute=True)
+```
+
+### 3. Temporal query with `TConverter`
+
+```python
+import pandas as pd
+from rtgl.converter import TConverter
+
+timestamps = pd.Series(...) # define timestamps for which prediction must be made
+converter = TConverter(db, timestamps)
+
+# also, it is possible to update prediction timestamps later without recreating converter
+converter.set_timestamps(new_timestamps)
+
+rtgl_query = """
+    PREDICT COUNT_DISTINCT(votes.* 
+        WHERE votes.votetypeid == 2, 0, 91, DAYS)
+    FOR EACH posts.* WHERE posts.PostTypeId == 1
+                       AND posts.OwnerUserId IS NOT NULL
+                       AND posts.OwnerUserId != -1;
+"""
+
+# SQL only
+sql_query = converter.convert(rtgl_query, execute=False)
+
+# execute and get Table(fk, timestamp, label)
+table = converter.convert(rtgl_query, execute=True)
+```
+
+### 4. Examples
+
+For more comprehensive examples and use cases, check out the [`relbench_exp.ipynb`](./experiments/relbench_exp.ipynb) notebook.  
+You can also check the [`rtgl-tasks`](https://github.com/kolesole/rtgl-tasks) repository for more tasks.
+
+## 📐 Query Language
+
+### 📌 Static query design
+
+```sql
+PREDICT <aggregation | expression | table.column> [RANK TOP K | CLASSIFY]
+FOR EACH <entity_table>.<primary_key>
+[WHERE <static_condition | static_nested_expression>];
+```
+
+### ⏰ Temporal query shape
+
+```sql
+PREDICT <aggregation | temporal_expression> [RANK TOP K | CLASSIFY]
+FOR EACH <entity_table>.<primary_key> [WHERE <static_condition | static_nested_expression>]
+[ASSUMING <temporal_condition | temporal_nested_expression>]
+[WHERE <temporal_condition | temporal_nested_expression>];
+```
+
+### 🧮 Aggregations
+
+| Function | Meaning | Condition-Compatible |
+| :--- | :--- | :--- |
+| `AVG` | average | ✅ |
+| `MAX` | maximum | ✅ |
+| `MIN` | minimum | ✅ |
+| `SUM` | sum | ✅ |
+| `COUNT` | non-null count | ✅ |
+| `COUNT_DISTINCT` | distinct count | ✅ |
+| `FIRST` | earliest value by time | ✅ |
+| `LAST` | latest value by time | ✅ |
+| `LIST_DISTINCT` | list of distinct values | ❌ |
+
+### 🧭 Temporal window rules
+
+- Window format: `<start>, <end>, <measure_unit>`.
+- Supported units: `YEARS`, `MONTHS`, `WEEKS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS`.
+- Window semantics are half-open: `(start, end]`.
+- `PREDICT`/`WHERE`: `start` and `end` must be non-negative.
+- `ASSUMING`: `start` and `end` must be non-positive.
+- `start` must be strictly less than `end`.
+
+## 🏗️ Architecture
+
+```text
+RTGL Query String
+    ↓
+[Lexer] -> Tokens
+    ↓
+[Parser] -> Parse Tree
+    ↓
+[Visitor] -> Structured Dictionary
+    ↓
+[Validator] -> Semantic Checks
+    ↓
+[Converter] -> SQL Query
+    ↓ (optional execute=True)
+[DuckDB] -> Result Table
+```
+
+## 🔧 Development
+
+### Install uv
+
+- macOS & Linux
+
+```bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
+
+- Windows
+
+```bash
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Install dependencies
+
+```bash
+uv sync --all-extras
+```
+
+### Regenerate parser files
+
+If you modify lexer or parser grammar files (`*.g4`), regenerate ANTLR outputs from the repo root:
+
+```bash
+./regenerate_parser.sh
+```
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Run linter
+
+```bash
+ruff check .
+```
+

rtgl-0.0.3/README.md

@@ -0,0 +1,197 @@
+# RTGL
+
+**RTGL** (Relational Task Generation Language) is a Python framework for writing compact, expressive predictive queries over relational data, especially for Relational Deep Learning.
+
+It lets you write shorter, more expressive queries by abstracting temporal joins and complex aggregations.
+
+## 🧠 Features
+
+- 🎯 **ANTLR-based Parser** 
+  - Lexer and parser for RTGL syntax
+
+- 🌳 **Structured parse-tree visitor**
+  - Converts parsed queries into normalized dictionaries with source positions.
+
+- 🔍 **Semantic validation**
+  - Schema-aware query validation with error reporting.
+
+- 🔀 **Two converters**
+  - 📌 `SConverter` for static prediction queries.
+  - ⏰ `TConverter` for temporal prediction queries with timestamp windows.
+
+- ⚙️ **Dual output mode**
+  - `execute=False` returns generated SQL.
+  - `execute=True` executes SQL and returns a `Table` object.
+
+## ⚙️ Installation
+
+Install RTGL via pip:
+
+```bash
+pip install rtgl
+```
+
+## 🚀 Quickstart
+
+### 1. Build your database as [RelBench](https://github.com/snap-stanford/relbench) `Database` object or use simplified RTGL version 
+
+```python
+# path to classes
+from rtgl.base import Database, Table
+```
+
+### 2. Static query with `SConverter`
+
+```python
+from rtgl.converter import SConverter
+
+converter = SConverter(db)
+
+rtgl_query = """
+    PREDICT COUNT_DISTINCT(votes.* 
+        WHERE votes.votetypeid == 2)
+    FOR EACH posts.* WHERE posts.PostTypeId == 1
+                       AND posts.OwnerUserId IS NOT NULL
+                       AND posts.OwnerUserId != -1;
+"""
+
+# SQL only
+sql_query = converter.convert(rtgl_query, execute=False)
+
+# execute and get Table(fk, label)
+table = converter.convert(rtgl_query, execute=True)
+```
+
+### 3. Temporal query with `TConverter`
+
+```python
+import pandas as pd
+from rtgl.converter import TConverter
+
+timestamps = pd.Series(...) # define timestamps for which prediction must be made
+converter = TConverter(db, timestamps)
+
+# also, it is possible to update prediction timestamps later without recreating converter
+converter.set_timestamps(new_timestamps)
+
+rtgl_query = """
+    PREDICT COUNT_DISTINCT(votes.* 
+        WHERE votes.votetypeid == 2, 0, 91, DAYS)
+    FOR EACH posts.* WHERE posts.PostTypeId == 1
+                       AND posts.OwnerUserId IS NOT NULL
+                       AND posts.OwnerUserId != -1;
+"""
+
+# SQL only
+sql_query = converter.convert(rtgl_query, execute=False)
+
+# execute and get Table(fk, timestamp, label)
+table = converter.convert(rtgl_query, execute=True)
+```
+
+### 4. Examples
+
+For more comprehensive examples and use cases, check out the [`relbench_exp.ipynb`](./experiments/relbench_exp.ipynb) notebook.  
+You can also check the [`rtgl-tasks`](https://github.com/kolesole/rtgl-tasks) repository for more tasks.
+
+## 📐 Query Language
+
+### 📌 Static query design
+
+```sql
+PREDICT <aggregation | expression | table.column> [RANK TOP K | CLASSIFY]
+FOR EACH <entity_table>.<primary_key>
+[WHERE <static_condition | static_nested_expression>];
+```
+
+### ⏰ Temporal query shape
+
+```sql
+PREDICT <aggregation | temporal_expression> [RANK TOP K | CLASSIFY]
+FOR EACH <entity_table>.<primary_key> [WHERE <static_condition | static_nested_expression>]
+[ASSUMING <temporal_condition | temporal_nested_expression>]
+[WHERE <temporal_condition | temporal_nested_expression>];
+```
+
+### 🧮 Aggregations
+
+| Function | Meaning | Condition-Compatible |
+| :--- | :--- | :--- |
+| `AVG` | average | ✅ |
+| `MAX` | maximum | ✅ |
+| `MIN` | minimum | ✅ |
+| `SUM` | sum | ✅ |
+| `COUNT` | non-null count | ✅ |
+| `COUNT_DISTINCT` | distinct count | ✅ |
+| `FIRST` | earliest value by time | ✅ |
+| `LAST` | latest value by time | ✅ |
+| `LIST_DISTINCT` | list of distinct values | ❌ |
+
+### 🧭 Temporal window rules
+
+- Window format: `<start>, <end>, <measure_unit>`.
+- Supported units: `YEARS`, `MONTHS`, `WEEKS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS`.
+- Window semantics are half-open: `(start, end]`.
+- `PREDICT`/`WHERE`: `start` and `end` must be non-negative.
+- `ASSUMING`: `start` and `end` must be non-positive.
+- `start` must be strictly less than `end`.
+
+## 🏗️ Architecture
+
+```text
+RTGL Query String
+    ↓
+[Lexer] -> Tokens
+    ↓
+[Parser] -> Parse Tree
+    ↓
+[Visitor] -> Structured Dictionary
+    ↓
+[Validator] -> Semantic Checks
+    ↓
+[Converter] -> SQL Query
+    ↓ (optional execute=True)
+[DuckDB] -> Result Table
+```
+
+## 🔧 Development
+
+### Install uv
+
+- macOS & Linux
+
+```bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
+
+- Windows
+
+```bash
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Install dependencies
+
+```bash
+uv sync --all-extras
+```
+
+### Regenerate parser files
+
+If you modify lexer or parser grammar files (`*.g4`), regenerate ANTLR outputs from the repo root:
+
+```bash
+./regenerate_parser.sh
+```
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Run linter
+
+```bash
+ruff check .
+```

rtgl-0.0.3/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["flit_core>=3.4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "rtgl"
+version = "0.0.3"
+description = "RTGL: A framework providing a Relational Task Generation Language for Relational Deep Learning"
+authors = [{ name = "Oleksii Kolesnichenko", email = "oleksii.kolesnichenko@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+    "relational-task-generation-language",
+    "predictive-query-language",
+    "sql",
+    "relational-deep-learning",
+    "deep-learning",
+    "relational-learning",
+    "machine-learning",
+    "temporal-data",
+    "task-generation"
+]
+dependencies = [
+    "pandas>=2.2.0",
+    "antlr4-python3-runtime>=4.13.2",
+    "duckdb>=1.0.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0"
+]
+notebook = [
+    "ipykernel>=7.1.0",
+    "jupyter>=1.0.0",
+    "ipywidgets>=8.1.0"
+]
+dev = [
+    "rtgl[test]",
+    "rtgl[notebook]",
+    "antlr4-tools>=0.2.1",
+    "relbench>=1.1.0",
+    "tqdm>=4.66.0",
+    "ruff>=0.14.10"
+]
+
+[project.urls]
+Repository = "https://github.com/kolesole/RTGL"
+Issues = "https://github.com/kolesole/RTGL/issues"
+
+[tool.ruff]
+line-length = 121
+target-version = "py312"
+extend-exclude = ["experiments", "showcase", "tasks", "tests", "rtgl/parser/gen/**",]
+
+[tool.ruff.lint]
+select = [
+    "B",    # flake8-bugbear
+    "D",    # pydocstyle
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "SIM",  # flake8-simplify
+    "UP",   # pyupgrade
+    "W",    # pycodestyle warnings
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rtgl-0.0.3/rtgl/__init__.py

@@ -0,0 +1,9 @@
+"""RTGL: A Framework for Relational Task Generation Language."""
+
+from rtgl import base
+from rtgl import converter
+from rtgl import parser
+from rtgl import validator
+from rtgl import visitor
+
+__all__ = ["base", "converter", "parser", "validator", "visitor"]

rtgl-0.0.3/rtgl/base/__init__.py

@@ -0,0 +1,6 @@
+"""Database representation module for RTGL."""
+
+from rtgl.base.database import Database
+from rtgl.base.table import Table
+
+__all__ = ["Database", "Table"]

rtgl-0.0.3/rtgl/base/database.py

@@ -0,0 +1,57 @@
+"""Database class to hold multiple tables."""
+
+from functools import cached_property
+
+import pandas as pd
+
+from rtgl.base.table import Table
+
+
+class Database:
+    r"""Represents a database containing multiple related tables.
+
+    The *`Database`* class stores a collection of *`Table`* objects and provides
+    a representation method for displaying all tables in the database.
+    """
+
+    def __init__(self, table_dict: dict[str, Table]) -> None:
+        r"""Initializes *`Database`* with a dictionary of tables.
+
+        Args:
+            table_dict (dict[str, Table]): Dictionary where keys are table
+            names and values are Table objects.
+
+        Returns:
+            out (None):
+        """
+        self.table_dict = table_dict
+
+    def __repr__(self) -> str:
+        r"""Returns a string representation of the database.
+
+        Returns:
+            out (str): Formatted string showing all tables in the database.
+        """
+        return "================= Database ================\n" + "".join(
+            f"Table Name: {name}\n{table}\n" for name, table in self.table_dict.items()
+        )
+
+    @cached_property
+    def min_timestamp(self) -> pd.Timestamp | None:
+        r"""Returns the minimum timestamp across all tables in the database, if any time columns exist.
+
+        Returns:
+            min_timestamp (pd.Timestamp | None): Minimum timestamp across all tables, or None if no time columns.
+        """
+        min_timestamps = [table.min_timestamp for table in self.table_dict.values() if table.time_col]
+        return min(min_timestamps) if min_timestamps else None
+
+    @cached_property
+    def max_timestamp(self) -> pd.Timestamp | None:
+        r"""Returns the maximum timestamp across all tables in the database, if any time columns exist.
+
+        Returns:
+            max_timestamp (pd.Timestamp | None): Maximum timestamp across all tables, or None if no time columns.
+        """
+        max_timestamps = [table.max_timestamp for table in self.table_dict.values() if table.time_col]
+        return max(max_timestamps) if max_timestamps else None

rtgl-0.0.3/rtgl/base/table.py

@@ -0,0 +1,65 @@
+"""Table class representing a database table with metadata."""
+
+from functools import cached_property
+
+import pandas as pd
+
+
+class Table:
+    r"""Represents a database table with its data and relational metadata.
+
+    The *`Table`* class encapsulates a pandas DataFrame along with metadata about
+    primary keys, foreign keys, and temporal columns.
+    """
+
+    def __init__(
+        self, df: pd.DataFrame, fkey_col_to_pkey_table: dict[str, str] = None, pkey_col: str = None, time_col: str = None
+    ) -> None:
+        r"""Initializes *`Table`* with data and metadata.
+
+        Args:
+            df (pd.DataFrame): The table data.
+            fkey_col_to_pkey_table (dict, optional): Dictionary mapping foreign key column names to parent table names.
+                    Default = None.
+            pkey_col (str, optional): Primary key column name.
+                    Default = None.
+            time_col (str, optional): Timestamp column name for temporal tables.
+                    Default = None.
+        """
+        self.df = df
+        self.fkey_col_to_pkey_table = fkey_col_to_pkey_table
+        self.pkey_col = pkey_col
+        self.time_col = time_col
+
+    def __repr__(self) -> str:
+        r"""Returns a string representation of the table.
+
+        Returns:
+            out (str): Formatted string showing *`DataFrame`* and all metadata.
+        """
+        return (
+            "------------------ Table ------------------\n"
+            f"DataFrame:\n{self.df}\n"
+            f"Foreign Key Columns to Primary Key Tables: {self.fkey_col_to_pkey_table}\n"
+            f"Primary Key Column: {self.pkey_col}\n"
+            f"Time Column: {self.time_col}\n"
+            "-------------------------------------------"
+        )
+
+    @cached_property
+    def min_timestamp(self) -> pd.Timestamp | None:
+        r"""Returns the minimum timestamp in the time column, if it exists.
+
+        Returns:
+            min_timestamp (pd.Timestamp | None): Minimum timestamp in the time column, or None if no time column.
+        """
+        return self.df[self.time_col].min() if self.time_col else None
+
+    @cached_property
+    def max_timestamp(self) -> pd.Timestamp | None:
+        r"""Returns the maximum timestamp in the time column, if it exists.
+
+        Returns:
+            max_timestamp (pd.Timestamp) | None: Maximum timestamp in the time column, or None if no time column.
+        """
+        return self.df[self.time_col].max() if self.time_col else None

rtgl-0.0.3/rtgl/converter/__init__.py

@@ -0,0 +1,7 @@
+"""Converter modules for RTGL to SQL translation."""
+
+from rtgl.converter.converter import Converter
+from rtgl.converter.static_converter import SConverter
+from rtgl.converter.temporal_converter import TConverter
+
+__all__ = ["Converter", "SConverter", "TConverter"]