Expose ProllyTree SQL API to Python and Add Chronological LangGraph TA-RAG Example

[zhangfengcdt]

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