zleap-sag 0.4.0

SAG data engine: ingest, extract, and retrieve over a lightweight event/entity graph

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。

安装与验证(开发)

make install                  # 创建 .venv + 安装开发依赖(可编辑)
make verify                   # 全量验证:lint → type → test → build
make help                     # 查看全部命令

# 解释器需 >= 3.11;如默认 python3 较旧:
make PYTHON=python3.11 verify

用法

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_ 前缀,__ 表示嵌套):

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

config = EngineConfig.from_env()          # 或 EngineConfig.from_env(env_file=".env")

统一异常捕获:

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	清理构建与缓存产物