sqlseed 0.1.14__tar.gz → 0.1.16__tar.gz

{sqlseed-0.1.14 → sqlseed-0.1.16}/.gitignore

@@ -19,6 +19,8 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+*.whl
+*.tar.gz
 
 # Virtual Environment
 .venv/
@@ -29,46 +31,40 @@ ENV/
 # IDE
 .vscode/
 .idea/
+.trae/
+.claude/
+.sonarlint/
 *.swp
 *.swo
 *~
 
-# Testing
+# Testing & Quality
 .pytest_cache/
 .benchmarks/
 .coverage
 coverage.xml
 htmlcov/
-
-# Type checking
 .mypy_cache/
 .dmypy.json
 dmypy.json
-
-# Linting
 .ruff_cache/
 
-# Project specific
+# sqlseed
 *.db
 *.sqlite
 *.sqlite3
-snapshots/
-
-# AI cache
 .sqlseed_cache/
+snapshots/
+.env
+examples/notebooks/_*.yaml
+examples/notebooks/_*.json
+examples/notebooks/batch_config.yaml
+*.nbconvert.ipynb
+.ipynb_checkpoints/
 
-# macOS
+# OS
 .DS_Store
 
-# Trae IDE
-.trae/
-
-# Build artifacts
-*.whl
-*.tar.gz
-
-# Local git worktrees
+# Other
 .worktrees/
-
-# IDE - SonarLint
-.sonarlint/
+.sisyphus/

{sqlseed-0.1.14 → sqlseed-0.1.16}/CHANGELOG.md

@@ -7,6 +7,42 @@ 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).
 
+## [v0.1.16]
+
+### Added
+
+- `_utils/paths.py` — `get_cache_dir(subdir)` platform-specific cache directory utility (macOS `~/Library/Caches/sqlseed/`, Linux `~/.cache/sqlseed/`, Windows `%LOCALAPPDATA%/sqlseed/`), respects `SQLSEED_CACHE_DIR` env var
+- `_utils/progress.py` refactored to Strategy Pattern with multi-backend architecture: `RichProgressBackend` (terminal), `TqdmNotebookBackend` (Jupyter), `NullProgressBackend` (disabled), with automatic environment detection
+- `generators/_protocol.py` adds `GenerationError` (retriable runtime error) and `ConfigurationError` (non-retriable config error) exception classes
+- `ColumnConfig` adds `normalize_dict_input` model_validator: supports `type` as `generator` alias, auto-routes unknown keys to `params`, flattens nested `params`
+- `DataStream` now logs UNIQUE constraint exhaustion warnings with column and generator details
+- `DataStream` RuntimeError message includes non-skip column names for faster debugging
+- Jupyter notebook tutorial series (`examples/notebooks/`): quickstart, column mapping, generators, DB association, expression/DAGs, AI configuration, MCP server, testing patterns, utilities, CLI reference
+
+### Changed
+
+- `SnapshotManager` default directory changed from `./snapshots` to platform cache dir (`get_cache_dir("snapshots")`)
+- `AiConfigRefiner` default cache directory changed from `.sqlseed_cache/ai_configs/` to platform cache dir (`get_cache_dir("ai_configs")`)
+- `cli/main.py` `inspect --show-mapping` now uses `orch._resolve_specs()` for accurate column mapping display (previously used `orch.map_column(col)` which skipped FK resolution)
+- `cli/main.py` `fill` now outputs warnings for `result.errors` to stderr
+- `orchestrator._resolve_user_configs` supports `derive_from`/`expression` in dict-style column configs
+- Demo database (`examples/build_demo_db.py`) rewritten as idempotent schema initializer (`ensure_db()`), no longer embeds seed data
+- **⚠️ Breaking**: `register_shared_pool` now only registers PK and FK columns to SharedPool (previously registered all non-PK-skip columns). Implicit cross-table association for same-name non-PK/FK columns now requires explicit `ColumnAssociation` config
+- UNIQUE columns are no longer overridden by SharedPool implicit association or template pool, preventing duplicate values that caused `IntegrityError`
+
+### Fixed
+
+- `orchestrator.fill_table` now catches `sqlite3.IntegrityError` alongside `OperationalError`, preventing unhandled crashes on UNIQUE/FK violations
+- `UniqueAdjuster` uses `params.get("max_length", max_length)` to prevent `KeyError` when `max_length` is absent from params
+- `DataStream._attempt_node_generation` catches generator exceptions gracefully instead of propagating to caller
+- Backtrack/no-values log level reduced from `warning` to `debug` to reduce noise
+
+## [v0.1.15]
+
+### Fixed
+- CI: remove unnecessary try/except in `ExpressionEngine.evaluate` to resolve SonarCloud S2737 and CodeFlow try-except-raise warnings
+- CI: add comment documenting intentional `list()` usage in `PluginMediator.apply_template_pool` (SonarCloud S7504)
+
 ## [v0.1.14]
 
 ### Fixed
