Metadata-Version: 2.4
Name: ragjson
Version: 0.1.0
Summary: 遵循RAG-Storage-Spec的知识库构建工具
Requires-Python: >=3.12
Requires-Dist: langchain-text-splitters>=0.3
Requires-Dist: openai>=1.0
Provides-Extra: all
Requires-Dist: markitdown[all]; extra == 'all'
Requires-Dist: mineru-vl-utils; extra == 'all'
Provides-Extra: markitdown
Requires-Dist: markitdown[all]; extra == 'markitdown'
Provides-Extra: mineru
Requires-Dist: mineru-vl-utils; extra == 'mineru'
Description-Content-Type: text/markdown

# ragjson

遵循 [RAG-Storage-Spec](docs/RAG-Storage-Spec.md) 规范的基于文件系统的 RAG 知识库构建工具。

将文档解析为 Markdown、切片、生成向量嵌入，并以 `.ragjson` 格式存储到文件系统中 —— 零外部数据库依赖。

## 特性

- **零外部依赖**：仅依赖操作系统文件系统，无需向量数据库或中间件
- **文档解析**：支持 markitdown（默认）和 MinerU 两种解析引擎
- **文本切片**：支持 RecursiveCharacterTextSplitter（默认）和 MarkdownTextSplitter
- **Embedding**：兼容 OpenAI API 的向量生成
- **原子写入**：write-to-tmp + rename 保证写入安全性
- **增量更新**：基于 MD5 对比，仅处理变更文件
- **目录级并发**：不同目录可并行处理，目录内 flock 互斥

## 安装

```bash
# 全局安装为独立命令（推荐，无需 venv）
uv tool install ragjson[all]
```

或在项目虚拟环境中使用：

```bash
uv venv
source .venv/bin/activate
uv pip install ragjson[all]
```

本地开发模式（从源码安装）：

```bash
uv venv
uv pip install -e ".[all]"
source .venv/bin/activate
```

可选的 extras 组合：

| extras | 说明 |
|--------|------|
| `ragjson` | 基础安装（切片 + Embedding） |
| `ragjson[markitdown]` | 增加 markitdown 文档解析 |
| `ragjson[mineru]` | 增加 MinerU 文档解析（轻量 HTTP 客户端） |
| `ragjson[all]` | 全部依赖 |

## 配置

在用户 home 目录下创建 `~/.rag.config` 文件（JSON 格式）：

```json
{
  "embedding_model": {
    "base_url": "https://api.example.com/v1",
    "api_key": "sk-your-token",
    "model_name": "text-embedding-3-small",
    "dimension": 1536
  },
  "mineru": {
    "backend": "http-client",
    "server_url": "https://your-mineru-server:8443",
    "image_dir": "/tmp/mineru_output",
    "image_url_prefix": "https://yoursite.com"
  },
  "splitter": {
    "chunk_size": 1000,
    "chunk_overlap": 200
  }
}
```

| 配置项 | 说明 |
|--------|------|
| `embedding_model.base_url` | OpenAI 兼容 API 的地址 |
| `embedding_model.api_key` | API 密钥 |
| `embedding_model.model_name` | Embedding 模型名称 |
| `embedding_model.dimension` | 向量维度 |
| `mineru.*` | MinerU 解析服务配置（仅 `--parser mineru` 时需要） |
| `splitter.chunk_size` | 切片最大字符数 |
| `splitter.chunk_overlap` | 切片重叠字符数 |

## 使用方法

### 初始化目录

在目标目录下创建 `.rag/` 和 `.rag/tmp/` 控制目录：

```bash
rag init ./docs
```

### 查看状态

```bash
# 当前目录
rag status

# 指定目录
rag status ./docs

# 递归扫描子目录
rag status ./docs -r
```

输出说明：
- 🟢 **EMBEDDED** — 已完成嵌入且 MD5 一致，无需更新
- 🔴 **NEW / CHANGED** — 新文件或 MD5 已变更，需要更新
- 🟡 **DELETED / SLICING / EMBEDDING** — 中间状态或已标记删除

### 增量更新

仅处理 MD5 发生变化的文件，执行完整流水线：**解析 → 切片 → 嵌入 → 写入**

```bash
# 使用默认解析器 (markitdown) 和默认切片器 (recursive)
rag update ./docs

# 递归更新子目录
rag update ./docs -r

# 使用 MinerU 解析器
rag update ./docs --parser mineru

# 使用 Markdown 切片器
rag update ./docs --splitter markdown

# 指定并发数
rag update ./docs -r -j 4
```

参数说明：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-r` | 递归扫描子目录 | 否 |
| `-j N` | 并行处理的目录数 | CPU 核心数 |
| `--splitter` | 切片器类型：`recursive` / `markdown` | `recursive` |
| `--parser` | 解析器类型：`markitdown` / `mineru` | `markitdown` |

### 清理临时文件

清除崩溃后残留的 `.tmp` 文件：

```bash
rag clean ./docs
rag clean ./docs -r    # 递归清理
```

### 清除已删除记录

物理删除状态为 `DELETED` 的 `.ragjson` 文件：

```bash
rag cleanup ./docs
rag cleanup ./docs -r  # 递归清除
```

### 导出

将所有 `.ragjson` 文件打包为 tar.gz 归档：

```bash
rag export ./docs ./backup.tar.gz
```

## 目录结构

执行 `rag init` 和 `rag update` 后的目录结构示例：

```
docs/
├── .rag/                          # 控制目录
│   ├── tmp/                       # 原子写入暂存区
│   ├── readme.md.ragjson          # readme.md 的元数据
│   └── manual.pdf.ragjson         # manual.pdf 的元数据
├── readme.md                      # 源文件
└── manual.pdf                     # 源文件
```

## `.ragjson` 文件格式

```json
{
  "ragjson_version": "2.0",
  "processing": {
    "status": "EMBEDDED",
    "create_dt": "2026-07-14T10:00:00Z",
    "modify_dt": "2026-07-14T12:00:00Z"
  },
  "source": {
    "md5_hash": "d41d8cd98f00b204e9800998ecf8427e",
    "size_bytes": 2048,
    "mtime": 1710508800
  },
  "embedding": {
    "model_name": "text-embedding-3-small",
    "dimension": 1536
  },
  "slices": [
    {
      "index": 0,
      "content": "切片完整原文内容...",
      "vector_base64": "P0A/0D9A/0D9A/0D9A=="
    }
  ]
}
```

## 支持的文件类型

`.pdf` `.docx` `.doc` `.pptx` `.ppt` `.xlsx` `.xls` `.md` `.txt` `.html`

## 状态流转

```
INITIAL → SLICING → SLICED → EMBEDDING → EMBEDDED
                                         ↓
    (MD5 变更) ←────────────────── INITIAL (回退)
    
    任意状态 → DELETED → (cleanup 物理删除)
```

## 开发

```bash
# 克隆项目
git clone <repo>
cd knowledge-base-processor

# 创建虚拟环境并安装开发版本
uv venv
uv pip install -e ".[all]"
source .venv/bin/activate

# 运行 CLI
rag --help
```

## 许可证

MIT
