Wren AI × Pydantic AI SDK（wren-pydantic）实战指南：把 CLI 准备好的 Wren 项目接入 Agent 工具箱

Wren AI × Pydantic AI SDKwren-pydantic实战指南把 CLI 准备好的 Wren 项目接入 Agent 工具箱【免费下载链接】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本文基于当前仓库 docs/core/sdk/pydantic.md 及sdk/wren-pydantic源码编写。wren-pydantic是 Wren AI 官方为 Pydantic AI 提供的集成 SDK它将一个已经由wrenCLI 准备就绪的项目profile MDL 可选 memory 索引包装成 Pydantic AI 的FunctionToolset让 Agent 通过 context layer 完成 schema 解析、memory 召回与 SQL 执行。读完本文你将掌握从 CLI 引导项目、安装 SDK、构建数据问答 Agent到结构化输出、只读 memory、多项目编排等完整实战能力。概览wren-pydantic 是什么wren-pydantic是 Wren AI 的 Pydantic AI 集成层位于仓库的 sdk/wren-pydantic 目录。它的定位是一层薄适配器把 CLI 已经准备好的 Wren 项目wren_project.yml、target/mdl.json、可选的.wren/memory/暴露为一组 LLM 可调用的工具toolPydantic AI 的Agent借助这些工具回答数据问题。从源码结构看SDK 的核心是 WrenToolkit 这个门面类其内部由三个 provider 组成ProjectMDLSource读取project/target/mdl.json实现位于 sdk/wren-pydantic/src/wren_pydantic/_providers/mdl_source.pyProfileConnectionProvider解析连接 profile 并展开${ENV_VAR}密钥实现位于 sdk/wren-pydantic/src/wren_pydantic/_providers/connection.pyLocalLanceDBMemoryProvider/NoopMemoryProvider根据项目是否已有 memory 索引自动选择。Use this SDK when你在构建一个 Pydantic AI Agent需要针对某个 Wren 项目回答数据问题。对于一次性 CLI 使用单独的wren命令已经足够不需要引入 SDK。⚠️Caution — Wren CLI required first.本 SDK 是薄适配器依赖wrenCLI 已经准备好的项目profile MDL 可选 memory 索引。缺少这些WrenToolkit.from_project()将没有任何东西可挂载构造时直接失败。安装本包前请先完成安装引导。前置条件用 Wren CLI 准备项目安装wren-pydantic之前需要先用 Wren CLI 完成项目的最小引导。以 PostgreSQL 为例也可以换成 mysql、duckdb 等wren profile add my_project --datasource postgres # or mysql, duckdb, ... wren context init wren context set-profile my_project # binds profile to project wren context build # produces target/mdl.json wren memory index # optional but recommendedwren profile add创建连接 profile 并指定数据源类型wren context init初始化项目结构生成wren_project.ymlwren context set-profile把 profile 绑定到当前项目wren context build生成target/mdl.json—— 这是 SDK 的 MDL 来源WrenToolkit.from_project()会校验该文件是否存在wren memory index是可选项但推荐执行它为项目构建.wren/memory/目录SDK 据此自动暴露 memory 工具。完整的 CLI 配置流程包括.env配置、如何通过wren docs connection-info检查连接器字段可参考仓库内的连接指南 docs/core/guides/connect.md。从源码看WrenToolkit.from_project()的构造校验逻辑sdk/wren-pydantic/src/wren_pydantic/_toolkit.py#L179-L221会依次检查path/wren_project.yml是否存在否则抛出WrenToolkitInitError提示运行wren context initpath/target/mdl.json是否存在否则提示先运行wren context build加载project/.env若存在到进程环境变量用于解析 profile 中的密钥引用见 sdk/wren-pydantic/src/wren_pydantic/_toolkit.py#L223-L242探测path/.wren/memory/是否为目录是则启用LocalLanceDBMemoryProvider否则回退到NoopMemoryProvider不暴露任何 memory 工具。SDK 定义的两个专用异常均可在 sdk/wren-pydantic/src/wren_pydantic/exceptions.py 中查看WrenToolkitInitError初始化前置条件不满足与MemoryNotEnabledErrormemory 未启用时直接调用toolkit.memory.*。安装与 extras安装时选择与项目data_source匹配的 datasource extrapip install wren-pydantic[postgres,memory] # or mysql, bigquery, ...Extra用途postgres/mysql/bigquery/snowflake/clickhouse/trino/mssql/databricks/redshift/spark/athena/oracleDatasource 直通DuckDB 内置在wrenai中无需 extramemory启用 3 个 memory 工具wren_fetch_context、wren_recall_queries、wren_store_queryall一次性安装全部数据源 —— 适合实验生产环境较重如果你已经安装了wrenai例如你正在使用 CLI裸安装pip install wren-pydantic即可 —— 已有 extras 会随之生效。从 sdk/wren-pydantic/pyproject.toml 可以看到这些 extras 的实现机制每个 datasource extra 都链式直通到对应的wrenai[datasource]0.13.1因此连接器依赖只安装一次不会重复。同时包元数据声明了运行时约束requires-python 3.11核心依赖wrenai0.13.1提供WrenEngine、MemoryStore、profile 解析与 MDL 处理、pydantic-ai1.0,2.0、pydantic2。此外测试默认跳过标记为slow的用例LanceDB 集成测试会加载 sentence-transformer 模型约 30–40 秒需要完整运行可执行pytest -m slow。快速开始准备就绪后三行代码即可把项目接入 Agentfrom wren_pydantic import WrenToolkit from pydantic_ai import Agent toolkit WrenToolkit.from_project(./analytics_db) agent Agent( openai:gpt-4o, instructionstoolkit.instructions(), toolsets[toolkit.toolset()], ) result agent.run_sync(Top 5 customers by revenue last quarter?) print(result.output)toolkit 会读取项目的 MDL、连接 profile 和instructions.mdinstructions()生成的指令字符串会教给 Agent 推荐工作流召回 → 获取上下文 → 写 SQL → 存储结果。仓库提供了可直接运行的示例脚本 sdk/wren-pydantic/examples/pydantic_ai_demo.py通过环境变量PROJECT_PATH指定项目路径默认./analytics_db。API 参考WrenToolkit.from_project(path, *, profileNone)从 CLI 准备好的 Wren 项目目录构建 toolkit。参数类型说明pathstr \| Path项目根目录包含wren_project.yml的目录profilestr \| None可选 profile 名。解析顺序该 kwarg →wren_project.yml中的profile:字段 → 全局激活 profileMemory 工具自动探测存在path/.wren/memory/时暴露 3 个 memory 工具 3 个运行时工具不存在时只有运行时工具。没有提供 kwarg 来覆盖这一行为——启用靠wren memory index停用靠删除该目录见 sdk/wren-pydantic/src/wren_pydantic/_toolkit.py#L244-L253。关于 profile 的三层解析顺序源码 sdk/wren-pydantic/src/wren_pydantic/_providers/connection.py#L41-L60 给出了更精确的实现细节显式 kwargprofileprod直接按名查找注意实现使用is not None判断传入空字符串也会报“profile not found”而不会静默回退项目配置读取wren_project.yml中的profile:字段全局激活 profile即wren profile switch设定的当前 profile若三者均无抛出WrenToolkitInitError提示先执行wren profile add和wren profile switch。profile 中的${ENV_VAR}密钥会通过 Core 的expand_profile_secrets在暴露连接信息前完成展开。toolkit.toolset(*, include_memory_writeTrue, takes_ctxFalse)返回绑定到该 toolkit 的 Pydantic AIFunctionToolset。参数默认值说明include_memory_writeTrue设为False将 memory 暴露为只读移除wren_store_querytakes_ctxFalse设为True时为每个工具注入ctx: RunContext作为第一个参数 —— 用于与deps_type类型的工具混用返回一个FunctionToolset包含 3 个运行时工具 0/2/3 个 memory 工具取决于 memory 状态与include_memory_write。从源码 sdk/wren-pydantic/src/wren_pydantic/_toolkit.py#L65-L100 看memory 工具的注册逻辑是先构建运行时工具集若 memory provider 处于 enabled 状态再在其上追加 memory 工具include_memory_writeFalse只移除写工具wren_store_query保留两个只读工具。当 memory 完全禁用时include_memory_write不产生任何影响。toolkit.instructions(*, toolsetNone)返回 Wren 感知的指令字符串它会根据实际启用的工具自适应并在存在时嵌入项目的instructions.md。如果你自定义了 toolset例如include_memory_writeFalse请把同一个toolset传给Agent这样工作流会丢弃持久化步骤而不是让 Agent 去调用一个不存在的工具。指令构建实现在 sdk/wren-pydantic/src/wren_pydantic/_instructions.py组装逻辑为四段式 MarkdownWorkflow 规则从实际工具列表推导recall → fetch context → compose SQL → dry_plan → execute → store步骤编号动态重排缺哪个工具就自动去掉对应步骤Error recovery按error.phase分类给出恢复指引SQL_PARSING修语法、METADATA_FETCHING/MDL_EXTRACTION查模型列名、SQL_EXECUTION看dialect_sql片段等Things to avoid禁止直接写物理表名、禁止跳过 recall、禁止存储失败/试探性查询等Project-specific instructions项目根目录存在instructions.md时原样嵌入。值得注意的设计指令中 recall by default、store by default 是刻意强默认——源码注释指出经验测试表明 for non-trivial questions 这类柔和措辞几乎总被 GPT-4o 解读为“跳过”因此改用强默认措辞。ToolsLLM 面向Tool返回用途wren_queryWrenQueryResult通过 Wren context layer 执行 SQL上限 1000 行wren_dry_planstr不执行即做 SQL 计划验证 SQL 是否正确命中 MDL 模型wren_list_modelslist[ModelSummary]列出项目模型含列数与描述wren_fetch_contextFetchContextResult为自然语言问题检索 schema 与业务上下文wren_recall_querieslist[RecalledPair]召回相似的历史 NL→SQL 对作为 few-shot 示例wren_store_querystr持久化已确认的 NL→SQL 对注册为retries0写失败不循环重试每个工具注册为retries2LLM 有两次机会在 SQL 或元数据错误上自我纠正。被归类为基础设施类的错误连接失败、文件缺失会以WrenError直接向上抛出而不会转成ModelRetry。各工具的详细参数与实现可在 sdk/wren-pydantic/src/wren_pydantic/_tools.py 与 sdk/wren-pydantic/src/wren_pydantic/_tools_memory.py 中查看。几个关键的实现细节wren_querylimit参数默认 100合法范围 1–1000越界会直接抛出ModelRetryAggregate in SQL if you need more rows。常量MAX_QUERY_ROWS 1000是 LLM 工具层的硬上限防止模型幻觉出的巨大 limit 撑爆内存。当引擎恰好返回limit行时工具无法判断上游是否还有更多行会把truncatedTrue置位并返回给 LLM让它知道答案可能是部分结果sdk/wren-pydantic/src/wren_pydantic/_tools.py#L127-L151。wren_fetch_context支持limit默认 5、item_typemodel/column/relationship/view可空与model收窄到单个模型三个筛选参数。wren_recall_queries默认召回 3 条相似 NL→SQL 对。wren_store_queryretries0因为写失败通常重试同一调用也修不好且 LLM 已完成分析工作直接暴露失败比陷入重试循环更优。工具返回的是类型化 Pydantic 模型见 sdk/wren-pydantic/src/wren_pydantic/_models.pyWrenQueryResult带columns/rows/row_count/truncated其中row_count有校验器强制等于len(rows)FetchContextResult区分full小 schema 整体返回与search大 schema 检索命中两种策略schema字段别名schema_text以避免与BaseModel内部属性冲突RecalledPair的score别名到 LanceDB 的_distance且extraignore容忍 Core 后续新增字段。错误处理机制源码深化WrenError→ModelRetry的映射实现在 sdk/wren-pydantic/src/wren_pydantic/_errors.py核心逻辑如下Propagate 类基础设施错误码GET_CONNECTION_ERROR、INVALID_CONNECTION_INFO、DUCKDB_FILE_NOT_FOUND、ATTACH_DUCKDB_ERROR、GENERIC_INTERNAL_ERROR、NOT_IMPLEMENTED—— 重试无意义直接冒泡出 Agent 交给外层代码处理Retry 类其余错误SQL 错误、模型查找、校验失败 —— 转成ModelRetry框架以RetryPromptPart形式把消息回传给 LLM触发自我纠正。消息构建是phase-aware的按SQL_PARSING、SQL_PLANNING、SQL_TRANSPILE、SQL_DRY_RUN、SQL_EXECUTION、METADATA_FETCHING、MDL_EXTRACTION、VALIDATION给出不同的措辞框架。SQL_EXECUTION错误会附带最多 200 字符的翻译后 dialect SQL 摘录让 LLM 看到实际发给数据库的语句。安全方面消息体做递归密钥脱敏匹配password/secret/token/credential的键值替换为***并强制 4KB 上限避免数据库密码或数 MB 的元数据大块泄漏进重试 prompt。直接 Python API在 Agent 循环之外直接调用 Wrentoolkit.query(SELECT ...) # → pyarrow.Table toolkit.dry_plan(SELECT ...) # → str (target-dialect SQL) toolkit.dry_run(SELECT ...) # → None (validates without execution) toolkit.memory.fetch(revenue trends) toolkit.memory.recall(top customers, limit3) toolkit.memory.store(nl..., sql..., tags[revenue])仅同步 API—— 没有aquery/afetch变体。底层引擎是同步 I/OPydantic AI 会自动把同步工具桥接到其 async 运行循环因此用asyncio.to_thread包裹属于“伪异步”没有真实的并发收益。等 Wren AI 推出 async 原生引擎后再重新评估。源码层面对应的实现要点sdk/wren-pydantic/src/wren_pydantic/_toolkit.py#L121-L177query支持limit与properties参数properties承载 MDL 会话属性并转发到引擎的计划路径——被行级访问控制RLAC保护的模型需要其规则声明的必需值缺少该值时计划阶段就会失败dry_plan返回目标方言的展开后 SQLRLAC 谓词在计划期间注入因此同样生效每个调用都会重新构建WrenEngine并重读 manifest保证wren context build的更新被即时拾取但 connector 在 toolkit 生命周期内缓存复用数据库鉴权只发生一次toolkit.memory是惰性初始化的子作用域sdk/wren-pydantic/src/wren_pydantic/_memory_api.pyfetch额外支持threshold参数store会拒绝包含逗号的 tag逗号是底层存储的分隔符静默拆分会造成往返损坏内存 Store 实例因加载 sentence-transformer 模型较重而缓存复用。memory 未启用时直接调用这些方法会抛出MemoryNotEnabledError。集成模式结构化输出 viaoutput_typePydantic AI 的杀手级特性让模型把答案以类型化的 Pydantic 实例返回由框架校验。与我们的 toolset 开箱即用from pydantic import BaseModel class TopCustomers(BaseModel): period: str customers: list[str] agent Agent( openai:gpt-4o, instructionstoolkit.instructions(), toolsets[toolkit.toolset()], output_typeTopCustomers, # ← framework validates output into this type ) result agent.run_sync(Top 5 customers last quarter?) print(result.output.customers) # already a list[str], no parsing needed可运行的完整版本见 sdk/wren-pydantic/examples/pydantic_ai_structured_demo.py其TopCustomers模型还带可选的notes字段演示了字段为空的优雅处理。只读 memory共享 / 精选项目当 Agent 应学习历史查询但不应污染 memory 存储时使用include_memory_writeFalsetoolset toolkit.toolset(include_memory_writeFalse) agent Agent( openai:gpt-4o, instructionstoolkit.instructions(toolsettoolset), # keep prompt in sync toolsets[toolset], )把toolset传给instructions()能确保工作流丢弃“存储查询”步骤而不是让 Agent 调用一个已不存在的工具。这适合共享/精选的 memory 存储场景。与deps_type工具混用当你想在同一 Agent 中组合 Wren 工具与自己的依赖注入工具时启用takes_ctxTruedataclass class MyDeps: api_client: ApiClient agent Agent( openai:gpt-4o, deps_typeMyDeps, toolsets[toolkit.toolset(takes_ctxTrue)], # ← required when deps_type is set ) # Your own tool that uses deps: agent.tool def lookup_external(ctx: RunContext[MyDeps], id: str) - str: return ctx.deps.api_client.fetch(id)Wren 工具在内部忽略 contexttoolkit 已捕获自身状态——takes_ctxTrue只是加上该参数使签名与 Pydantic AI 的 deps 类型注册兼容。多项目、单程序一个 toolkit 绑定一个项目。要查询多个 Wren 项目构建独立的 toolkit 并在 Python 中编排loans WrenToolkit.from_project(./loans_proj) events WrenToolkit.from_project(./events_proj) loans_agent Agent(model..., toolsets[loans.toolset()], instructionsloans.instructions()) events_agent Agent(model..., toolsets[events.toolset()], instructionsevents.instructions())跨项目 join 必须在 Python 中完成而不是在 SQL 中 —— 每个项目有自己独立的 MDL 与连接。故障排查症状原因修复table wren.schema.x not found出现在 SQL_PLANNINGAgent 写了schema.table物理名而不是 MDL 模型名收紧 instructions 禁止物理名或让 Agent 先调用wren_list_models连接到了错误的数据库项目没有profile:固定 → 回退到全局激活 profile运行wren context set-profile name固定绑定MissingSecretErrorprofile 中的${VAR}未解析在project/.env中填入对应键wren_query返回被截断的行数每次工具调用硬上限 1000 行在 SQL 中加LIMIT或使用直接 APItoolkit.query拉取更大数据量兼容性wren-pydanticwrenaipydantic-ai0.1.x 0.7.0 1.0, 2.0注意当前仓库 sdk/wren-pydantic/pyproject.toml 中的实际版本为0.3.0对wrenai的要求为0.13.1——文档中的兼容矩阵反映的是 0.1.x 时代的最小版本基线实际安装时以包元数据声明为准。SDK 额外声明了requires-python 3.11。限制仅同步直接 API。理由见 API 参考一节底层引擎是同步 I/OPydantic AI 自动桥接异步包装没有真实并发收益一个 toolkit 对应一个 Agent。多 Wren 项目场景需构建独立 toolkit Agent并在 Python 侧做联邦无热重载。target/mdl.json每次工具调用都会重读因此wren context build的更新会被即时拾取但 profile 变更需要构造新的 toolkit不要在 Agent 使用同一项目时运行wren memory index。索引操作会删除并重建 LanceDB schema 表并发读取可能瞬时失败。这些限制在仓库的 sdk/wren-pydantic/README.md 中同样有完整声明并补充了 Apache License 2.0 许可说明。SDK 的单元测试sdk/wren-pydantic/tests/unit与契约测试sdk/wren-pydantic/tests/conformance/test_pydantic_ai_contract.py覆盖了 toolkit 初始化、错误映射、指令生成、memory API 与 Pydantic AI 契约等路径可作为深入理解内部行为的参考。【免费下载链接】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），仅供参考