zleap-sag 0.4.0__tar.gz

zleap_sag-0.4.0/.gitignore

@@ -0,0 +1,24 @@
+# Build
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Env
+.venv/
+venv/
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Secrets
+.env
+
+# OS
+.DS_Store

zleap_sag-0.4.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/).
+
+## [0.4.0] - 2026-07-03
+
+### Changed (BREAKING)
+- **导入命名空间迁移**:`zleap_sag` → **`zleap.sag`**(PEP 420 原生命名空间)。
+  `from zleap import sag` / `from zleap.sag import DataEngine, EngineConfig, SagError`。
+  分发名仍为 `zleap-sag`;无 `zleap_sag` 兼容 shim(干净切换)。`SAG_` 环境变量前缀不变。
+- **仓库改为 monorepo**(uv workspace):包落 `packages/sag/`,`src/zleap/sag/`;
+  为未来 `zleap-agent`/`zleap-memo` 等**独立、无耦合**的同命名空间包铺底座(各包独立版本/依赖/发布)。
+- 验证:干净 venv `from zleap import sag` 可用、`import zleap.agent` 干净失败;`make verify` 全绿;
+  MySQL+ES 集成回归通过(pgvector/PG/OceanBase 逻辑未变)。
+
+## [0.3.0] - 2026-07-02
+
+工程能力升级(对标 cognee):可适配后端骨架、DI 资源容器、Alembic 迁移、启动健康检查、
+链路灵活化。MySQL+ES 现网路径**行为零回归**,并首次经真机(MySQL+ES+LLM+Embedding)端到端验证。
+
+### Added
+- **向量库可切换(Elasticsearch / pgvector)**:`vector_provider="pgvector"` 让整套引擎跑在**单个
+  PostgreSQL**(关系 + 向量,零 ES)。`PgVectorStore` 实现 ES 客户端方法面(repositories 无改动),
+  表按文档自动建(float 列表→`vector(N)`+HNSW cosine 索引),ES filter_query→SQL WHERE,match→ILIKE。
+  **真机验证**:全 4 策略(vector/atomic/multi/multi_es)在 PostgreSQL+pgvector 单库跑通。extras:`[postgres]`。
+- **OceanBase 关系后端**(MySQL 协议兼容,`provider="oceanbase"`,复用 aiomysql 驱动/mysql 方言)。
+  **活体真机验证**:在 **OceanBase CE v4.4.2.1** 实例上,`ingest→extract→search`(全 4 策略)全链路跑通;
+  `create_all`(LONGTEXT/MEDIUMTEXT/VARBINARY 经 with_variant)+ ORM + 查询在 OB MySQL 模式均正常。
+- **关系库可切换(MySQL / PostgreSQL / SQLite)**:`RelationalConfig(provider=...)` 配置驱动、无硬编码;
+  schema 经 `with_variant` 可移植(MySQL DDL 逐字节不变,由快照守卫)+ 全局唯一索引名;`db.base` 按方言
+  建引擎(PG `server_settings` 时区 / SQLite 外键 PRAGMA)。**真机验证**:`create_all` 三方言均通过,
+  `ingest→extract→search` 在 **MySQL+ES 与 PostgreSQL+ES** 两套后端各自跑通;Alembic 基线跨方言可迁移。
+  向后兼容:`mysql=MySQLConfig(...)` 自动映射为 `relational(provider="mysql")`。extras:`[postgres]`/`[sqlite]`。
+- **后端适配器层**(`core/adapters/`):LLM/Embedding/Rerank/VectorStore/RelationalStore 接口 +
+  能力模型(`Capability`,如 BM25/`supports_lexical`)+ provider 工厂注册表(`create_*`/`register`,
+  对齐 cognee `create_*_engine`)。默认适配器包装现有 OpenAI/ES/SQLAlchemy 客户端,惰性、行为不变。
+- **DI 资源容器**(`core/resources.py`):`ResourceContainer` + `ContextVar` 单一事实来源解析
+  (默认容器=现网 MySQL+ES,无裸全局回退);`DataEngine` 构建并持有容器,暴露 `.resources`。
+- **Alembic 迁移**(`migrations/`):首条迁移=当前 schema;已验证 fresh upgrade / 升降级往返 /
+  对现网库 `stamp head` 无损纳管。`SAG_DB_URL` 覆盖连接串。
+- **启动健康检查(fail-fast)**:`DataEngine.start()` 预检关系库/向量库连通性,失败给明确错误并
+  干净回滚(不泄漏 ContextVar、不留半初始化);可 `DataEngine(cfg, health_check=False)` 关闭。
+- **`DataEngine.chunk()`**:只切不存/传字符串的纯 CPU 分块入口(无需 start、无 DB/ES/LLM)。
+- **litellm 多 provider LLM(可选,对齐 cognee)**:`LLMConfig(provider="litellm")` 切换到 litellm
+  客户端(OpenAI/Anthropic/本地等统一入口);默认仍 `openai`(零回归)。需 `pip install zleap-sag[litellm]`。
+  已真机验证:extract/search 走 litellm→302.ai 全链路通过。
+- 集成冒烟测(`tests/integration/`)+ MySQL DDL 零变更快照守卫(`tests/unit/`)。
+
+### Changed
+- `db.base.init_database()` 默认**不再删表**;drop+重建需显式 `allow_drop=True`(仅限开发)。生产用 Alembic。
+- 新增门面/适配器代码纳入严格 lint/type(`core/adapters`、`core/resources`);逐步收窄 vendored 排除范围。
+
+### Fixed
+- **ES 搜索健壮性**:查询尚未创建的索引(如稀疏数据下的 `entity_vectors`)不再抛 404 崩溃,
+  改为优雅返回空结果(`vector_search`/`search` 均修复)。
+- wheel 构建:移除与 hatchling 自动打包冲突的 `prompts/` `force-include`(路径重复)。
+- mypy:`_bootstrap` 向 `PromptManager` 传 `Path` 而非 `str`。
+
+## [Unreleased]
+
+### Added
+- src-layout 包骨架与规范 `pyproject.toml`(hatchling 后端,动态版本)。
+- 公开 API:`DataEngine`(ingest/extract/search + `init_schema` 幂等建表)、注入式 `EngineConfig`
+  (含 `from_env`,`SAG_` 前缀标准环境加载)、解耦结果模型、统一异常基类 `SagError`。
+- `py.typed`、Makefile(`make verify`)、CI、pre-commit、测试目录骨架。
+
+### Changed
+- 迁入核心 `core/db/modules/models/utils` + `prompts/`(原 `pipeline/*`,import 前缀机械改名)。
+- `DataEngine` 直接编排 load/extract/search;旧 `pipelineEngine`/`orchestrator` 已内联并删除。
+- `_bootstrap` 适配:`apply_config_to_env`(配置→环境)、`warmup_prompts`、`close_core_resources`。
+- 运行时依赖按核心实际 import 校准(补 `aiohttp`/`numpy`/`elasticsearch-dsl`/`tiktoken`,删 dead `query` extra)。
+- 质量门:vendored 核心按 `extend-exclude` 暂不纳入严格 lint/type,新增门面层严格把关。
+- 异常基类 `pipelineError` → `SagError`。
+
+### Known limitations
+- 单实例 / 进程级配置(全局连接复用);多配置隔离待依赖注入(v0.2)。
+
+### TODO
+- 真机验证(3.11 venv);集成冒烟测(`ingest→extract→search`)。
+
+## [0.1.0] - 未发布
+- 初始骨架。

