Metadata-Version: 2.4
Name: epub-summary
Version: 0.0.10
Summary: A summary tool
Author-email: Tao Zeyu <i@taozeyu.com>
Maintainer-email: Tao Zeyu <i@taozeyu.com>
License: MIT
Project-URL: Homepage, https://github.com/oomol/epub-summary
Project-URL: Repository, https://github.com/oomol/epub-summary
Keywords: epub-summary,epub,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: aiofiles<25.0.0,>=24.1.0
Requires-Dist: jinja2<4.0.0,>=3.1.6
Requires-Dist: tiktoken<1.0.0,>=0.12.0
Requires-Dist: spacy<4.0.0,>=3.8.11
Requires-Dist: openai<3.0.0,>=2.15.0
Requires-Dist: networkx<4.0,>=3.0
Requires-Dist: json-repair<0.56.0,>=0.55.0
Requires-Dist: resource-segmentation<0.0.8,>=0.0.7
Requires-Dist: ebooklib<0.21,>=0.20
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: langdetect<2.0.0,>=1.0.9

# EPUB Summary

<div align="center">

基于 AI 的 EPUB 电子书智能压缩与摘要工具

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)

</div>

## 简介

EPUB Summary 是一个创新的电子书智能处理工具，它能够根据你的**个性化阅读意图**，自动提取和压缩 EPUB 电子书中的相关内容。与传统的文本摘要工具不同，它使用先进的知识图谱技术和多智能体系统，能够理解书籍的叙事结构，保留最重要的内容，同时大幅压缩文件体积。

### 核心特性

- **🎯 意图驱动压缩**：根据你的阅读意图定制化提取内容，而非简单的机械摘要
- **🧠 知识图谱构建**：将书籍内容解构为认知块，并构建语义连接关系
- **🔗 主题链检测**：使用拓扑指纹算法自动识别叙事主题链
- **✨ 多轮迭代优化**：通过多个 AI 审阅者迭代优化压缩结果
- **📊 精细保留控制**：四级保留度系统（逐字/详细/重点/相关）确保关键信息不丢失
- **⚡ 高性能并发**：异步处理架构，支持章节和 LLM 请求的并发处理
- **💾 智能缓存**：基于内容哈希的 LLM 响应缓存，节省 API 调用成本

## 工作原理

EPUB Summary 采用多层次的知识表示和处理流程：

```
原始 EPUB
    ↓
文本分片 (Fragments, ~800 tokens)
    ↓
认知块提取 (Chunks + 保留度标注)
    ↓
知识图谱构建 (Nodes + Edges + 工作记忆)
    ↓
主题链检测 (Snake Detection 贪心算法)
    ↓
多审阅者迭代压缩 (最多 10 轮优化)
    ↓
压缩后的 EPUB
```

### 关键技术

1. **拓扑指纹算法**：通过"墨水扩散"模型计算节点在知识图谱中的拓扑位置，用于主题相似度判断
2. **Wave Reflection 工作记忆**：基于生成衰减的算法，动态选择上下文中最相关的历史信息
3. **多智能体审阅系统**：为每条主题链创建专属的 AI 审阅者，从不同角度评估压缩质量
4. **两阶段贪心合并**：先合并单节点，再合并主题链，平衡效率与质量

## 安装

### 环境要求

- Python 3.11 或更高版本
- OpenAI API 密钥（或兼容的 API，如 DeepSeek）
- 对本仓库的读权限（私有仓库）

### 在项目中集成

在使用 epub-summary 的项目中，按以下步骤集成：

**1. 下载 wheel 文件**

```bash
# 在项目根目录
mkdir -p libs
cd libs
gh release download v0.0.1 -R oomol/epub-summary -p "*.whl"
cd ..
```

**2. 配置依赖**

在项目的 `pyproject.toml` 中添加：

```toml
[tool.poetry.dependencies]
python = "^3.11"
epub-summary = {path = "libs/epub_summary-0.0.1-py3-none-any.whl"}
```

**3. 安装依赖**

```bash
poetry install
```

**4. 提交 wheel 文件到 Git**

```bash
git add libs/epub_summary-0.0.1-py3-none-any.whl
git commit -m "Add epub-summary v0.0.1"
```

**更新版本**：

