Expose ProllyTree SQL API to Python and Add Chronological LangGraph TA-RAG Example (#87)

* Expose ProllyTree SQL API to Python

  Summary

  This PR adds complete SQL functionality to the ProllyTree Python bindings, allowing users to
  execute SQL queries on the versioned key-value store through a new ProllySQLStore class.

  Changes

  Core Implementation

  - Added ProllySQLStore Python class (src/python.rs)
    - Full SQL query execution via GlueSQL
    - Multiple output formats: dict, tuples, JSON, CSV
    - Helper methods for common operations (create_table, insert, select)
    - Transaction support with commit functionality

  Python Module Updates

  - Updated python/prollytree/__init__.py
    - Conditionally exports ProllySQLStore when SQL feature is available
    - Graceful fallback when SQL support is not compiled

  Build System Enhancements

  - Enhanced python/build_python.sh
    - Added --with-sql flag to build with SQL support
    - Added --all-features flag for complete feature set
    - Added --help documentation
    - Automatic SQL functionality testing when built with SQL feature
  - Updated pyproject.toml
    - Added SQL feature to default maturin build configuration
    - Allows override via command-line flags

  Storage Layer

  - Added current_commit() method (src/git/versioned_store.rs)
    - Enables retrieving the current HEAD commit ID
    - Required for SQL commit operations

  Documentation & Examples

  - Created comprehensive SQL example (python/examples/sql_example.py)
    - Demonstrates table creation, data insertion, and querying
    - Shows all output formats (dict, tuples, JSON, CSV)
    - Examples of JOINs, GROUP BY, subqueries
    - UPDATE and DELETE operations
  - Added SQL test suite (python/tests/test_sql.py)
    - Tests for all SQL operations
    - Output format validation
    - Complex query testing
    - Static method testing

  API Usage

  from prollytree import ProllySQLStore

  # Initialize store (requires git repository)
  store = ProllySQLStore(path)

  # Create table
  store.create_table("users", [("id", "INTEGER"), ("name", "TEXT")])

  # Insert data
  store.insert("users", [[1, "Alice"], [2, "Bob"]])

  # Query with different formats
  results = store.execute("SELECT * FROM users")  # Returns list of dicts
  labels, rows = store.execute("SELECT * FROM users", format="tuples")
  json_str = store.execute("SELECT * FROM users", format="json")
  csv_str = store.execute("SELECT * FROM users", format="csv")

  # Helper methods
  store.select("users", columns=["name"], where_clause="id > 1")

  # Execute multiple queries
  store.execute_many([query1, query2, query3])

  # Commit changes
  store.commit("Added user data")

  Building with SQL Support

  # Build with SQL support
  ./python/build_python.sh --with-sql

  # Build and install
  ./python/build_python.sh --with-sql --install

  # Run example
  python3 python/examples/sql_example.py

  Testing

  - ✅ All SQL operations tested and working
  - ✅ Example script runs successfully
  - ✅ Multiple output formats validated
  - ✅ Complex queries (JOIN, GROUP BY) functional

  Breaking Changes

  None - SQL support is optional and doesn't affect existing functionality.

  Notes

  - SQL functionality requires git repository initialization
  - Based on GlueSQL, some SQL features may have limitations (e.g., no DISTINCT support)
  - Performance is optimized for versioned operations rather than pure SQL speed

* add sql example to run script

* rename langgraph example

* add langgraph_chronological.py

* add loop

* add more profiles to the example

* remove unused codes

* improve run_example.sh

Author: zhangfengcdt

pyproject.toml

@@ -39,6 +39,7 @@ Repository = "https://github.com/zhangfengcdt/prollytree.git"
 "Bug Tracker" = "https://github.com/zhangfengcdt/prollytree/issues"
 
 [tool.maturin]
-features = ["python"]
+# Default features - can be overridden with --features flag
+features = ["python", "sql"]
 module-name = "prollytree"
 python-source = "python"

python/build_python.sh

@@ -13,9 +13,38 @@
 # limitations under the License.
 
 # Build script for ProllyTree Python bindings
+#
+# Usage:
+#   ./build_python.sh                    # Build with default Python bindings
+#   ./build_python.sh --with-sql         # Build with SQL support
+#   ./build_python.sh --all-features     # Build with all features (Python + SQL)
+#   ./build_python.sh --features "python sql"  # Specify features explicitly
+#   ./build_python.sh --install          # Build and install the package
+#   ./build_python.sh --with-sql --install  # Build with SQL and install
 
 set -e
 
+# Show help if requested
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+    echo "Build script for ProllyTree Python bindings"
+    echo ""
+    echo "Usage:"
+    echo "  ./build_python.sh [OPTIONS]"
+    echo ""
+    echo "Options:"
+    echo "  --with-sql           Build with SQL support"
+    echo "  --all-features       Build with all features (Python + SQL)"
+    echo "  --features FEATURES  Specify features explicitly (e.g., 'python sql')"
+    echo "  --install            Install the built package after building"
+    echo "  --help, -h           Show this help message"
+    echo ""
+    echo "Examples:"
+    echo "  ./build_python.sh                       # Basic Python bindings"
+    echo "  ./build_python.sh --with-sql            # With SQL support"
+    echo "  ./build_python.sh --with-sql --install  # Build and install with SQL"
+    exit 0
+fi
+
 echo "🔧 Building ProllyTree Python bindings..."
 
 # Check if maturin is installed
@@ -27,9 +56,33 @@ fi
 # Change to project root directory
 cd "$(dirname "$0")/.."
 
+# Parse command line arguments for features
+FEATURES="python"
+for arg in "$@"; do
+    case $arg in
+        --features)
+            shift
+            FEATURES="$1"
+            shift
+            ;;
+        --features=*)
+            FEATURES="${arg#*=}"
+            shift
+            ;;
+        --with-sql)
+            FEATURES="python sql"
+            shift
+            ;;
+        --all-features)
+            FEATURES="python sql"
+            shift
+            ;;
+    esac
+done
+
 # Build the wheel
