sqlseed 0.2.3__tar.gz → 0.2.5__tar.gz

sqlseed-0.2.5/.gitignore

@@ -0,0 +1,125 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.whl
+*.tar.gz
+
+# Virtual Environment
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+.trae/
+.claude/
+.gemini/
+.sonarlint/
+*.swp
+*.swo
+*~
+
+# Testing & Quality
+.pytest_cache/
+.benchmarks/
+.coverage
+coverage.xml
+htmlcov/
+.mutmut-cache
+mutmut_*.log
+mutmut_results_*.txt
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.hypothesis/
+.import_linter_cache/
+
+# sqlseed
+*.db
+*.sqlite
+*.sqlite3
+.sqlseed_cache/
+snapshots/
+.env
+# validation harness scratch artifacts
+scripts/complex_validation/dbs/_*.yaml
+examples/notebooks/_*.yaml
+examples/notebooks/_*.json
+examples/notebooks/batch_config.yaml
+*.nbconvert.ipynb
+.ipynb_checkpoints/
+
+# AI-generated config outputs
+*_config.yaml
+ai_analyze_out.yaml
+ai_suggest_out/
+out.yaml
+full_config_v2.yaml
+products_order_items.yaml
+test_merchants.yaml
+
+# OS
+.DS_Store
+
+# AI agent work directories
+.agents/
+
+# Other
+.worktrees/
+.sisyphus/
+
+# IDE knowledge graph cache (local only)
+.understand-anything/
+
+# AI batch edit scripts (one-shot, not for repo)
+.edits/
+_edit_helper.py
+
+# Local agent tool cache (not for repo)
+.omo/
+
+# Node.js (for ctxlint)
+node_modules/
+
+# mkdocs build output (deployed via GitHub Actions, not committed)
+site/
+
+# CodeFlow warning/issue reports (local analysis artifacts, not for repo)
+codeflow-warnings*.md
+codeflow_issues_report.md
+
+# Temporary tool outputs (not for repo)
+test.log
+.understand-anything/
+.playwright-mcp/
+
+# LLM validation loop engineering (temporary, not committed)
+scripts/_*.py
+data_quality_demo/*.db
+data_quality_demo/*.log
+data_quality_demo/*_config.yaml
+data_quality_demo/*_config_v*.yaml
+data_quality_demo/_*.json
+data_quality_demo/_report_*.md
+data_quality_demo/_phase1_catalog.md

{sqlseed-0.2.3 → sqlseed-0.2.5}/CHANGELOG.md

@@ -7,6 +7,89 @@ All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.5] - 2026-10-02
+
+### Added
+
+- Add reusable `FillOptions` for single-table generation. Existing `fill()` keyword calls and defaults remain supported; explicit keywords override shared settings.
+- Add Simplified Chinese and English interface switching across the Web workbench, configurations, run history and settings, preserving edits and keeping interface language separate from generated-data locale. Bundled message resources also translate supported backend diagnostics.
+- Add light, dark and system appearance, browser-local defaults for new configurations, and a shared Web component reference with bundled fonts.
+- Support managed component changes on Windows and reviewed updates of optional components with fixed dependencies, wheel hashes and service recovery.
+- Add editable AI suggestions and contextual preview-rule editing, keeping unapplied changes separate from active generation rules.
+- Support Web preview and atomic append for SQLite cross-table cycles when every internal edge is a single-column foreign key with existing non-NULL parent keys. Freeze the available keys before insertion, recheck sources and rules before writing, and roll back all newly inserted rows in the selected scope if any batch fails.
+
+### Changed
+
+- Split complex AI parsing and graph layout stages into focused helpers, and merge duplicate CSS declarations while preserving rendering and interaction behavior. `fill()` introspection now shows grouped options and typed compatibility keywords; the complete parameter reference remains in the API guide.
+- Simplify workbench guidance, configuration actions and relationship views; add pointer-centered graph zoom, stable hover geometry and actionable cycle locations.
+- Add editable graph zoom percentages, clearer node and relationship legends, and brief selection feedback for tabs, workflow stages and checkboxes. Respect reduced-motion preferences and keep dependency arrows static rather than implying an active data transfer.
+- Guide SQLite clear-and-regenerate failures through a reviewed downstream-table expansion while preserving the selected write mode and final confirmation.
+- Deliver Core, CLI, AI, Core MCP and Web together at version 0.2.5. Plugins require Core `>=0.2.5.dev0,<0.3` for shared connection parsing and credential redaction; the 0.2.4 release retains its original dependency metadata.
+- Refresh bilingual package and architecture documentation, update the wordmark, and replace obsolete audit logs with concise historical decision records.
+
+### Fixed
+
+- Make both Core MCP tools explicitly use Faker, matching their generated YAML templates and avoiding a fallback to Base when optional Mimesis is absent. The existing target-table-only YAML execution scope is unchanged.
+- Close tutorial SQLite connections and explicitly clean up temporary Notebook databases and cache settings, with complete offline execution checks for four affected notebooks.
+- Preserve SQLite `mode=memory` connection-pool behavior explicitly across SQLAlchemy 2.0/2.1, avoiding a deprecated implicit default without changing URI parsing or thread policy.
+- Reject non-object AI tool arguments through the normal format-error path, apply strict output-limit checks to streaming refinement, and ignore malformed suggestion cache envelopes.
+- Bound Web update checks across DNS and response-header waits, retain in-flight request limits after timeouts, and prevent late responses from replacing the active cache result.
+- Publish a terminal component-operation failure when temporary-file cleanup fails, preserving installer exit information and service recovery without automatically retrying installation.
+- Reject missing or columnless AI refinement targets before reading cached suggestions or calling a model, preserving valid empty tables and SQLite identifier resolution.
+- Keep AI-refined suggestions and cached configurations bound to the requested table; retry wrong-target model responses and ignore mismatched caches without silently renaming them.
+- Preserve quoted colon identifiers in database sampling, column-value and row-count queries without treating them as SQL parameters or changing sampled JSON/date values.
+- Refresh the installer snapshot when reviewing a new component operation plan, so temporary pip/uv detection changes do not permanently block installation; environment and dependency changes are still checked before execution.
+- Preserve SQLite file URL identity across encoded and special-character paths; opening an existing file or restoring a session cannot create a missing replacement database.
+- Restore each database connection's own unsaved workbench state when switching connections. Distinguish a configuration/database mismatch from a connection failure, offer a route back to the current database or to the matching target, and ignore stale responses after switching.
+- Report invalid generator bounds before applying rules; recover empty schemas after a refresh and restore keyboard focus after failed connections or background run polling.
+- Keep database credentials out of connection responses, validation errors, exception messages and diagnostic logs without changing runtime connection targets.
+- Treat invalid date ranges as configuration errors instead of exhausting random-generation retries; clarify the existing date/time contract in AI prompts and validate malformed JSON containers normally.
+- Distinguish malformed AI JSON from empty configurations and feed safe format diagnostics into existing bounded retries; unknown generators follow the existing validation recovery path.
+- Constrain strict local AI responses with LM Studio JSON-schema mode or Ollama JSON-object mode. Allow one text-mode compatibility attempt only when the server explicitly rejects the requested format; preserve strict parsing, output-limit checks, authentication failures and unrelated server errors.
+- Connect local AI services at `localhost` and loopback IP addresses directly when environment proxies are present, without changing remote proxy routing or HTTPS certificate settings.
+- Explain unsupported generation scopes, missing previews and disabled identity-reset controls with their actual cause. Preserve successfully returned samples and keep existing database records separately available for read-only inspection.
+- Preserve frontend error feedback and interaction state after failed asynchronous operations; improve light-theme control contrast, selected checkboxes, inspector spacing and diagnostic/example typography.
+- Update the PyPI uploader for Core Metadata 2.5 and allow the maintained workflow to publish an existing release tag without changing its source commit.
+- Use the shared `pypi` environment for all five existing packages while retaining separate upload jobs and post-publication acceptance; verify publisher permissions using unchanged public release files.
+- Upload only the measured Python coverage report, verify the Codecov signer in an isolated keyring, and deploy documentation through the supported GitHub Pages API with artifact provenance checks, bounded polling and cancellation.
+
+### Compatibility
+
+- SQLite cycle appends reuse existing parent records; newly generated cyclic records do not reference one another. Each source pool contains at most 100,000 distinct non-NULL keys. This does not bypass UNIQUE/CHECK constraints or add cross-table backfill. Empty-source cycles, cycles involving composite/overlapping foreign keys or configured associations, PostgreSQL cycles, and clearing cyclic tables before regeneration remain unsupported in the Web workbench.
+- Selecting every table or resetting IDs cannot remove an unsupported cycle. Ordinary acyclic appends process tables sequentially and commit each batch, so a later failure can leave earlier batches committed. Atomic rollback applies to the supported SQLite cycle-append and clear-and-regenerate paths. See the [Web workbench guide](docs/web-workbench.md) for the full boundaries.
+
+## [0.2.4] - 2026-09-13
+
+### Added
+
+- Ship the Web workbench as `sqlseed-web`, with schema graphs, column rules, previews, multi-table generation, saved configurations and run history. AI remains optional.
+- Add CHECK-aware generator adaptation, foreign-key coverage strategies and coordinated self-reference generation. PostgreSQL uses the SQLAlchemy adapter and psycopg driver.
+- Add contract-driven AI validation and repair with bounded model calls, deterministic fallbacks and separate AI MCP tools.
+- Add automatic post-upload PyPI acceptance for fresh full wheel, minimal Core/Web and full sdist installations, including source hashes and real SQLite entry-point checks.
+
+### Changed
+
+- Deliver offline Core, CLI, AI, Core MCP and Web as five packages at version 0.2.4. Install `sqlseed-cli` for the `sqlseed` command; the Core package provides the Python API. See the [migration guide](docs/migration.md) for changes from 0.2.3.
+- Keep sibling dependencies in the compatible `>=0.2.4.dev0,<0.3` series. Use matching released versions or a single development artifact set.
+- Core MCP exposes two offline tools. Launch `mcp-server-sqlseed-ai` separately for the four AI tools; installing the AI package does not add tools to the Core MCP process.
+- Refresh English and Chinese READMEs, user and API guides, package metadata and documentation links. Include the complete AGPL-3.0-or-later license text in all five distributions.
+- Deploy GitHub Pages after all main CI jobs succeed; publish Python packages through a separate version-tagged release workflow.
+
+### Fixed
+
+- Preserve JSON document values through typed database inserts and accept valid ISO temporal values without double encoding JSON or rejecting compatible SQLite date configurations.
+- Identify self-referencing rows by their complete primary key and check complete ordinary UNIQUE keys when assigning parent references; partial and expression indexes remain enforced by the database.
+- Preserve explicit generation constraints, handle existing UNIQUE values during appends and enforce CHECK ranges without silently replacing conflicting user rules.
+- Close SQLite resources and clean up Web workers on failures, including Windows path and macOS process-cleanup cases.
+- Keep AI MCP progress output out of the stdio JSON-RPC stream and enforce AI healing time budgets.
+
+### Compatibility
+
+- Migrate old `sqlseed.cli` imports and MCP client tool selections before upgrading. Core 0.2.3 cannot be combined with the new plugins.
+- Ordinary batched fills can retain earlier committed batches after a later failure; inspect the returned count and errors. PostgreSQL composite and cross-schema foreign-key generation still has limitations described in the migration guide.
+
 ## [v0.1.20]
 
 ### Changed

{sqlseed-0.2.3 → sqlseed-0.2.5}/CHANGELOG.zh-CN.md

@@ -7,6 +7,89 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，
 本项目遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。
 
+## [Unreleased]
+
+## [0.2.5] - 2026-10-02
+
+### 新增
+
+- 增加可复用的 `FillOptions` 单表生成参数。既有 `fill()` 关键字调用和默认值保持兼容，显式关键字优先于共享设置。
+- Web 工作台、配置管理、运行记录与设置支持简体中文和 English 切换，保留编辑状态，界面语言与生成数据的 locale 分离；随包分发的消息资源同时翻译受支持的后端诊断。
+- 增加浅色、深色及跟随系统外观、保存在浏览器中的新建配置偏好，以及包含分发字体的 Web 共用组件样板。
+- 支持 Windows 受管组件变更；可选组件更新需审阅依赖、固定其他包版本、核验 wheel 哈希，并恢复服务。
+- AI 建议支持应用前微调，预览可在保留上下文的情况下编辑字段规则；未应用修改与当前生成规则分开保存。
+- Web 支持 SQLite 已有来源的跨表循环预览与原子追加：环内每条关系必须是已有非空父键的单列外键。生成前固定引用来源，写入前重新核对来源与规则，任一批次失败时回滚整个所选范围的本次新增记录。
+
+### 变更
+
+- 将复杂 AI 解析与关系图布局阶段拆分为职责明确的辅助函数，合并重复 CSS 声明并保持渲染与交互行为。`fill()` 签名内省改为分组参数和带类型的兼容关键字，API 指南保留完整参数参考。
+- 简化工作台引导、配置操作与关系图；增加鼠标位置缩放、稳定的悬停几何和可定位到具体表的循环问题。
+- 关系图支持手动输入缩放比例，明确节点与关系图例；标签页、流程阶段和复选框提供短暂选择反馈并遵循减少动态效果设置。依赖箭头保持静态，避免暗示正在传输数据。
+- SQLite 清空重建受阻时，引导审阅并补齐下游关联表，保留已选写入方式和最后确认步骤。
+- Core、CLI、AI、Core MCP 与 Web 统一以 0.2.5 版本交付。插件要求 Core `>=0.2.5.dev0,<0.3`，使用共享连接解析与凭据脱敏；0.2.4 发行包保留原有依赖元数据。
+- 同步双语包说明与架构文档，更新品牌标识；用简明历史决策记录替换过期验收日志。
+
+### 修复
+
+- 两个 Core MCP 工具显式使用 Faker，与生成的 YAML 模板一致，避免未安装可选 Mimesis 时回退到 Base；YAML 仍只执行工具指定目标表的既有配置范围。
+- 关闭教程 SQLite 连接，显式清理 Notebook 临时数据库并恢复缓存设置；四份受影响示例增加完整离线执行验收。
+- 显式保留 SQLAlchemy 2.0/2.1 下 SQLite `mode=memory` 的连接池行为，消除已弃用的隐式选择，不改变 URI 解析或线程策略。
+- AI 工具参数为非对象 JSON 时进入正常格式错误处理；流式优化同样严格检查输出截断，结构损坏的建议缓存按失效处理。
+- Web 检查更新的等待预算覆盖 DNS 与响应头阶段；超时后保留在途请求数量限制，迟到响应不会覆盖当前缓存结果。
+- 组件操作临时文件清理失败时仍发布明确失败终态，保留安装器退出信息并恢复服务，不自动重试安装。
+- AI 单表配置优化在读取建议缓存或调用模型前拒绝不存在或没有列的目标，保留合法空表及 SQLite 标识符解析行为。
+- AI 优化建议与缓存配置必须属于请求的同一张表；目标错误的模型响应进入重试，错目标缓存重新生成，不静默改名。
+- 数据库采样、列值与行数查询保留已引用的冒号标识符，不再将其误判为 SQL 参数，并保持 JSON 与日期采样值的既有表示。
+- 重新审阅组件操作计划时更新安装器快照，避免 pip/uv 临时探测变化持续阻塞安装；执行前仍核验环境与依赖是否改变。
+- 保留编码及特殊字符 SQLite 文件 URL 的真实目标身份；打开已有文件或恢复会话时，不会创建已丢失数据库的替代空库。
+- 切换数据库时恢复各自未保存的工作台状态；区分配置与数据库不匹配和连接失败，提供返回当前数据库或选择对应目标的入口，切换后的迟到响应不会覆盖新状态。
+- 应用规则前定位非法生成器边界；重新读取空库结构后能进入新表；连接失败或运行记录轮询后恢复键盘焦点。
+- 连接响应、参数校验错误、异常与诊断日志不再回显数据库凭据；实际运行连接目标保持原样。
+- 无效日期范围按配置错误报告，不再耗尽随机取值重试；AI 提示明确既有日期时间合同，错误 JSON 容器交给正常配置校验。
+- 区分 AI 的非法 JSON 与空配置，在既有有界重试中反馈安全的格式诊断；未知生成器进入已有配置校验恢复路径。
+- 本地 AI 严格输出使用 LM Studio JSON-schema 模式或 Ollama JSON-object 模式。仅在服务器明确拒绝指定格式时尝试一次文本兼容请求；仍执行严格解析与截断检查，认证失败及无关服务器错误不会因此降级。
+- 配置了环境代理时，`localhost` 与回环 IP 上的本地 AI 服务仍直接连接；远程服务代理与 HTTPS 证书设置保持不变。
+- 按实际原因说明不支持的生成范围、缺失的新样例与自增重置禁用状态；保留其他已成功返回的样例，并将数据库已有记录作为独立只读入口。
+- 异步操作失败后保留前端错误反馈与交互状态；改善浅色主题控件对比度、复选框选中状态、检查区间距及诊断和示例字体。
+- 升级 PyPI 上传工具以支持 Core Metadata 2.5，并允许通过维护后的工作流发布现有版本 tag，保持其源码提交不变。
+- 五个已创建的包统一使用 `pypi` 发布环境，保留各包独立上传任务及发布后验收，并通过保持不变的公开发行文件核验发布权限。
+- 覆盖率只上传实际测量的 Python 报告，并在独立密钥环中核验 Codecov 签名者；文档通过受支持的 GitHub Pages API 部署，核对产物来源并限制轮询与取消的等待时间。
+
+### 兼容性
+
+- SQLite 循环追加引用已有父表记录，新生成的循环表记录不会互相引用；每个来源最多使用 100,000 个非空不同键，不绕过 UNIQUE/CHECK 约束，也不增加跨表回填。来源为空、涉及组合或重叠外键或配置关联、PostgreSQL 循环，以及清空循环表后重建，仍不属于当前 Web 工作台支持范围。
+- 全选数据表或重置 ID 不能解除不支持的循环。普通无跨表循环的追加保持逐表执行、逐批提交，后续失败可能保留先前已提交的批次；原子回滚适用于已支持的 SQLite 循环追加与清空重建流程。完整边界见 [Web 工作台指南](docs/web-workbench.md)。
+
+## [0.2.4] - 2026-09-13
+
+### 新增
+
+- 通过 `sqlseed-web` 交付 Web 工作台，支持 schema 关系图、字段规则、预览、多表生成、配置保存与运行记录；AI 仍为可选能力。
+- 增加 CHECK 驱动的生成器适配、外键覆盖策略与自引用协调生成；PostgreSQL 使用 SQLAlchemy adapter 和 psycopg 驱动。
+- 增加基于 contract 的 AI 校验与修复，包含有界模型调用、确定性降级和独立 AI MCP 工具。
+- 增加上传后自动执行的正式 PyPI 验收，覆盖全量 wheel、仅 Core/Web 和全量 sdist 的新环境安装，核验文件来源哈希并通过真实入口生成 SQLite 数据。
+
+### 变更
+
+- 离线 Core、CLI、AI、Core MCP 与 Web 以统一 0.2.4 版本五包交付。`sqlseed` 命令需要安装 `sqlseed-cli`；Core 提供 Python API。从 0.2.3 升级前请阅读[迁移指南](docs/migration.zh-CN.md)。
+- 兄弟包依赖保持在兼容的 `>=0.2.4.dev0,<0.3` 系列；使用匹配的正式版本或同一组开发构建产物。
+- Core MCP 提供两个离线工具；四个 AI 工具通过独立的 `mcp-server-sqlseed-ai` 进程提供，安装 AI 包不会向 Core MCP 进程注入工具。
+- 更新中英文 README、用户与 API 指南、包元数据和文档链接；五包分发物均包含完整的 AGPL-3.0-or-later 许可证正文。
+- main 全部 CI 任务成功后部署 GitHub Pages；Python 包通过独立、基于版本 tag 的发布流程上传。
+
+### 修复
+
+- 保留类型绑定写入中的 JSON 文档语义，支持合法 ISO 日期时间输入，避免 JSON 双重编码和旧 SQLite 日期配置失效。
+- 自引用父节点更新使用完整主键，并检查完整普通 UNIQUE 键；partial/expression index 仍由数据库执行约束。
+- 保留用户显式生成约束，追加数据时处理既有 UNIQUE 值，适配 CHECK 范围且不静默替换冲突规则。
+- 关闭 SQLite 资源并在失败时清理 Web worker，处理 Windows 路径与 macOS 进程清理问题。
+- AI MCP 的进度输出不再进入 stdio JSON-RPC 协议流，并严格执行 AI 修复时间预算。
+
+### 兼容性
+
+- 升级前迁移旧 `sqlseed.cli` 导入和 MCP 客户端工具选择；Core 0.2.3 不能与新插件混用。
+- 普通批量填充在后续批次失败时可能保留此前已提交的数据，应检查返回的 count 和 errors。PostgreSQL 复合与跨 schema 外键生成仍有限制，详见迁移指南。
+
 ## [v0.1.20]
 
 ### 变更