wren-core-py 深入指南用 PyO3 打通 WrenAI 的 Rust 语义引擎与 Python 生态【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAIWrenAI 的核心是 Rust 编写的语义引擎 wren-core而 wren-core-py 正是这座引擎面向 Python 世界的官方桥梁它通过 PyO3 将 wren-core 的 MDLModeling Definition Language语义层能力封装成 Python 模块再由 Maturin 构建为可分发的 wheel 包供 Python 端的 ibis-server 等上层服务直接调用。读完本文你将掌握 wren-core-py 的模块结构、构建链路、全部核心 Python API会话上下文、MDL 解析、行级访问控制校验、Manifest 抽取与迁移等、并发契约与测试方法并能基于仓库源码定位每一处能力的具体实现。定位语义引擎与 Python 服务器之间的那座桥wren-core-py 位于 core/wren-core-py 目录其角色可以概括为PyO3 bindings exposing wren-core to PythonBuilt with Maturin见 core/wren-core-py/.claude/CLAUDE.md。它是连接两端的中间层上游是 Rust 语义引擎 wren-core负责 SQL 的语义层转换、MDL 解析、计划生成下游是 Python 侧的 ibis-server以及所有需要把自然语言问题转化为可信 SQL 与图表的 AI Agent 服务。在 core/wren-core-py/README.md 中作者明确描述了这一定位Wren Engine 通过语义层 MDL 翻译 SQL 查询并支持 22 种数据源PostgreSQL、BigQuery、Snowflake 等。wren-core-py 让这些能力对 Python 开发者完全透明——只要pip install wren-core-py就能在 Python 进程内直接获得 Rust 引擎的语义分析能力而无需感知底层 Rust 的存在。从工程角度看这种Rust 核心 Python 胶水层的架构既保留了语义引擎的高性能和类型安全又复用了 Python 生态庞大的数据工具链如 PyArrow是 WrenAI 面向 AI Agent 场景的关键基础设施。模块地图src/ 下七个源文件的职责划分wren-core-py 的源码非常克制全部集中在src/目录。按照 core/wren-core-py/.claude/CLAUDE.md 的说明各文件职责如下文件职责lib.rsPyO3 模块入口点注册所有对外暴露的类与函数context.rsPython 面向的会话上下文包装 wren-core 的 SessionContextmanifest.rsPython 侧 Manifest 类型由wren-manifest-macro自动生成及 base64/JSON 转换validation.rs暴露给 Python 的查询校验能力extractor.rsMDL 抽取工具裁剪未使用的数据集remote_functions.rs远程函数注册与描述errors.rsRust → Python 异常的类型转换入口 lib.rs注册了什么core/wren-core-py/src/lib.rs 展示了模块对外契约的完整清单4 个类PySessionContextPython 名SessionContext、PyRemoteFunction、Manifest、PyManifestExtractor6 个函数to_json_base64、to_manifest、validate_rlac_rule、is_backward_compatible、migrate_manifest_json、cube_query_to_sql。这意味着 Python 侧import wren_core后可以得到与 Rust 引擎一一对应的能力面。模块还通过env_logger::init()初始化日志便于排查。构建链路PyO3 Maturin uv 的三层协作Cargo.toml依赖与特性core/wren-core-py/Cargo.toml 定义了关键依赖pyo3 { version 0.29.0, features [extension-module, abi3-py311] }PyO3 稳定 ABI目标 Python 3.11wren-core { version 0.3.2, path ../wren-core/core, package wren-semantic-core }语义引擎本体通过 path 依赖指向仓库内 core/wren-core/corewren-core-base { path ../wren-core-base, features [python-binding] }带 PyO3 支持的共享 Manifest 类型其余包括datafusion-common、serde_json、tokio、csv、env_logger等用于 IPC 流、序列化、异步运行时与日志。特性设计上有两个关键点对应 core/wren-core-py/.claude/CLAUDE.md 的 Build Notesextension-module特性是默认开启且必需的——构建为 Python 扩展模块时必须启用--no-default-features用于纯 Rust 测试即just test-rs此时禁用 PyO3 扩展模块链接Rust 单元测试可以脱离 Python 运行。pyproject.tomlMaturin 作为构建后端core/wren-core-py/pyproject.toml 声明了完整的打包信息requires-python 3.11项目名wren-core-py版本 0.7.6构建后端为maturinbuild-system.requires [maturin1.0,2.0][tool.maturin]指定module-name wren_corelocked true并从 sdist 中排除tests/**与target/**开发依赖组固定了maturin1.9.4、pyarrow25.0.0、pytest9.1.1、ruff0.13.1ruff 规则集相当严格pydocstyle、pyflakes、isort、pylint 等并显式extend-exclude [*.md]避免格式化手写文档。稳定 ABI 的红利文档特别强调使用abi3-py311稳定 ABI同一个 wheel 可以覆盖 Python 3.11 及以上的所有版本无需为每个小版本分别编译。这是构建产物分发成本大幅下降的关键设计。开发命令justfile 即完整工作流core/wren-core-py/justfile 提供了全套开发命令与 core/wren-core-py/.claude/CLAUDE.md 中列举的一致just install # uv sync --no-install-project仅同步依赖不安装项目自身 just develop # uv run --no-sync maturin develop构建开发版 wheel 供本地测试 just build # 构建发布版 wheel输出到 target/wheels/ENVprod 时加 --release just test-rs # cargo test --no-default-features仅 Rust 测试 just test-py # uv run --no-sync pytest仅 Python 测试 just test # 先 Rust 后 Python全部测试 just format # cargo fmt ruff format ruff check --fix taplo fmt其中install特意使用--no-install-project因为项目本体是 Rust 扩展模块必须由maturin develop或maturin build编译。环境要求见 core/wren-core-py/README.md 的 Developer GuideRust 工具链、Python 3.11、uv、casey/just。just develop是 Python 测试前的必需步骤——必须先编译出可导入的wren_core扩展模块pytest才能运行。核心 APISessionContext 的完整能力面SessionContext是 Python 侧使用频率最高的类实现在 core/wren-core-py/src/context.rsRust 结构体名PySessionContext通过#[pyclass(name SessionContext)]暴露为 Python 名。构造与初始化构造函数签名源码 context.rs为SessionContext(mdl_base64None, remote_functions_pathNone, propertiesNone, data_sourceNone)mdl_base64base64 编码的 MDL JSON。提供时直接基于该 Manifest 初始化语义层不提供时创建空 MDLremote_functions_pathCSV 文件路径用于注册远程函数每行一个函数描述经csv::Reader反序列化为PyRemoteFunctionproperties会话属性frozenset 形式的(key, value)二元组集合data_source数据源字符串如bigquery用于按数据源注册对应函数集合。源码中有一个细节DataSource::BigQuery分支会跳过远程函数注册见register_function_by_data_source。构造时引擎会以Mode::Unparse和Mode::LocalRuntime两种模式分别把 MDL 应用到上下文上生成unparser_ctx用于 SQL 转换与exec_ctx用于本地执行两个内部上下文。SQL 语义转换transform_sqlfrom wren_core import SessionContext base64_mdl_json your-base64-encoded-mdl-json ctx SessionContext(base64_mdl_json) planned_sql ctx.transform_sql(SELECT * FROM my_model)transform_sql将 Wren SQL 经过语义层转换为目标数据源的 Planned SQL。实现上该方法把 SQL 字符串拷贝为自有所有权后释放 GIL再在进程级 Tokio runtime 上调用mdl::transform_sql_with_ctx完成转换context.rs保证阻塞期间不卡住其他 Python 线程。limit 下推pushdown_limitpushdown_limit(sql, limitNone)用于把 LIMIT 下推到 SQL 中context.rslimitNone时原样返回 SQL已存在 LIMIT 且大于下推值时替换为下推值小于则保持不变不存在 LIMIT 时直接追加LIMIT limit一次只允许一条语句否则报错。本地执行query、dry_run、list_tablesipc_bytes ctx.query(SELECT * FROM my_catalog.my_schema.customer)query使用 DataFusion LocalRuntime 执行 SQL返回Arrow IPC stream 字节Vecu8Python 侧用 PyArrow 即可解析import io from pyarrow import ipc table ipc.open_stream(io.BytesIO(bytes(ipc_bytes))).read_all()值得注意的实现细节见 test_query_ipc_schema.pyIPC 流写入的是执行时 schema而非计划声明的 MDL 类型。当 MDL 声明integer/varchar而物理列实际是 int64/Utf8View 时流依然可解码且数值正确——空结果集也保持一致 schema。dry_run(sql)通过EXPLAIN {sql}校验计划可行性并返回格式化执行计划文本list_tables()枚举执行上下文中的所有表名best-effort 语义遍历中途的注册可能不出现但结果始终良构。本地文件注册两阶段初始化MDL 模型可以由本地 Parquet/CSV 文件回填采用两阶段初始化详见 core/wren-core-py/README.md 与 tests/test_physical_tables.pyctx SessionContext() ctx.register_parquet(customer, /data/customer.parquet) ctx.register_csv(orders, /data/orders.csv) ctx.load_mdl(base64_mdl_json) # MDL 模型现在解析到这些文件可见性契约要点文件表落在默认 catalogdatafusion.public其内部状态与派生上下文实时共享因此即使在上下文创建之后再注册query/dry_run/list_tables也能看到MDL 模型要解析到已注册文件其tableReference必须为{catalog: datafusion, schema: public, table: 注册名}且声明的列必须存在于文件中例外是全新的顶层 catalog——它必须在 MDL 构造、load_mdl或 transform 之前存在因为这几步都会对顶层 catalog 列表做快照对应 wren-core 中clone_catalog_list的语义。load_mdl实现上从base_ctx抽取物理表 provider调用AnalyzedWrenMDL::analyze_with_tables后重建unparser_ctx与exec_ctxcontext.rs。并发契约core/wren-core-py/README.md 的 Concurrency 一节给出了明确的并发语义transform_sql、query以及注册类 API 支持并发执行——每个transform_sql作用于私有顶层 catalog 快照分析器状态按调用隔离dry_run对仅做EXPLAIN的语句是并发安全的ANALYZE前缀输入会变成EXPLAIN ANALYZE并真正执行不在并发契约内register_parquet/register_csv在不同表名下安全同名并发注册不受支持load_mdl与其他调用不能重叠它接收mut selfPyO3 的独占借用会对同一上下文上的重叠调用抛出RuntimeError。相关测试见 test_modeling_core.py 中的test_concurrent_calls_from_threads与test_fork_child_gets_working_runtime——后者验证了进程级 runtime 的 fork 安全性子进程继承句柄但不继承 worker 线程PID 不匹配时会惰性重建 runtime。Manifest 工具链base64 编解码、迁移与兼容性检查core/wren-core-py/src/manifest.rs 提供了一组与 MDL 打交道的基础函数to_json_base64(manifest) - str将Manifest序列化为 JSON 再 base64 编码是 Python 侧构造 MDL 的出口to_manifest(base64_str) - Manifest反向解码并反序列化是SessionContext、ManifestExtractor共用的解析入口migrate_manifest_json(manifest_json, target_version) - str将 Manifest JSON 迁移到指定 layout 版本底层委托wren-core-base的migration::migrate_manifestis_backward_compatible(base64_str) - bool检查 MDL 是否可被 v2 wren core 使用——只要存在行级访问控制RLAC或列级访问控制CLAC规则即返回False此类 MDL 仅能由 v3 核心使用。Manifest类型本身由wren-manifest-macro自动生成见 core/wren-core-base/manifest-macromanifest.rs中通过pub use wren_core_base::mdl::*直接再导出。校验与安全行级访问控制的规则验证validate_rlac_rule(rule, model)validation.rs是安全相关的关键能力它将 Python 传入的RowLevelAccessControl规则与Model交给 wren-core 的logical_plan::analyze::access_control::validate_rlac_rule校验规则不合法时抛出带具体信息的异常。结合 test_modeling_core.py 中的test_rlac/test_validate_rlac_rule测试可以看到它覆盖了规则字段合法性、表达式可解析性等场景——这是 MDL 应用到引擎前的一道安全闸门。Manifest 抽取为问答裁剪语义模型extractor.rs 中的ManifestExtractor解决一个实际痛点Agent 在回答具体问题时只需要语义模型的一小部分而非全部。from wren_core import ManifestExtractor extractor ManifestExtractor(base64_mdl_json) used_tables extractor.resolve_used_table_names(SELECT * FROM my_model) smaller_manifest extractor.extract_by(used_tables) # 仅保留被使用的数据集resolve_used_table_names(sql)解析 SQL 中引用的表名列表解析时关闭标识符归一化以保证大小写敏感extract_by(used_datasets)从原 Manifest 中裁掉未被使用的数据集保留与使用数据集相关的模型/视图及其 relationship输出精简后的Manifest。相关测试见 test_modeling_core.py 的test_resolve_used_table_names与test_extract_by。远程函数扩展引擎能力PyRemoteFunctionremote_functions.rs描述一个远程函数的六元组function_typescalar/aggregate/window、name、return_type、param_names、param_types均为逗号分隔字符串、description并可通过to_dict()转为 Python dict。注册时函数名会统一小写以匹配 DataFusion 的解析归一化规则且会与已注册函数做名称去重见 context.rs 的register_remote_function。get_available_functions()/get_available_function(name)通过查询information_schema.routines返回当前上下文中可用的函数清单。错误处理从 Rust 错误到 Python 异常errors.rs 定义了统一的CoreError并为它实现了从base64::DecodeError、serde_json::Error、DataFusionError、csv::Error、ParsedDataSourceError等十余种底层错误的From转换反过来CoreError → PyErr统一映射为PyException。特别地DataFusionError的转换会向下穿透解包WrenError让 Python 侧拿到的错误信息尽量贴近语义引擎的真实报错。测试与发布测试矩阵just test-rs运行 Rust 侧cargo test --no-default-features覆盖 manifest 编解码往返等单元测试just test-py运行 tests/ 下的 Python 测试覆盖会话上下文与函数注册test_session_context、test_get_available_functionslimit 下推、大小写敏感性、并发与 fork 场景test_modeling_core.py本地文件注册与两阶段初始化test_physical_tables.pyIPC schema 正确性包括 MDL 类型与物理类型不一致、空结果集场景test_query_ipc_schema.pyCube 查询的 JSON DSLtest_cube.py 中的test_basic_cube_query、test_time_dimension_with_date_range等。发布脚本scripts/publish.sh 支持发布到 PyPI/TestPyPI./scripts/publish.sh --build # 仅构建 wheel ./scripts/publish.sh --test # 构建并发布到 TestPyPI ./scripts/publish.sh # 构建并发布到 PyPI发布物wheel覆盖 Linux x86_64、macOS x86_64/ARM64、Windows x86_64 等平台见 core/wren-core-py/README.mdLinux ARM64 尚无预编译 wheel需在目标平台用 Rust 工具链从源码构建。结语wren-core-py 是一个小而精的桥接模块源码仅 7 个 Rust 文件却完整承载了 WrenAI 语义引擎对 Python 生态的全部能力出口——从 MDL 的编解码、迁移、兼容性检查到会话上下文的 SQL 转换、本地执行与本地文件回填再到行级访问控制校验和 Manifest 裁剪。理解了它的模块划分、构建链路的两个特性开关extension-module与abi3-py311以及just命令的完整工作流你就掌握了在 Python 侧驱动 Rust 语义引擎的标准姿势也就能基于 core/wren-core-py/.claude/CLAUDE.md 这份开发者指南快速上手或扩展这一层能力。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考