Metadata-Version: 2.5
Name: zleap_parser
Version: 0.2.1
Summary: zleap 文档解析 SDK：多格式文件/URL 解析为 knowledge-only OCTX 归档
Author: zleap
License-Expression: MIT
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Keywords: document,knowledge,markdown,octx,parser
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: camoufox<0.6,>=0.5.4
Requires-Dist: octx>=0.1.6
Requires-Dist: openai<2,>=1.68
Requires-Dist: playwright>=1.40
Requires-Dist: pycryptodome>=3.19
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Requires-Dist: uuid6>=2025.0.1
Provides-Extra: bigdb
Requires-Dist: clickhouse-connect>=0.8; extra == 'bigdb'
Requires-Dist: psycopg2-binary>=2.9; extra == 'bigdb'
Requires-Dist: pymysql>=1.1; extra == 'bigdb'
Provides-Extra: bigdb-clickhouse
Requires-Dist: clickhouse-connect>=0.8; extra == 'bigdb-clickhouse'
Provides-Extra: bigdb-mysql
Requires-Dist: pymysql>=1.1; extra == 'bigdb-mysql'
Provides-Extra: bigdb-postgres
Requires-Dist: psycopg2-binary>=2.9; extra == 'bigdb-postgres'
Provides-Extra: db
Requires-Dist: oracledb>=2.0; extra == 'db'
Requires-Dist: psycopg2-binary>=2.9; extra == 'db'
Requires-Dist: pymssql>=2.2; extra == 'db'
Requires-Dist: pymysql>=1.1; extra == 'db'
Provides-Extra: db-all
Requires-Dist: clickhouse-connect>=0.8; extra == 'db-all'
Requires-Dist: oracledb>=2.0; extra == 'db-all'
Requires-Dist: psycopg2-binary>=2.9; extra == 'db-all'
Requires-Dist: pymssql>=2.2; extra == 'db-all'
Requires-Dist: pymysql>=1.1; extra == 'db-all'
Provides-Extra: db-mssql
Requires-Dist: pymssql>=2.2; extra == 'db-mssql'
Provides-Extra: db-mysql
Requires-Dist: pymysql>=1.1; extra == 'db-mysql'
Provides-Extra: db-oracle
Requires-Dist: oracledb>=2.0; extra == 'db-oracle'
Provides-Extra: db-postgres
Requires-Dist: psycopg2-binary>=2.9; extra == 'db-postgres'
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == 'dev'
Requires-Dist: eventlet>=0.37; extra == 'dev'
Requires-Dist: gevent>=24.11; extra == 'dev'
Requires-Dist: mypy>=2.3.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.16.2; extra == 'dev'
Requires-Dist: twine>=7.0.0; extra == 'dev'
Requires-Dist: uvloop>=0.21; (sys_platform != 'win32') and extra == 'dev'
Provides-Extra: dingtalk-oa
Requires-Dist: mcp<3,>=2; extra == 'dingtalk-oa'
Provides-Extra: dingtalk-profile
Requires-Dist: keyring>=25.0; extra == 'dingtalk-profile'
Provides-Extra: docx
Requires-Dist: docling>=2.73.1; extra == 'docx'
Requires-Dist: markitdown[docx]>=0.1.7; extra == 'docx'
Provides-Extra: email-all
Requires-Dist: google-api-python-client>=2.170; extra == 'email-all'
Requires-Dist: httpx>=0.28; extra == 'email-all'
Requires-Dist: msal>=1.31; extra == 'email-all'
Provides-Extra: email-gmail
Requires-Dist: google-api-python-client>=2.170; extra == 'email-gmail'
Provides-Extra: email-graph
Requires-Dist: httpx>=0.28; extra == 'email-graph'
Requires-Dist: msal>=1.31; extra == 'email-graph'
Provides-Extra: media
Requires-Dist: docling-slim[format-video]<3,>=2.119.0; extra == 'media'
Requires-Dist: docling[asr]<3,>=2.119.0; extra == 'media'
Requires-Dist: setuptools<81,>=80; extra == 'media'
Provides-Extra: pdf
Requires-Dist: docling>=2.73.1; extra == 'pdf'
Requires-Dist: markitdown[pdf]>=0.1.7; extra == 'pdf'
Requires-Dist: pypdfium2>=5.12.1; extra == 'pdf'
Requires-Dist: rapidocr>=3.9.2; extra == 'pdf'
Provides-Extra: ppt
Requires-Dist: docling>=2.73.1; extra == 'ppt'
Requires-Dist: markitdown[pptx]>=0.1.7; extra == 'ppt'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: xlsx
Requires-Dist: docling>=2.73.1; extra == 'xlsx'
Requires-Dist: markitdown[xlsx]<0.2,>=0.1.7; extra == 'xlsx'
Requires-Dist: matplotlib>=3.11.1; extra == 'xlsx'
Requires-Dist: openpyxl>=3.1.5; extra == 'xlsx'
Description-Content-Type: text/markdown