zleap_sag-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zleap Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zleap_sag-0.4.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: zleap-sag
+Version: 0.4.0
+Summary: SAG data engine: ingest, extract, and retrieve over a lightweight event/entity graph
+Project-URL: Homepage, https://github.com/Zleap-AI/zleap
+Project-URL: Issues, https://github.com/Zleap-AI/zleap/issues
+Author-email: Zleap Team <contact@zleap.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: event-extraction,knowledge-graph,multi-hop,rag,retrieval
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: aiomysql>=0.2
+Requires-Dist: cryptography>=41
+Requires-Dist: elasticsearch-dsl<9,>=8
+Requires-Dist: elasticsearch<9,>=8
+Requires-Dist: json-repair>=0.58
+Requires-Dist: jsonschema>=4
+Requires-Dist: numpy>=1.26
+Requires-Dist: openai>=1.6
+Requires-Dist: pydantic-settings>=2.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: tiktoken>=0.5
+Requires-Dist: tokenizers>=0.22
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1; extra == 'dev'
+Requires-Dist: pytest-cov>=7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.17; extra == 'migrations'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# zleap-sag
+
+SAG 数据引擎:在轻量"事件/实体图"上做 **数据写入 / 抽取 / 检索 / 查询**。
+
+> 分发名 `zleap-sag`,import 名 `zleap_sag`。
+> 接入指南见 `docs/接入指南.md`。
+
+## 状态(v0.2.0)
+
+✅ **已真机验证、生产可用(MySQL + Elasticsearch)**。公开入口 `DataEngine` 编排
+load/extract/search;注入式 `config`(支持 `from_env`)、解耦 `results`、统一 `SagError`、
+幂等 `init_schema` 均就绪。`make verify` 在 3.11 全绿;`ingest→extract→search`(全 4 策略)
+已对真机 MySQL+ES+LLM+Embedding 端到端跑通(openai 与 litellm 两种 LLM provider 均验证)。
+
+工程能力(对标 cognee):后端**适配器层 + 能力模型 + provider 注册表**、**DI 资源容器**、
+**Alembic 迁移**、**启动健康检查(fail-fast)**、`chunk()` 只切不存、可选 **litellm** 多 provider。
+详见 `docs/接入指南.md`。
+
+> 后端范围(真机验证):**关系库** MySQL / PostgreSQL / SQLite / OceanBase;**向量库** Elasticsearch / pgvector。
+> 全 4 检索策略在 **MySQL+ES**、**PostgreSQL+ES**、**PostgreSQL+pgvector(单库,零 ES)**、
+> **OceanBase(CE v4.4.2.1)+ES** 四套组合均端到端跑通。见 `docs/接入指南.md`。
+
+## 安装与验证(开发)
+
+```bash
+make install                  # 创建 .venv + 安装开发依赖(可编辑)
+make verify                   # 全量验证:lint → type → test → build
+make help                     # 查看全部命令
+
+# 解释器需 >= 3.11;如默认 python3 较旧:
+make PYTHON=python3.11 verify
+```
+
+## 用法
+
+```python
+from zleap_sag import DataEngine, EngineConfig
+from zleap_sag.config import MySQLConfig, ESConfig, LLMConfig, EmbeddingConfig
+
+config = EngineConfig(
+    mysql=MySQLConfig(user="sag2", password="...", database="sag2"),
+    es=ESConfig(hosts=["http://localhost:9200"]),
+    llm=LLMConfig(api_key="...", model="qwen3.6-flash"),
+    embedding=EmbeddingConfig(model="bge-large-en-v1.5", dimensions=1024),
+)
+
+async with DataEngine(config) as engine:
+    await engine.init_schema()                          # 全新库首次建表(幂等,不删表)
+    ing = await engine.ingest("doc.md")                 # 加载单个文档
+    await engine.extract()                              # 抽取事件/实体
+    res = await engine.search("Who founded X?", strategy="multi", top_k=10)
+    print(len(res.sections))
+```
+
+也可从环境变量加载配置(`SAG_` 前缀,`__` 表示嵌套):
+
+```bash
+export SAG_MYSQL__USER=sag2 SAG_MYSQL__PASSWORD=... SAG_MYSQL__DATABASE=sag2
+export SAG_ES__HOSTS='["http://localhost:9200"]'
+export SAG_LLM__API_KEY=... SAG_LLM__MODEL=qwen3.6-flash
+export SAG_EMBEDDING__MODEL=bge-large-en-v1.5
+```
+
+```python
+config = EngineConfig.from_env()          # 或 EngineConfig.from_env(env_file=".env")
+```
+
+统一异常捕获:
+
+```python
+from zleap_sag import SagError            # 所有引擎异常的基类
+
+try:
+    res = await engine.search("...")
+except SagError as e:
+    ...
+```
+
+## ⚠️ 已知限制(v0.2)
+
+**多配置隔离(演进中)**:已引入 DI 资源容器(`ResourceContainer` + `ContextVar` 单源解析),
+但底层部分核心仍复用进程级全局连接(DB/ES)。因此**同一进程内并发多套不同配置**尚未完全隔离,
+建议一个进程一套配置;完整隔离随核心逐点切换到容器继续推进。
+
+- 关系库可切换 **MySQL / PostgreSQL / SQLite / OceanBase**;向量库可切换 **Elasticsearch / pgvector**(单库 PG 可跑完整引擎)。均已真机验证。
+- `ES` 目前取 `hosts` 列表的第一个地址。
+- `ingest` 以**文件路径**为输入(单文档);字符串/只切不存见 `DataEngine.chunk()`。
+
+## 常用命令
+
+| 命令 | 作用 |
+|------|------|
+| `make install` | 创建 `.venv` + 安装开发依赖 |
+| `make lint` | ruff 检查 + 格式校验 |
+| `make format` | ruff 自动修复 + 格式化 |
+| `make type` | mypy 类型检查 |
+| `make test` | 单元测试(跳过 integration) |
+| `make test-integration` | 集成测试(需 docker mysql/es) |
+| `make build` | 构建 sdist + wheel 并 `twine check` |
+| `make verify` | lint → type → test → build 全量验证 |
+| `make clean` | 清理构建与缓存产物 |