```bash
# 下载新版本
cd libs
gh release download v0.0.2 -R oomol/epub-summary -p "*.whl"
cd ..

# 更新 pyproject.toml 中的路径
# epub-summary = {path = "libs/epub_summary-0.0.2-py3-none-any.whl"}

# 重新安装
poetry install
```

> **说明**：wheel 文件作为项目源码的一部分签入 Git，所有团队成员和 CI 环境无需额外配置即可使用。

## 快速开始

### 1. 配置 LLM API

在项目根目录创建 `format.json` 配置文件：

```json
{
  "key": "your-api-key-here",
  "url": "https://api.openai.com/v1",
  "model": "gpt-4",
  "timeout": 360.0,
  "temperature": 0.8,
  "top_p": 0.6
}
```

> 提示：项目支持任何 OpenAI 兼容的 API，例如 DeepSeek、Azure OpenAI 等。

### 2. 准备 EPUB 文件

将要处理的 EPUB 文件放入 `tests/assets/` 目录（或修改 `main.py` 中的路径）。

### 3. 运行示例

```bash
python main.py
```

### 4. 自定义使用

编辑 `main.py` 或直接调用 API：

```python
import asyncio
from pathlib import Path
from epub_summary import summary

async def main():
    await summary(
        # 阅读意图：描述你想从书中提取什么内容
        intention=(
            "压缩此书，重点关注主角的成长历程和关键转折点。"
            "对于重要对话必须原文保留，背景描写可以大幅压缩。"
        ),

        # 文件路径
        input_epub_file=Path("input.epub"),
        output_epub_file=Path("output.epub"),

        # 并发控制
        llm_concurrent=12,          # LLM 并发请求数
        chapter_concurrent=6,       # 章节并发处理数

        # LLM 配置
        llm_api_key="your-api-key",
        llm_base_url="https://api.openai.com/v1",
        llm_model="gpt-4",
        llm_timeout=360.0,
        llm_temperature=0.8,
        llm_top_p=0.6,

        # 工作路径
        workspace_path=Path("workspace"),
        log_dir=Path("logs"),
        cache_dir=Path("cache"),

        # 压缩参数（可选）
        compression_ratio=0.2,      # 目标压缩比（保留 20%）
        max_iterations=10,          # 最大迭代次数
        max_clues=6,                # 最大线索（主题链）数量

        # 进度回调（可选）
        on_progress=lambda progress: print(f"处理进度: {progress * 100:.1f}%"),
    )

if __name__ == "__main__":
    asyncio.run(main())
```

## 核心参数说明

### intention（阅读意图）

这是最重要的参数，决定了压缩的方向和质量。好的意图描述应该：

- 明确说明关注什么内容
- 指定哪些内容必须保留
- 说明哪些内容可以压缩或删除

示例：
```python
# 示例 1：关注人物关系
intention = "重点保留人物之间的互动和对话，社会背景可以简化"

# 示例 2：关注特定主题
intention = "提取所有与技术实现相关的内容，理论部分可以概括"

# 示例 3：混合要求
intention = (
    "压缩此书，重点关注作者的核心观点和论证过程。"
    "对于首次提出的概念定义必须原文保留，案例可以精简。"
)
```

### 压缩参数

- `compression_ratio`：目标压缩比（0.0-1.0），默认约 0.2（保留 20%）
- `max_iterations`：最大优化迭代次数，默认 10
- `max_clues`：提取的最大主题链数量，默认 6

### 并发控制

- `llm_concurrent`：同时发起的 LLM API 请求数，建议 8-16
- `chapter_concurrent`：同时处理的章节数，建议 4-8

> 注意：过高的并发可能导致 API 限流，请根据你的 API 配额调整。

### 进度回调

- `on_progress`：可选的进度回调函数，接收一个 0.0-1.0 之间的浮点数表示当前进度
  - 可用于在 UI 中显示进度条、记录日志等
  - 传入 `None` 则禁用进度回调（默认）

示例：
```python
# 简单的进度打印
on_progress=lambda p: print(f"进度: {p*100:.1f}%")

# 更新进度条（假设使用 tqdm）
from tqdm import tqdm
pbar = tqdm(total=100)
on_progress=lambda p: pbar.update(p * 100 - pbar.n)

# 发送到 Web 界面
on_progress=lambda p: send_to_frontend({"progress": p})
```

## 目录结构

