add paper and figure to doc

Author: FeiYang73

.gitignore

@@ -1,5 +1,53 @@
-*.code-workspace
-*.egg-info/
+# Python
 __pycache__/
 *.py[cod]
-*$py.class
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# IDE
+*.code-workspace
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Documentation
+docs/_build/
+docs/build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.png
+!docs/source/_static/*.png
+!docs/source/_static/*.jpg

LICENSE

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

README.md

@@ -1,6 +1,8 @@
 <div align="center">
 
-# TLSQL: SQL-like API for Table Learning 
+# TLSQL: SQL-like API for Table Learning
+
+ 
 
 *A Python library that converts custom SQL-like statements into standard SQL queries for machine learning workflows on tables in modern data management systems.*
 
@@ -9,90 +11,93 @@
 [![Python](https://img.shields.io/badge/Python-3.8+-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
 [![Documentation](https://img.shields.io/badge/Documentation-latest-blue?style=flat-square)](https://tlsql.readthedocs.io/en/latest/index.html)
+[![Paper](https://img.shields.io/badge/Paper-arXiv:2601.14109-b31b1b?style=flat-square)](https://arxiv.org/abs/2601.14109)
 
 
 ---
 
 </div>
 
 ## About
-
-TLSQL simplifies machine learning on structured tables by converting SQL-like statements into standard SQL queries. This allows data scientists and engineers to focus on modeling rather than writing complex SQL or managing datasets manually.
-
-TLSQL supports three types of statements that map directly to ML workflows:
-
-- **`TRAIN WITH`**: Specifies the training set
-- **`PREDICT VALUE`**: Specifies the test set
-- **`VALIDATE WITH`**: Specifies the validation set
+TLSQL is a system designed to simplify machine learning workflows on structured tabular data. It translates SQL-like statements into standard SQL queries and structured learning task descriptions, enabling data scientists and engineers to focus on model development instead of writing complex SQL or manually managing datasets.
 
 TLSQL works seamlessly with **RDBs, data warehouses, and data lakes**, enabling end-to-end table-based ML workflows.
 
+- **`PREDICT VALUE`**: Specifies the test set.
+- **`TRAIN WITH`**: Specifies the training set.
+- **`VALIDATE WITH`**: Specifies the validation set.
+
+<div align="center">
+  <img src="docs/source/_static/workflow.jpg" alt="TLSQL Workflow" width="600"/>
+  <br/>
+  <small><strong>The TLSQL Workflow</strong></small>
+</div>
 
 ## TLSQL Syntax
 
-### 1. TRAIN WITH Statement
+### 1. PREDICT VALUE Statement
 
-The `TRAIN WITH` statement specifies which columns and tables to use for training data, along with optional filtering conditions. This statement defines the dataset used to train your machine learning model.
+The `PREDICT VALUE` statement specifies the target column for prediction and the task type (classification or regression). This statement defines the test set - the data for which you want to make predictions. The `WHERE` clause in this statement filters which rows are included in the test set.
 
 #### Syntax
 
 ```sql
-TRAIN WITH (column_selectors)
-FROM table1, table2, ...
+PREDICT VALUE(column_selector, TASK_TYPE)
+FROM table
 [WHERE conditions]
 ```
 
+#### Task Types
+
+- **`CLF`**: Classification task - predicts discrete categories
+- **`REG`**: Regression task - predicts continuous values
+
 #### Examples
 
 ```sql
-TRAIN WITH (users.*, movies.*, ratings.*)
-FROM users, movies, ratings
-WHERE users.Gender='M' AND movies.Year >= 2000
+PREDICT VALUE(users.Age, CLF)
+FROM users
+WHERE users.Gender='F' 
 ```
 
-### 2. PREDICT VALUE Statement
+### 2. TRAIN WITH Statement
 
-The `PREDICT VALUE` statement specifies the target column for prediction and the task type (classification or regression). This statement defines the test set - the data for which you want to make predictions. The `WHERE` clause in this statement filters which rows are included in the test set.
+The `TRAIN WITH` statement specifies which columns and tables to use for training data, along with optional filtering conditions. This statement defines the dataset used to train your machine learning model.
 
 #### Syntax
 
 ```sql
-PREDICT VALUE(table.column, TASK_TYPE)
-FROM table
+TRAIN WITH column_selector
+FROM table1, table2, ...
 [WHERE conditions]
 ```
 
-#### Task Types
-
-- **`CLF`**: Classification task - predicts discrete categories
-- **`REG`**: Regression task - predicts continuous values
-
 #### Examples
 
 ```sql
-PREDICT VALUE(users.Age, CLF)
-FROM users
-WHERE users.Gender='F' OR users.userID IN (1,2,3,4,5)
+TRAIN WITH (users.*, movies.*, ratings.*)
+FROM users, movies, ratings
+WHERE users.Gender='M' AND users.userID<3000
 ```
 
 ### 3. VALIDATE WITH Statement
 
-The `VALIDATE WITH` statement specifies validation data with the same syntax as `TRAIN WITH`. This statement defines the validation set used for model selection. If omitted, the pipeline will use k-fold cross-validation on the training data.
+The `VALIDATE WITH` statement specifies validation data with the same syntax as `TRAIN WITH`. This statement defines the validation set used for model selection. If omitted, `validate_result` will be `None`.
 
 #### Syntax
 
 ```sql
-VALIDATE WITH (column_selectors)
-FROM table1, table2, ...
+VALIDATE WITH column_selector
+FROM table
 [WHERE conditions]
 ```
 
 #### Examples
 
 ```sql
-VALIDATE WITH (users.*, movies.*, ratings.*)
-FROM users, movies, ratings
-WHERE users.Gender='M' AND movies.Year < 2000
+VALIDATE WITH (users.Age)
+FROM users
+WHERE users.Gender='M' and users.userID>3000
 ```
 
 ## Supported Operators
@@ -125,11 +130,14 @@ This will install TLSQL in development mode, allowing you to make changes to the
 ```python
 import tlsql
 
-
-result = tlsql.convert("PREDICT VALUE(users.Age, CLF) FROM users")
-print(result.statement_type)  # 'PREDICT'
-print(result.target_column)   # 'users.Age'
-print(result.task_type)       # 'CLF'
+# Workflow mode: PREDICT only (auto-generates TRAIN)
+result = tlsql.convert(
+    predict_query="PREDICT VALUE(users.Age, CLF) FROM users WHERE users.Gender='F'"
+)
+print(result.predict.statement_type)  # 'PREDICT'
+print(result.predict.target_column)   # 'users.Age'
+print(result.predict.task_type)       # 'CLF'
+print(result.train.sql)                # Auto-generated TRAIN SQL
 ```
 
 ### Examples
@@ -145,3 +153,14 @@ Check out the examples directory for more usage examples:
 
 
 
+### Citation
+
+```
+@article{chen2026tlsql,
+  title={TLSQL: Table Learning Structured Query Language},
+  author={Chen, Feiyang and Zhong, Ken and Zhang, Aoqian and Wang, Zheng and Pan, Li and Li, Jianhua},
+  journal={arXiv preprint arXiv:2601.14109},
+  year={2026}
+}
+```
+**Paper Link**: [arXiv:2601.14109](https://arxiv.org/abs/2601.14109)

__init__.py

@@ -1,52 +1,82 @@
 """TLSQL: A SQL-like language designed for relational table learning tasks and workflows.
 
-This package converts three types of custom SQL statements into standard SQL:
-1. TRAIN WITH - Training data queries
-2. PREDICT VALUE - Prediction target queries
-3. VALIDATE WITH - Validation data queries
+This package converts TLSQL workflow statements into standard SQL:
+- PREDICT VALUE: Prediction target queries (required)
+- TRAIN WITH: Training data queries (optional, auto-generated if not provided)
+- VALIDATE WITH: Validation data queries (optional)
 
 Usage:
     >>> from tlsql import convert
-    >>> result = convert("PREDICT VALUE(users.Age, CLF) FROM users")
-    >>> print(result.sql_list)  # List of GeneratedSQL objects
+    >>> result = convert(
+    ...     predict_query="PREDICT VALUE(users.Age, CLF) FROM users WHERE users.Gender='F'"
+    ... )
+    >>> print(result.predict.sql)
+    >>> print(result.train.sql)
 """
 
+from typing import Optional
+from tlsql.tlsql.sql_generator import SQLGenerator, ConversionResult
 __version__ = "0.1.0"
 __author__ = "TLSQL Team"
 
 
-def convert(tlsql: str):
-    """Convert TLSQL statement to standard SQL.
+def convert(
+    predict_query: str,
+    train_query: Optional[str] = None,
+    validate_query: Optional[str] = None
+) -> ConversionResult:
+    """Convert TLSQL workflow statements to standard SQL.
 
-    This is the main entry point for TLSQL conversion.
+    Converts PREDICT, TRAIN, and VALIDATE TLSQL statements into standard SQL.
+    PREDICT is required. If TRAIN is not provided, it will be auto-generated
+    by excluding PREDICT data from the same table.
 
     Args:
-        tlsql: TLSQL statement string.
+        predict_query: PREDICT TLSQL statement (required).
+        train_query: TRAIN TLSQL statement (optional, auto-generated if not provided).
+        validate_query: VALIDATE TLSQL statement (optional).
 
     Returns:
-        ConversionResult: Unified result containing statement type and all metadata.
+        ConversionResult: Contains predict_result, train_result, and validate_result.
 
     """
-    from tlsql.tlsql.parser import Parser
-    from tlsql.tlsql.sql_generator import SQLGenerator
 
-    # Parse the TLSQL statement
-    parser = Parser(tlsql)
-    ast = parser.parse()
+    if not predict_query or not predict_query.strip():
+        raise ValueError("predict_query is required.")
 
-    # Generate SQL with metadata
     generator = SQLGenerator()
-    return generator.build(ast)
+
+    # Process PREDICT
+    predict_result = SQLGenerator.convert_query(predict_query)
+
+    # Process TRAIN
+    train_result = (
+        SQLGenerator.convert_query(train_query)
+        if train_query and train_query.strip()
+        else generator.auto_generate_train(predict_result)
+    )
+
+    # Process VALIDATE
+    validate_result = (
+        SQLGenerator.convert_query(validate_query)
+        if validate_query and validate_query.strip()
+        else None
+    )
+
+    return ConversionResult(
+        predict_result=predict_result,
+        train_result=train_result,
+        validate_result=validate_result
+    )
 
 
 # Tokens
 from tlsql.tlsql.tokens import Token, TokenType
 
-# Core classes (re-exported for convenience)
+# Core classes
 from tlsql.tlsql.lexer import Lexer
 from tlsql.tlsql.parser import Parser
 from tlsql.tlsql.sql_generator import (
-    SQLGenerator,
     GeneratedSQL,
     ConversionResult,
 )

docs/source/_static/custom.css

@@ -1316,6 +1316,28 @@ dl.py.method > dt + dd {
     line-height: 1.6 !important;
 }
 
+/* Hide list markers in field list (Parameters, Returns, etc.) */
+.field-list dd ul,
+.field-list dd ol,
+.field-list ul,
+.field-list ol {
+    list-style: none !important;
+    padding-left: 0 !important;
+    margin-left: 0 !important;
+}
+
+.field-list dd li::marker,
+.field-list li::marker {
+    content: none !important;
+}
+
+.field-list dd li,
+.field-list li {
+    list-style: none !important;
+    padding-left: 0 !important;
+    margin-left: 0 !important;
+}
+
 /* Spacing for paragraphs inside field list */
 .field-list dd p {
     margin-bottom: 0.5em !important;