@@ -36,7 +72,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### AI Plugin (sqlseed-ai)
 - Auto model selection: `_model_selector` picks the best free model from OpenRouter by priority
 - Structured output: `response_format: json_object` forces LLM to return JSON
-- Few-shot example library: 4 typical scenarios (users, bank cards, orders, employees)
+- Few-shot example library: 4 typical scenarios (users, projects, orders, employees)
 - `AiConfigRefiner` self-correction loop: auto-detects and fixes invalid configs, up to 3 retries
 - File caching: `.sqlseed_cache/ai_configs/` with schema hash validation, `--no-cache` to skip
 - Pre-computed template pool: `sqlseed_pre_generate_templates` hook pre-generates candidate values for complex columns

{sqlseed-0.1.14 → sqlseed-0.1.16}/CHANGELOG.zh-CN.md

@@ -7,6 +7,42 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，
 本项目遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。
 
+## [v0.1.16]
+
+### 新增
+
+- `_utils/paths.py` — `get_cache_dir(subdir)` 平台标准缓存目录工具（macOS `~/Library/Caches/sqlseed/`，Linux `~/.cache/sqlseed/`，Windows `%LOCALAPPDATA%/sqlseed/`），支持 `SQLSEED_CACHE_DIR` 环境变量覆盖
+- `_utils/progress.py` 重构为 Strategy Pattern 多后端架构：`RichProgressBackend`（终端）、`TqdmNotebookBackend`（Jupyter）、`NullProgressBackend`（禁用），含自动环境检测
+- `generators/_protocol.py` 新增 `GenerationError`（可重试运行时错误）和 `ConfigurationError`（不可重试配置错误）异常类
+- `ColumnConfig` 新增 `normalize_dict_input` model_validator：支持 `type` 作为 `generator` 别名、未知键自动归入 `params`、嵌套 `params` 展平
+- `DataStream` 新增 UNIQUE 约束耗尽警告日志，包含列名和生成器详情
+- `DataStream` RuntimeError 消息现在包含非 skip 列名，便于快速定位问题
+- Jupyter Notebook 教程系列（`examples/notebooks/`）：快速上手、列映射、生成器、数据库关联、表达式/DAG、AI 配置、MCP 服务器、测试模式、工具类、CLI 参考
+
+### 变更
+
+- `SnapshotManager` 默认目录从 `./snapshots` 改为平台缓存目录（`get_cache_dir("snapshots")`）
+- `AiConfigRefiner` 默认缓存目录从 `.sqlseed_cache/ai_configs/` 改为平台缓存目录（`get_cache_dir("ai_configs")`）
+- `cli/main.py` `inspect --show-mapping` 现在使用 `orch._resolve_specs()` 显示准确的列映射（此前使用 `orch.map_column(col)` 会跳过 FK 解析）
+- `cli/main.py` `fill` 命令现在会将 `result.errors` 的警告输出到 stderr
+- `orchestrator._resolve_user_configs` 支持 dict 风格的 `derive_from`/`expression` 列配置
+- 示例数据库（`examples/build_demo_db.py`）重写为幂等 schema 初始化（`ensure_db()`），不再内置种子数据
+- **⚠️ Breaking**: `register_shared_pool` 现在只注册 PK 和 FK 列到 SharedPool（此前会注册所有非 PK-skip 列）。同名非 PK/FK 列的隐式跨表关联需通过 `ColumnAssociation` 显式声明
+- UNIQUE 列不再被 SharedPool 隐式关联或 template pool 覆盖，避免生成重复值导致 `IntegrityError`
+
+### 修复
+
+- `orchestrator.fill_table` 现在捕获 `sqlite3.IntegrityError`，避免 UNIQUE/FK 冲突导致未处理崩溃
+- `UniqueAdjuster` 使用 `params.get("max_length", max_length)` 防止 `max_length` 缺失时的 `KeyError`
+- `DataStream._attempt_node_generation` 优雅捕获生成器异常，不再向上传播
+- 回溯/无值日志级别从 `warning` 降为 `debug`，减少日志噪音
+
+## [v0.1.15]
+
+### 修复
+- CI: 移除 `ExpressionEngine.evaluate` 中不必要的 try/except，解决 SonarCloud S2737 和 CodeFlow try-except-raise 警告
+- CI: 为 `PluginMediator.apply_template_pool` 中的 `list()` 调用添加注释说明其必要性（SonarCloud S7504）
+
 ## [v0.1.14]
 
 ### 修复