```
epub-summary/
├── epub_summary/              # 核心库
│   ├── topologization/        # 知识图谱构建
│   │   ├── topologize.py      # 主流程
│   │   ├── chunk_extraction.py # 认知块提取
│   │   ├── snake_detector.py  # 主题链检测
│   │   ├── graph.py           # 图数据结构
│   │   └── wave_reflection.py # 工作记忆算法
│   ├── editor/                # 压缩与审阅
│   │   ├── compress.py        # 压缩主流程
│   │   ├── clue.py            # 线索提取
│   │   └── markup.py          # 文本标记
│   ├── epub/                  # EPUB 读写
│   ├── data/                  # AI 提示词模板
│   ├── llm.py                 # LLM 客户端
│   ├── summation.py           # 顶层 API
│   └── text.py                # 文本工具
├── tests/                     # 测试文件
├── main.py                    # 示例脚本
├── format.json               # LLM API 配置（需手动创建）
├── workspace/                 # 运行时工作区
├── cache/                     # LLM 响应缓存
└── output/                    # 输出结果
```

## 技术架构

### 依赖库

- **LLM**：OpenAI Python SDK
- **EPUB 处理**：ebooklib
- **图算法**：NetworkX
- **异步 IO**：aiofiles, asyncio
- **文本处理**：tiktoken, spacy, resource-segmentation
- **模板引擎**：Jinja2
- **工具库**：json-repair

### 数据持久化

- **SQLite**：存储知识图谱（chunks, edges, fragments）
- **文件系统**：缓存 LLM 响应（基于 SHA-512 哈希）

### 日志系统

每次 LLM 请求都会生成独立的日志文件，包含：
- 请求的完整提示词
- 响应内容
- Token 统计
- 耗时信息

日志文件位于 `output/logs/` 目录，便于调试和分析。

## 适用场景

- **学术研究**：从长篇论文或专著中提取特定主题的论述
- **阅读辅助**：根据兴趣定制化压缩长篇小说（如只关注某个角色的故事线）
- **知识管理**：从技术书籍中提取关键知识点和代码示例
- **文献综述**：从多本书中提取相同主题的不同表述

## 开发指南

### 安装开发依赖

```bash
poetry install --with dev
```

### 代码格式化

```bash
# 使用 ruff 格式化
ruff format .

# 检查代码风格
ruff check .
```

### 类型检查

```bash
pyright
```

### 运行测试

```bash
pytest
```

### 可视化知识图谱

项目提供了基于 Cytoscape.js 的交互式可视化工具，可以在浏览器中查看和探索知识图谱：

```python
from epub_summary import generate_visualization

# 生成 HTML 可视化
generate_visualization(
    workspace_path="workspace",     # summary() 函数的 workspace_path
    output_path="visualization"     # 输出目录
)

# 可视化文件将生成在 visualization/ 目录，包含：
# - index.html: 章节列表索引页
# - chapter_*.html: 每个章节的知识图谱可视化
# 用浏览器打开 index.html 即可查看
```

可视化功能特性：

- **交互式图谱**：使用 Cytoscape.js 渲染，支持缩放、拖拽、筛选
- **节点详情**：点击节点可查看认知块的完整内容和保留度
- **边关系**：可视化节点之间的语义连接
- **按章节浏览**：每个章节生成独立的可视化页面
- **主题链高亮**：清晰展示检测到的叙事主题链

使用场景：

- 调试和分析知识图谱构建效果
- 理解主题链检测结果
- 验证压缩过程中的节点保留逻辑

## 性能优化建议

1. **调整并发数**：根据你的机器性能和 API 限额调整 `llm_concurrent` 和 `chapter_concurrent`
2. **使用缓存**：重复运行时，缓存会自动复用之前的 LLM 响应
3. **选择合适的模型**：对于简单任务，使用 `gpt-3.5-turbo` 即可；复杂任务推荐 `gpt-4` 或 DeepSeek V3
4. **分批处理**：对于超大型书籍（>500 章），建议分批处理


## 作者

Tao Zeyu - [i@taozeyu.com](mailto:i@taozeyu.com)

## 致谢

本项目的灵感来源于认知科学和知识图谱领域的研究成果，特别感谢：

- 认知块（Cognitive Chunk）理论
- 图神经网络中的拓扑指纹方法
- 多智能体系统的协同优化思想

---

如有问题或建议，欢迎提交 [Issue](https://github.com/oomol/epub-summary/issues) 或 [Pull Request](https://github.com/oomol/epub-summary/pulls)！
