Metadata-Version: 2.3
Name: pdf-ai-explorer
Version: 0.1.1
Summary: PDF-AI Explorer - AI-oriented PDF document reading tool
Author: nopnopnoop
Author-email: nopnopnoop <nopnopnoop@foxmail.com>
Requires-Dist: diskcache>=5.6.0
Requires-Dist: typer>=0.9.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0 ; extra == 'dev'
Requires-Python: >=3.12
Provides-Extra: dev
Description-Content-Type: text/markdown

# PDF-AI Explorer

面向 AI 的 PDF 文档阅读工具，将 PDF 视为带索引的拓扑图，帮助 AI 高效导航和理解长文档。

## 为什么需要这个工具？

当 AI 阅读长 PDF 文档（如年报、合同、技术手册）时，面临几个挑战：

- **迷失位置** - 不知道当前内容在文档中的位置
- **缺乏上下文** - 看不到相邻章节和层级关系
- **难以定位** - 无法快速跳转到相关内容
- **表格断裂** - 跨页表格被拆分，难以理解完整数据

PDF-AI Explorer 通过将 PDF 转换为**带索引的拓扑图**来解决这些问题：

```
AI: "我在看第 196 页的表格，这是什么章节？"
→ inspect_node(2000) 
→ 路径: 根 > 财务报告 > 合并报表项目注释 > 长期股权投资
   兄弟: 对子公司投资、对联营企业投资、...
   
AI: "文档里哪里提到了营业收入？"
→ search_nodes("营业收入")
→ 15 个结果，包含 ID、类型、页码、预览

AI: "这个表格跨了 3 页，怎么看完整数据？"
→ get_content(52)  # 完整合并表格
→ get_content("52:p9")  # 只看第 9 页部分
```

## 核心特性

- **拓扑感知** - 祖先路径、兄弟节点、子节点导航
- **物理感知** - 页码定位、页面层级骨架
- **语义感知** - 正则/模糊搜索、HTML 表格
- **引用感知** - `^id` 锚点标记
- **跨页表格** - 自动拆分为分页虚拟节点 (`52:p9`)

## 安装

```bash
uv sync
```

## 快速开始

### Python SDK

```python
from pdf_ai_explorer import PDFAITool, PDFReader

# 文本接口（适合 AI）
tool = PDFAITool("document.json")
print(tool.get_outline(depth=2))
print(tool.inspect_node(id=1))
print(tool.search_nodes("关键词"))
print(tool.read_page(12))
print(tool.read_page("12-15"))  # 页码范围
print(tool.get_content(id=52))
print(tool.get_content(id="52:p9"))  # 跨页表格分页

# 结构化接口（适合程序）
reader = PDFReader("document.json")
node = reader.get_node(1)
for n in reader.iter_nodes(type_filter="table"):
    print(n.id, n.page_number)
```

### CLI

```bash
uv run pdf-ai-explorer outline doc.json --depth 2
uv run pdf-ai-explorer inspect doc.json 1 --siblings 5
uv run pdf-ai-explorer search doc.json "关键词"
uv run pdf-ai-explorer read doc.json 12-15
uv run pdf-ai-explorer content doc.json 52
```

### AI Agent Skill

生成 Claude Code skill 文件，让 AI agent 快速掌握 CLI 用法：

```bash
# 输出到 stdout
uv run pdf-ai-explorer skill

# 写入 Claude Code skills 目录（自动创建 SKILL.md）
uv run pdf-ai-explorer skill --output .claude/skills/pdf-ai-explorer
```

Python API：

```python
from pdf_ai_explorer import generate_skill
content = generate_skill()  # 返回 skill markdown 文本
```

### MCP Server

```bash
# 启动 MCP Server（stdio 模式，用于 IDE 集成）
uv run pdf-ai-explorer mcp

# 或指定传输协议
uv run pdf-ai-explorer mcp --transport sse
```

工具: `get_outline`, `inspect_node`, `search_nodes`, `read_page`, `get_content`

## 接口说明

| 接口 | 功能 | 主要参数 |
|------|------|----------|
| `get_outline` | 文档大纲 | `id`, `depth` |
| `inspect_node` | 节点透视 | `id`, `sibling_count` |
| `search_nodes` | 搜索 | `query`, `mode` |
| `read_page` | 读取页面 | `page_num`, `end_page` |
| `get_content` | 节点内容 | `id` |

## 输出格式

```
段落文本 ^1234

<table id="52">
  <tr><th>项目</th><th>金额</th></tr>
  <tr><td>营业收入</td><td>20,594,892</td></tr>
</table>

[跨页表格第 9 页部分，完整表格 ID: 52，页码范围: 8-10]
```

## 项目结构

```
src/pdf_ai_explorer/
├── api.py          # PDFAITool, PDFReader
├── cli.py          # CLI 命令
├── skill.py        # Skill 生成
├── parser.py       # 文档加载
├── renderer.py     # 渲染输出
├── search.py       # 搜索逻辑
├── cache.py        # diskcache 缓存
├── config.py       # 配置管理
├── exceptions.py   # 异常类
├── models/         # 数据模型
├── templates/      # Skill 模板
└── mcp/server.py   # MCP Server
```

## 开发

```bash
make test   # 运行测试
make demo   # 运行演示
make help   # 查看帮助
```

## 配置

优先级：代码参数 > 环境变量 > 配置文件 > 默认值

### 环境变量

```bash
export MEMECT_API_URL="http://api.example.com/api"
```

### 配置文件

```toml
# ~/.config/pdf-ai-explorer/config.toml
api_url = "http://api.example.com/api"
```

### MCP 配置示例

在 IDE 的 MCP 配置中（如 `mcp.json`）：

```json
{
  "mcpServers": {
    "pdf-ai-explorer": {
      "command": "uvx",
      "args": ["--index", "http://192.168.41.95:8141/memect/dev/+simple/", "pdf-ai-explorer", "mcp"],
      "env": {
        "MEMECT_API_URL": "http://api.example.com/api"
      }
    }
  }
}
```

`uvx` 会自动从指定索引安装并运行，无需本地克隆项目。

缓存目录：`~/.cache/pdf-ai-explorer/`（基于文件 MD5）

## License

MIT