# zleap_parser

`zleap_parser` 是 zleap 的 Python 文档解析 SDK：把本地文件或远程 HTML
转换为 Markdown，并归档为知识型 `.octx` 文件。当前规划基线为 M2.8
（0.2.1），普通解析与连接器取数不依赖外部事项提取或向量服务。

## 文档

1. [计划总览](./plan/PLAN.md)
2. [安装与快速上手](./docs/sdk/install.md)
3. [配置手册](./docs/sdk/configuration.md)
4. [文档解析 API](./docs/sdk/parse_api.md)
5. [连接器 API](./docs/sdk/connector_api.md)
6. [钉钉连接器与 MCP 方案](./docs/sdk/dingtalk_chat_mcp_pseudocode.md)
7. [服务 API 与部署](./docs/service/)

## 安装

```bash
python -m pip install zleap_parser

# URL 采集首次使用时准备浏览器二进制
python -m camoufox fetch
```

可选能力通过 extras 安装：

```bash
python -m pip install "zleap_parser[pdf]"
python -m pip install "zleap_parser[xlsx]"
python -m pip install "zleap_parser[media]"       # 另需系统 ffmpeg
python -m pip install "zleap_parser[db-all]"
python -m pip install "zleap_parser[dingtalk-oa]" # 钉钉 OA MCP（可选）
python -m pip install "zleap_parser[dingtalk-profile]" # 钉钉加密 profile（可选）
```

SQLite、Markdown 归档和普通文本解析可直接运行。RTF/XLSX 预览需要系统
`soffice`/`libreoffice`；URL 采集需要 Camoufox 浏览器二进制。

## 最小示例

```python
import zleap_parser
from zleap_parser import CacheConfig, Parser

zleap_parser.config(cache=CacheConfig(cache_namespace="sdk-default"))
parser = Parser()

parsed = parser.parse(file="/path/to/document.pdf")
print(parsed["result"])       # 已存在的 *.octx 路径
print(parsed["usage"])        # 完整零用量账本

csv_path = parser.pack_csv_to_octx("name,age\nAlice,30\n")
print(csv_path)
```

`Parser.parse(url=...)` 与 `Parser.parse(file=...)` 必须二选一。归档产物包含
`knowledge/main.md`、metadata 和原始附件；不会生成事项、关系或向量文件。

## 连接器

```python
from zleap_parser.connector import Connector, RSSAdapter

result = Connector().fetch(
    adapter=RSSAdapter(url="https://example.com/feed.xml", limit=20)
)
print(result["results"])       # knowledge-only *.octx 路径列表
print(result["usage"])         # 普通数据源为完整零用量
```

内置数据源包括 RSS/WebSearch/DeepCrawl、企业微信/飞书/Salesmartly/钉钉
聊天与群列表、钉钉知识库/云盘/文档/OA 审批、邮件、API 请求、
GitHub/GitLab/Gitee 仓库、DB/BigDB。所有数据源统一使用 `fetch()`；
邮件额外返回邮件 OCTX 列表和 sync-cursor OCTX。

Git 仓库分析是唯一默认会调用模型的取数场景。它使用统一 `LLMConfig` 和
OpenAI-compatible 客户端，分析摘要写入 knowledge Markdown，代码文件作为
附件归档；usage 明细统一为 `kind="llm"`。

## 配置和多模态能力

文本及未来多模态请求统一使用 `LLMConfig`。`supports_multimodal=False` 为
默认值，只有显式设置为 `True` 才表示模型接受多模态消息；M2.8 不执行多模态
enrichment，不根据模型名猜测能力，也不静默降级。

`CacheConfig.cache_namespace` 默认 `"sdk-default"`，参与所有缓存 key/signature。
多租户服务必须为每个任务创建独立配置快照，例如
`tenant-<sha256(tenant_id) 前 32 位>`，不得在并发任务中修改全局配置。

## 文件格式

支持文本、源码、PDF、RTF、DOCX、PPTX、XLSX、HTML、XML、图片和音视频。
格式识别优先依据内容特征；新增格式通过 `BaseAdapter` 插件接入。

## API 变更（M2.8）

- 保留 `Parser.parse()`、`pack_to_octx()`、`pack_csv_to_octx()`、
  `pack_xlsx_to_octx()` 和 `Connector.fetch()`。
- 直接删除旧的事项提取/向量入口、旧连接器组合入口及其残留模块；
  不提供兼容别名、弃用警告或失败桩。
- 移除 embedding 配置和独立视觉模型/图片处理配置；只保留
  `LLMConfig.supports_multimodal` 能力字段。
- OCTX metadata 写入 `com.zleap.parser.archive_schema=knowledge-only/1`，
  capability 集合显式为空。

历史需求和旧版本行为请查阅 `plan/M1`、`plan/M2`、`plan/M2.5`、
`plan/M2.6`、`plan/M2.7` 及 `CHANGELOG.md`；这些记录不构成当前安装或 API 依据。
