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