zleap_sag-0.4.0/README.md

@@ -0,0 +1,101 @@
+# zleap-sag
+
+SAG 数据引擎:在轻量"事件/实体图"上做 **数据写入 / 抽取 / 检索 / 查询**。
+
+> 分发名 `zleap-sag`,import 名 `zleap_sag`。
+> 接入指南见 `docs/接入指南.md`。
+
+## 状态(v0.2.0)
+
+✅ **已真机验证、生产可用(MySQL + Elasticsearch)**。公开入口 `DataEngine` 编排
+load/extract/search;注入式 `config`(支持 `from_env`)、解耦 `results`、统一 `SagError`、
+幂等 `init_schema` 均就绪。`make verify` 在 3.11 全绿;`ingest→extract→search`(全 4 策略)
+已对真机 MySQL+ES+LLM+Embedding 端到端跑通(openai 与 litellm 两种 LLM provider 均验证)。
+
+工程能力(对标 cognee):后端**适配器层 + 能力模型 + provider 注册表**、**DI 资源容器**、
+**Alembic 迁移**、**启动健康检查(fail-fast)**、`chunk()` 只切不存、可选 **litellm** 多 provider。
+详见 `docs/接入指南.md`。
+
+> 后端范围(真机验证):**关系库** MySQL / PostgreSQL / SQLite / OceanBase;**向量库** Elasticsearch / pgvector。
+> 全 4 检索策略在 **MySQL+ES**、**PostgreSQL+ES**、**PostgreSQL+pgvector(单库,零 ES)**、
+> **OceanBase(CE v4.4.2.1)+ES** 四套组合均端到端跑通。见 `docs/接入指南.md`。
+
+## 安装与验证(开发)
+
+```bash
+make install                  # 创建 .venv + 安装开发依赖(可编辑)
+make verify                   # 全量验证:lint → type → test → build
+make help                     # 查看全部命令
+
+# 解释器需 >= 3.11;如默认 python3 较旧:
+make PYTHON=python3.11 verify
+```
+
+## 用法
+
+```python
+from zleap_sag import DataEngine, EngineConfig
+from zleap_sag.config import MySQLConfig, ESConfig, LLMConfig, EmbeddingConfig
+
+config = EngineConfig(
+    mysql=MySQLConfig(user="sag2", password="...", database="sag2"),
+    es=ESConfig(hosts=["http://localhost:9200"]),
+    llm=LLMConfig(api_key="...", model="qwen3.6-flash"),
+    embedding=EmbeddingConfig(model="bge-large-en-v1.5", dimensions=1024),
+)
+
+async with DataEngine(config) as engine:
+    await engine.init_schema()                          # 全新库首次建表(幂等,不删表)
+    ing = await engine.ingest("doc.md")                 # 加载单个文档
+    await engine.extract()                              # 抽取事件/实体
+    res = await engine.search("Who founded X?", strategy="multi", top_k=10)
+    print(len(res.sections))
+```
+
+也可从环境变量加载配置(`SAG_` 前缀,`__` 表示嵌套):
+
+```bash
+export SAG_MYSQL__USER=sag2 SAG_MYSQL__PASSWORD=... SAG_MYSQL__DATABASE=sag2
+export SAG_ES__HOSTS='["http://localhost:9200"]'
+export SAG_LLM__API_KEY=... SAG_LLM__MODEL=qwen3.6-flash
+export SAG_EMBEDDING__MODEL=bge-large-en-v1.5
+```
+
+```python
+config = EngineConfig.from_env()          # 或 EngineConfig.from_env(env_file=".env")
+```
+
+统一异常捕获:
+
+```python
+from zleap_sag import SagError            # 所有引擎异常的基类
+
+try:
+    res = await engine.search("...")
+except SagError as e:
+    ...
+```
+
+## ⚠️ 已知限制(v0.2)
+
+**多配置隔离(演进中)**:已引入 DI 资源容器(`ResourceContainer` + `ContextVar` 单源解析),
+但底层部分核心仍复用进程级全局连接(DB/ES)。因此**同一进程内并发多套不同配置**尚未完全隔离,
+建议一个进程一套配置;完整隔离随核心逐点切换到容器继续推进。
+
+- 关系库可切换 **MySQL / PostgreSQL / SQLite / OceanBase**;向量库可切换 **Elasticsearch / pgvector**(单库 PG 可跑完整引擎)。均已真机验证。
+- `ES` 目前取 `hosts` 列表的第一个地址。
+- `ingest` 以**文件路径**为输入(单文档);字符串/只切不存见 `DataEngine.chunk()`。
+
+## 常用命令
+
+| 命令 | 作用 |
+|------|------|
+| `make install` | 创建 `.venv` + 安装开发依赖 |
+| `make lint` | ruff 检查 + 格式校验 |
+| `make format` | ruff 自动修复 + 格式化 |
+| `make type` | mypy 类型检查 |
+| `make test` | 单元测试(跳过 integration) |
+| `make test-integration` | 集成测试(需 docker mysql/es) |
+| `make build` | 构建 sdist + wheel 并 `twine check` |
+| `make verify` | lint → type → test → build 全量验证 |
+| `make clean` | 清理构建与缓存产物 |

zleap_sag-0.4.0/alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/migrations
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

zleap_sag-0.4.0/migrations/README

@@ -0,0 +1 @@
+Generic single-database configuration.

zleap_sag-0.4.0/migrations/env.py

@@ -0,0 +1,67 @@
+"""Alembic 迁移环境。
+
+- target_metadata = 全部 ORM 模型(zleap.sag.db.models 注册到 Base.metadata)。
+- 数据库 URL 来自环境变量 ``SAG_DB_URL``(同步驱动,如 mysql+pymysql / postgresql+psycopg / sqlite),
+  未设置则回退到 alembic.ini 的 sqlalchemy.url。
+- 迁移用同步引擎(运行期用异步;迁移一次性、用同步更简单稳妥)。
+"""
+
+from __future__ import annotations
+
+import os
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+
+# 注册全部表到 Base.metadata
+import zleap.sag.db.models  # noqa: F401
+from zleap.sag.db.base import Base
+
+config = context.config
+
+# 允许用 SAG_DB_URL 覆盖 ini 里的连接串
+_env_url = os.getenv("SAG_DB_URL")
+if _env_url:
+    config.set_main_option("sqlalchemy.url", _env_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

zleap_sag-0.4.0/migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}