ragjson 0.1.0__tar.gz

ragjson-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+data/

ragjson-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ragjson-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+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

ragjson-0.1.0/README.md

@@ -0,0 +1,243 @@
+# 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