{sqlseed-0.1.14 → sqlseed-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlseed
-Version: 0.1.14
+Version: 0.1.16
 Summary: Declarative SQLite test data generation toolkit
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Documentation, https://github.com/sunbos/sqlseed#readme
@@ -34,6 +34,7 @@ Requires-Dist: typing-extensions>=4.4
 Provides-Extra: all
 Requires-Dist: faker>=30.0; extra == 'all'
 Requires-Dist: mimesis>=18.0; extra == 'all'
+Requires-Dist: tqdm>=4.66; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
@@ -42,6 +43,7 @@ Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: tqdm>=4.66; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
@@ -49,6 +51,8 @@ Provides-Extra: faker
 Requires-Dist: faker>=30.0; extra == 'faker'
 Provides-Extra: mimesis
 Requires-Dist: mimesis>=18.0; extra == 'mimesis'
+Provides-Extra: notebook
+Requires-Dist: tqdm>=4.66; extra == 'notebook'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -136,7 +140,7 @@ Topological sort auto-detects table dependencies. SharedPool cross-table value s
 
 **🧮 Expression Engine & Constraint Solving**
 
-Supports derived column computation (`last_eight = card_number[-8:]`), unique constraint backtracking, and timeout protection against infinite loops.
+Supports derived column computation (`short_code = project_no[-8:]`), unique constraint backtracking, and timeout protection against infinite loops.
 
 </td>
 <td>
@@ -233,6 +237,22 @@ mypy src/sqlseed/
 
 ## 🚀 Quick Start
 
+### Try with Demo Database
+
+Want to try sqlseed right away? Build the demo database:
+
+```bash
+python examples/build_demo_db.py
+```
+
+Then explore:
+
+```bash
+sqlseed preview examples/sqlseed_demo.db --table members --count 5
+sqlseed inspect examples/sqlseed_demo.db --show-mapping
+sqlseed fill examples/sqlseed_demo.db --table members --count 100
+```
+
 ### Get Started in 30 Seconds
 
 Suppose you have a SQLite database `app.db` with a `users` table:
@@ -378,7 +398,7 @@ with sqlseed.connect("app.db", provider="mimesis", locale="en_US") as db:
     # →   orders: 50000 rows
 ```
 
-> **💡 Tip**: If two tables share a column name (e.g., `account_id`), even without a declared FK constraint, sqlseed automatically maintains cross-table consistency via the **SharedPool implicit association mechanism**.
+> **💡 Tip**: If two tables share a column name (e.g., `member_no`), even without a declared FK constraint, sqlseed automatically maintains cross-table consistency via the **SharedPool implicit association mechanism**.
 
 #### Explicit Cross-Table Associations (ColumnAssociation)
 
@@ -494,42 +514,42 @@ for r in results:
 sqlseed v2.0 introduces column dependency DAG and expression engine for computing derived columns:
 
 ```yaml
-# Bank card info table scenario
+# Project info table scenario
 tables:
-  - name: bank_cards
+  - name: projects
     count: 10000
     columns:
-      - name: card_number
+      - name: project_no
         generator: pattern
         params:
-          regex: "62[0-9]{17}"     # 19-digit UnionPay card number
+          regex: "PRJ-\\d{6}"       # Project number pattern
         constraints:
           unique: true
 
-      - name: last_eight
-        derive_from: card_number       # Depends on card_number
-        expression: "value[-8:]"   # Last 8 digits
+      - name: short_code
+        derive_from: project_no       # Depends on project_no
+        expression: "value[-6:]"   # Last 6 chars
         constraints:
           unique: true
 
-      - name: last_six
-        derive_from: card_number
-        expression: "value[-6:]"   # Last 6 digits
+      - name: region_code
+        derive_from: project_no
+        expression: "value[-4:]"   # Last 4 chars
 
-      - name: account_id
+      - name: member_no
         generator: pattern
         params:
-          regex: "U[0-9]{10}"
+          regex: "M-\\d{4}"         # Member number pattern
         constraints:
           unique: true
 ```
 
 **How it works**:
 
-1. sqlseed builds a column dependency DAG: `card_number → last_eight, last_six`
+1. sqlseed builds a column dependency DAG: `project_no → short_code, region_code`
 2. Topological sort determines generation order
-3. Generates `card_number` first, then computes `last_eight` via `value[-8:]`
-4. If `last_eight` unique constraint fails, backtracks to regenerate `card_number`
+3. Generates `project_no` first, then computes `short_code` via `value[-6:]`
+4. If `short_code` unique constraint fails, backtracks to regenerate `project_no`
 
 #### Expression Engine Functions (21 total)
 
@@ -664,10 +684,10 @@ Save a successful generation config for exact replay later:
 ```bash
 # Generate and save snapshot
 sqlseed fill app.db --table users --count 10000 --seed 42 --snapshot
-# → Snapshot saved: snapshots/2026-04-15_033000_users.yaml
+# → Snapshot saved: <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_users.yaml
 
 # Replay anytime
-sqlseed replay snapshots/2026-04-15_033000_users.yaml
+sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_users.yaml
 # → GenerationResult(table=users, count=10000, elapsed=0.52s, speed=19230 rows/s)
 ```
 
@@ -692,16 +712,16 @@ export SQLSEED_AI_API_KEY="your-api-key"
 export SQLSEED_AI_BASE_URL="https://your-llm-api-endpoint"
 
 # AI analysis and config generation
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml
+sqlseed ai-suggest app.db --table projects --output projects.yaml
 
 # AI suggestions with self-correction (3 rounds by default)
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --verify
+sqlseed ai-suggest app.db --table projects --output projects.yaml --verify
 
 # Specify model (defaults to most popular free model)
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --model nvidia/nemotron-3-super-120b-a12b:free
+sqlseed ai-suggest app.db --table projects --output projects.yaml --model nvidia/nemotron-3-super-120b-a12b:free
 
 # Skip cache
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --no-cache
+sqlseed ai-suggest app.db --table projects --output projects.yaml --no-cache
 ```
 
 **AI Workflow**:
@@ -757,7 +777,7 @@ python -m mcp_server_sqlseed
 
 This means you can tell your AI assistant:
 
-> "Analyze the structure of the `bank_cards` table in `app.db`, generate a YAML config, then fill 5000 rows."
+> "Analyze the structure of the `projects` table in `app.db`, generate a YAML config, then fill 5000 rows."
 
 The AI assistant will call `sqlseed_inspect_schema` → `sqlseed_generate_yaml` → `sqlseed_execute_fill` in sequence, without you writing any code.
 
@@ -874,7 +894,7 @@ sqlseed inspect app.db --table users --show-mapping
 sqlseed init generate.yaml --db app.db
 
 # Replay snapshot
-sqlseed replay snapshots/2026-04-15_users.yaml
+sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_users.yaml
 
 # ═══════════════════════════════════════
 # 🤖 AI Features
@@ -914,7 +934,7 @@ Level 5 │ DEFAULT check       Has default → skip / __enrich__ (when enrich=T
         ▼
 Level 6 │ Custom pattern      Regex rules registered via plugin hooks
         ▼
-Level 7 │ Built-in pattern    25 regexes: *_at→datetime, *_id→foreign_key, is_*→boolean...
+Level 7 │ Built-in pattern    26 regexes: *_at→datetime, *_id→foreign_key, is_*→boolean...
         ▼
 Level 8 │ NULLABLE fallback   Nullable → skip / __enrich__
         ▼
@@ -991,6 +1011,7 @@ src/sqlseed/
     ├── sql_safe.py          # quote_identifier — SQL injection protection
     ├── schema_helpers.py    # AUTOINCREMENT detection
     ├── metrics.py           # MetricsCollector performance metrics
+    ├── paths.py             # get_cache_dir — platform cache directory
     ├── progress.py          # Rich progress bar
     └── logger.py            # structlog logging
 

{sqlseed-0.1.14 → sqlseed-0.1.16}/README.md

@@ -83,7 +83,7 @@ Topological sort auto-detects table dependencies. SharedPool cross-table value s
 
 **🧮 Expression Engine & Constraint Solving**
 
-Supports derived column computation (`last_eight = card_number[-8:]`), unique constraint backtracking, and timeout protection against infinite loops.
+Supports derived column computation (`short_code = project_no[-8:]`), unique constraint backtracking, and timeout protection against infinite loops.
 
 </td>
 <td>
@@ -180,6 +180,22 @@ mypy src/sqlseed/
 
 ## 🚀 Quick Start
 
+### Try with Demo Database
+
+Want to try sqlseed right away? Build the demo database:
+
+```bash
+python examples/build_demo_db.py
+```
+
+Then explore:
+
+```bash
+sqlseed preview examples/sqlseed_demo.db --table members --count 5
+sqlseed inspect examples/sqlseed_demo.db --show-mapping
+sqlseed fill examples/sqlseed_demo.db --table members --count 100
+```
+
 ### Get Started in 30 Seconds
 
 Suppose you have a SQLite database `app.db` with a `users` table:
@@ -325,7 +341,7 @@ with sqlseed.connect("app.db", provider="mimesis", locale="en_US") as db:
     # →   orders: 50000 rows
 ```
 
-> **💡 Tip**: If two tables share a column name (e.g., `account_id`), even without a declared FK constraint, sqlseed automatically maintains cross-table consistency via the **SharedPool implicit association mechanism**.
+> **💡 Tip**: If two tables share a column name (e.g., `member_no`), even without a declared FK constraint, sqlseed automatically maintains cross-table consistency via the **SharedPool implicit association mechanism**.
 
 #### Explicit Cross-Table Associations (ColumnAssociation)
 
@@ -441,42 +457,42 @@ for r in results:
 sqlseed v2.0 introduces column dependency DAG and expression engine for computing derived columns:
 
 ```yaml
-# Bank card info table scenario
+# Project info table scenario
 tables:
-  - name: bank_cards
+  - name: projects
     count: 10000
     columns:
-      - name: card_number
+      - name: project_no
         generator: pattern
         params:
-          regex: "62[0-9]{17}"     # 19-digit UnionPay card number
+          regex: "PRJ-\\d{6}"       # Project number pattern
         constraints:
           unique: true
 
-      - name: last_eight
-        derive_from: card_number       # Depends on card_number
-        expression: "value[-8:]"   # Last 8 digits
+      - name: short_code
+        derive_from: project_no       # Depends on project_no
+        expression: "value[-6:]"   # Last 6 chars
         constraints:
           unique: true
 
-      - name: last_six
-        derive_from: card_number
-        expression: "value[-6:]"   # Last 6 digits
+      - name: region_code
+        derive_from: project_no
+        expression: "value[-4:]"   # Last 4 chars
 
-      - name: account_id
+      - name: member_no
         generator: pattern
         params:
-          regex: "U[0-9]{10}"
+          regex: "M-\\d{4}"         # Member number pattern
         constraints:
           unique: true
 ```
 
 **How it works**:
 
-1. sqlseed builds a column dependency DAG: `card_number → last_eight, last_six`
+1. sqlseed builds a column dependency DAG: `project_no → short_code, region_code`
 2. Topological sort determines generation order
-3. Generates `card_number` first, then computes `last_eight` via `value[-8:]`
-4. If `last_eight` unique constraint fails, backtracks to regenerate `card_number`
+3. Generates `project_no` first, then computes `short_code` via `value[-6:]`
+4. If `short_code` unique constraint fails, backtracks to regenerate `project_no`
 
 #### Expression Engine Functions (21 total)
 
@@ -611,10 +627,10 @@ Save a successful generation config for exact replay later:
 ```bash
 # Generate and save snapshot
 sqlseed fill app.db --table users --count 10000 --seed 42 --snapshot
-# → Snapshot saved: snapshots/2026-04-15_033000_users.yaml
+# → Snapshot saved: <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_users.yaml
 
 # Replay anytime
-sqlseed replay snapshots/2026-04-15_033000_users.yaml
+sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_users.yaml
 # → GenerationResult(table=users, count=10000, elapsed=0.52s, speed=19230 rows/s)
 ```
 
@@ -639,16 +655,16 @@ export SQLSEED_AI_API_KEY="your-api-key"
 export SQLSEED_AI_BASE_URL="https://your-llm-api-endpoint"
 
 # AI analysis and config generation
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml
+sqlseed ai-suggest app.db --table projects --output projects.yaml
 
 # AI suggestions with self-correction (3 rounds by default)
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --verify
+sqlseed ai-suggest app.db --table projects --output projects.yaml --verify
 
 # Specify model (defaults to most popular free model)
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --model nvidia/nemotron-3-super-120b-a12b:free
+sqlseed ai-suggest app.db --table projects --output projects.yaml --model nvidia/nemotron-3-super-120b-a12b:free
 
 # Skip cache
-sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --no-cache
+sqlseed ai-suggest app.db --table projects --output projects.yaml --no-cache
 ```
 
 **AI Workflow**:
@@ -704,7 +720,7 @@ python -m mcp_server_sqlseed
 
 This means you can tell your AI assistant:
 
-> "Analyze the structure of the `bank_cards` table in `app.db`, generate a YAML config, then fill 5000 rows."
+> "Analyze the structure of the `projects` table in `app.db`, generate a YAML config, then fill 5000 rows."
 
 The AI assistant will call `sqlseed_inspect_schema` → `sqlseed_generate_yaml` → `sqlseed_execute_fill` in sequence, without you writing any code.
 
@@ -821,7 +837,7 @@ sqlseed inspect app.db --table users --show-mapping
 sqlseed init generate.yaml --db app.db
 
 # Replay snapshot
-sqlseed replay snapshots/2026-04-15_users.yaml
+sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_users.yaml
 
 # ═══════════════════════════════════════
 # 🤖 AI Features
@@ -861,7 +877,7 @@ Level 5 │ DEFAULT check       Has default → skip / __enrich__ (when enrich=T
         ▼
 Level 6 │ Custom pattern      Regex rules registered via plugin hooks
         ▼
-Level 7 │ Built-in pattern    25 regexes: *_at→datetime, *_id→foreign_key, is_*→boolean...
+Level 7 │ Built-in pattern    26 regexes: *_at→datetime, *_id→foreign_key, is_*→boolean...
         ▼
 Level 8 │ NULLABLE fallback   Nullable → skip / __enrich__
         ▼
@@ -938,6 +954,7 @@ src/sqlseed/
     ├── sql_safe.py          # quote_identifier — SQL injection protection
     ├── schema_helpers.py    # AUTOINCREMENT detection
     ├── metrics.py           # MetricsCollector performance metrics
+    ├── paths.py             # get_cache_dir — platform cache directory
     ├── progress.py          # Rich progress bar
     └── logger.py            # structlog logging