-echo "🍹 Building wheel with maturin..."
-maturin build --release --features python
+echo "🍹 Building wheel with maturin (features: $FEATURES)..."
+maturin build --release --features "$FEATURES"
 
 # Find the built wheel
 WHEEL_PATH=$(find target/wheels -name "prollytree-*.whl" | head -1)
@@ -54,17 +107,51 @@ from prollytree import ProllyTree, TreeConfig
 tree = ProllyTree()
 tree.insert(b'test', b'value')
 result = tree.find(b'test')
-print(f'✅ Test passed: {result == b\"value\"}')
+print(f'✅ Basic test passed: {result == b\"value\"}')
 "
+
+    # Test SQL functionality if available
+    if [[ "$FEATURES" == *"sql"* ]]; then
+        echo "🧪 Testing SQL functionality..."
+        python3 -c "
+import tempfile
+import subprocess
+import os
+from prollytree import ProllySQLStore
+
+# Create temp dir and init git
+with tempfile.TemporaryDirectory() as tmpdir:
+    subprocess.run(['git', 'init'], cwd=tmpdir, capture_output=True)
+    subprocess.run(['git', 'config', 'user.name', 'Test'], cwd=tmpdir, capture_output=True)
+    subprocess.run(['git', 'config', 'user.email', 'test@test.com'], cwd=tmpdir, capture_output=True)
+
+    # Create SQL store
+    store_dir = os.path.join(tmpdir, 'data')
+    os.makedirs(store_dir)
+    store = ProllySQLStore(store_dir)
+
+    # Test basic SQL operations
+    store.create_table('test', [('id', 'INTEGER'), ('name', 'TEXT')])
+    store.insert('test', [[1, 'Test']])
+    result = store.select('test')
+
+    print(f'✅ SQL test passed: {len(result) == 1 and result[0][\"name\"] == \"Test\"}')
+" || echo "⚠️  SQL test skipped (import failed - may need git in temp dir)"
+    fi
 fi
 
 echo "🎉 Build complete!"
 echo ""
+echo "Built with features: $FEATURES"
+echo ""
 echo "To install the wheel manually:"
 echo "  pip install $WHEEL_PATH"
 echo ""
 echo "To test the bindings:"
 echo "  python3 test_python_binding.py"
+if [[ "$FEATURES" == *"sql"* ]]; then
+    echo "  python3 python/examples/sql_example.py  # Test SQL functionality"
+fi
 echo ""
 echo "To publish to PyPI:"
 echo "  cd python && ./publish_python.sh test    # Publish to TestPyPI first"