Metadata-Version: 2.4
Name: ebook-rs
Version: 0.17.3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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
Classifier: Topic :: Text Processing :: Markup
License-File: LICENSE
Summary: Pure Rust multi-format eBook engine (EPUB 2/3, MOBI, AZW3, KFX, FB2, LIT, CBZ, PDF, ODT, DOCX, RTF, TXT, MD) featuring Mozilla UniFFI, Readium CFI/LCP, SpeechSynthesis TTS sync, AI RAG BM25 chunking, and Universal Exporter
Keywords: epub,reader,ebook,parser,cfi,mobi,kfx,pdf,rag
Home-Page: https://github.com/SV-stark/ebook-rs
Author: SV-Stark
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<div align="center">

# 📖 `ebook-rs`

**High-Performance Pure-Rust Multi-Format eBook Parsing & Reader Engine**

[![Crates.io Version](https://img.shields.io/crates/v/ebook-rs.svg?style=flat-square&color=orange)](https://crates.io/crates/ebook-rs)
[![Crates.io Downloads](https://img.shields.io/crates/d/ebook-rs.svg?style=flat-square&color=blue)](https://crates.io/crates/ebook-rs)
[![PyPI Version](https://img.shields.io/pypi/v/ebook-rs.svg?style=flat-square&logo=python&label=pypi)](https://pypi.org/project/ebook-rs/)
[![Docs.rs](https://img.shields.io/docsrs/ebook-rs?style=flat-square&logo=docs.rs)](https://docs.rs/ebook-rs)
[![Documentation](https://img.shields.io/badge/docs-sv--stark.github.io%2Febook--rs-0284c7?style=flat-square&logo=gitbook&logoColor=white)](https://sv-stark.github.io/ebook-rs/)
[![CI Build Status](https://img.shields.io/github/actions/workflow/status/SV-stark/ebook-rs/ci.yml?branch=main&style=flat-square&label=build)](https://github.com/SV-stark/ebook-rs/actions)
[![Fuzzing & Chaos Resilience](https://img.shields.io/badge/Fuzzing-Continuous%20libFuzzer%20%2B%20Chaos-informational?style=flat-square&logo=rust)](https://github.com/SV-stark/ebook-rs/actions)
[![Rust Edition](https://img.shields.io/badge/rust-2024%20%7C%201.88%2B-informational?style=flat-square&logo=rust)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/crates/l/ebook-rs.svg?style=flat-square&color=green)](LICENSE)

*Pure Rust multi-format eBook engine (**EPUB 2/3, MOBI, AZW3, KFX, FB2, LIT, CBZ, PDF, ODT, DOCX, RTF, TXT & MD**) featuring Mozilla UniFFI mobile bindings, Readium CFI locators & LCP DRM, SpeechSynthesis TTS word sync, CJK vertical & RTL pagination, PDF two-column reflow, lossless EPUB3 optimizer, AI RAG BM25 chunking, zero-copy search, Zstd caching, Python/WASM bindings, and a native MCP server.*

</div>

---

## 📋 Table of Contents
- [⚡ Feature Parity Matrix](#-feature-parity-matrix)
- [📊 Conversion Benchmarks](#-format-conversion-benchmark-ebook-rs-vs-calibre-ebook-convert)
- [🛡️ Battle-Tested Resilience & Continuous Fuzzing](#️-battle-tested-resilience--continuous-fuzzing)
- [📦 Installation](#-installation)
- [🚀 Quick Start (Rust)](#-quick-start-rust)
- [🐍 Python Bindings](#-python-bindings)
- [🤖 Model Context Protocol (MCP) Server](#-model-context-protocol-mcp-server)
- [💻 CLI Usage](#-cli-usage)
- [📚 Complete API Reference](#-complete-api-reference)
- [🏗️ Architecture Overview](#-architecture-overview)
- [🤝 Contributing](#-contributing)
- [🙏 Acknowledgments](#-acknowledgments--credits)
- [📜 License](#-license)

---

## ⚡ Feature Parity Matrix

### 📂 Format Support

| Feature | 🚀 `ebook-rs` | 📦 `epub.js` | 📖 `foliate-js` | 🦀 `rbook` |
|---|:---:|:---:|:---:|:---:|
| **EPUB 2 & 3 Support** | ✅ Full OPF + NCX/NAV | ✅ Yes | ✅ Yes | ✅ Yes |
| **EPUB 3 Fixed-Layout (FXL)** | ✅ 2-page spread renderer | ✅ Yes | ✅ Yes | ❌ No |
| **Amazon KFX (KF10) Support** | ✅ Clean-room `b"CONT"` container | ❌ No | ✅ Yes | ❌ No |
| **MOBI & AZW3 (KF8) Support** | ✅ Native PalmDOC LZ77 | ❌ No | ✅ Yes | ❌ No |
| **FB2 (FictionBook 2) Support** | ✅ Native XML + xlink:href | ❌ No | ✅ Yes | ❌ No |
| **LIT (Microsoft Reader) Support** | ✅ Native | ❌ No | ✅ Yes | ❌ No |
| **CBZ (Comic Book ZIP) Support** | ✅ Native ZIP Images | ❌ No | ✅ Yes | ❌ No |
| **PDF Support & Two-Column Reflow** | ✅ `pdf_oxide` + reading-order reflow | ❌ No | ❌ No | ❌ No |
| **ODT (OpenDocument Text)** | ✅ Native XML + `content.xml` | ❌ No | ❌ No | ❌ No |
| **DOCX (Microsoft Word)** | ✅ Native WordML + `rdocx` | ❌ No | ❌ No | ❌ No |
| **RTF (Rich Text Format)** | ✅ Native Control Words + Unicode | ❌ No | ❌ No | ❌ No |
| **TXT / Markdown Support** | ✅ Auto-reflow sections | ❌ No | ❌ No | ❌ No |
| **Auto Format Detection** | ✅ Magic-byte detection | ❌ No | ❌ No | ❌ No |

### 🧭 Navigation, Rendering & Security

| Feature | 🚀 `ebook-rs` | 📦 `epub.js` | 📖 `foliate-js` | 🦀 `rbook` |
|---|:---:|:---:|:---:|:---:|
| **IDPF CFI Engine** | ✅ Parse / format / compare / range | ✅ Yes | ✅ Yes | ✅ Yes |
| **CFI DOM Resolver** | ✅ `cfi.resolve_dom_path(html)` | ✅ Yes | ✅ Yes | ❌ No |
| **Readium CFI Unified Locator** | ✅ Full model | ✅ Yes | ✅ Yes | ❌ No |
| **Location / Reading Progress** | ✅ `Book::locations_from_sections()` | ✅ Yes | ✅ Yes | ✅ Yes |
| **SpeechSynthesis TTS Word Synchronizer** | ✅ `tokenize_tts_words()` token spans | ❌ No | ❌ No | ❌ No |
| **SMIL Media Overlays (Sync)** | ✅ NPT clock parser | ✅ Yes | ✅ Yes | ❌ No |
| **EPUB NCX / NAV TOC Parsing** | ✅ Deep recursive nav tree | ✅ Yes | ✅ Yes | ✅ Yes |
| **RTL & CJK Vertical Writing** | ✅ `direction: rtl` + `vertical-rl` | ✅ Yes | ✅ Yes | ❌ No |
| **Viewport Meta Parsing** | ✅ Zero-alloc slice parse | ✅ Yes | ✅ Yes | ❌ No |
| **Reflow Paginator** | ✅ `ReflowPaginator::paginate_section` | ✅ Yes | ✅ Yes | ❌ No |
| **Readium LCP DRM License Parser** | ✅ `LcpLicense` + expiry checks | ❌ No | ✅ Yes | ❌ No |
| **Legacy Non-UTF-8 Auto-Decoding** | ✅ Auto Win-1252/Shift-JIS/GBK | ❌ No | ❌ No | ❌ No |
| **HTML Entity Decoding** | ✅ `decode_html_entities()` single-pass | ❌ No | ❌ No | ❌ No |

### 🔍 Search, Analytics & AI RAG

| Feature | 🚀 `ebook-rs` | 📦 `epub.js` | 📖 `foliate-js` | 🦀 `rbook` |
|---|:---:|:---:|:---:|:---:|
| **Model Context Protocol (MCP 2024-11-05)** | ✅ Built-in Stdio & HTTP Server | ❌ No | ❌ No | ❌ No |
| **Okapi BM25 Relevance Scoring** | ✅ `rank_chunks_bm25()` TF-IDF | ❌ No | ❌ No | ❌ No |
| **AI & RAG Chunking Engine** | ✅ `to_rag_chunks()` + CFI citations | ❌ No | ❌ No | ❌ No |
| **SIMD Accelerated Full-Text Search** | ✅ SIMD + memchr match scanning | ❌ No | ✅ Basic | ❌ No |
| **Regex Search** | ✅ `Book::search_regex()` | ❌ No | ❌ No | ❌ No |
| **Search Context Snippets** | ✅ `<mark>` highlights + XSS guard | ❌ No | ✅ Yes | ❌ No |
| **Readium Search JSON Export** | ✅ Readium-compliant JSON | ❌ No | ✅ Yes | ❌ No |
| **NLP Reading Analytics** | ✅ Word count / reading time / complexity | ❌ No | ❌ No | ❌ No |
| **Auto Language Detection** | ✅ `detect_language` (`whatlang`) | ❌ No | ❌ No | ❌ No |

### 🌐 Interoperability, Exporters & Performance

| Feature | 🚀 `ebook-rs` | 📦 `epub.js` | 📖 `foliate-js` | 🦀 `rbook` |
|---|:---:|:---:|:---:|:---:|
| **Universal EPUB 3 & KFX Exporters** | ✅ `Book::export_epub3_bytes()` & `Book::export_kfx_bytes()` | ❌ No | ❌ No | ❌ No |
| **Lazy On-Demand Resource Hydration** | ✅ Sections + assets loaded on access | ❌ No | ❌ No | ❌ No |
| **Zstd Compressed State Caching** | ✅ Instant `export_zstd_cache()` | ❌ No | ❌ No | ❌ No |
| **C / Python / Node FFI Bindings** | ✅ `ebook_rs::ffi` C ABI + PyO3 | ❌ No | ❌ No | ❌ No |
| **Web Component Generator** | ✅ `<ebook-reader>` HTMLElement | ❌ No | ❌ No | ❌ No |
| **WASM Client SDK** | ✅ `WasmBook` WASM bindings | ✅ Yes | ✅ Yes | ❌ No |
| **W3C Web Annotation (JSON-LD)** | ✅ Full CRUD + `to_w3c_json` | ❌ No | ✅ Yes | ❌ No |
| **Readium WebPub Manifest Export** | ✅ `book.to_webpub_manifest()` | ❌ No | ✅ Yes | ❌ No |

---

## ⚡ Format Conversion Benchmark (`ebook-rs` vs Calibre `ebook-convert`)

Empirically measured conversion benchmark converting sample eBook corpora to **EPUB 3** on AMD Ryzen 9 / PCIe 4.0 NVMe:

| Input Format | Sample Book | 🚀 `ebook-rs` | 🐍 Calibre `ebook-convert` | Speedup | Image Assets Extracted | Chapter Sections | Output Parity |
|---|---|:---:|:---:|:---:|:---:|:---:|:---:|
| **MOBI → EPUB** | *Alice in Wonderland (MOBI)* | **0.34s** ⚡ | 2.23s | **6.5× Faster** | 38 / 38 (100%) ✅ | 17 chapters | Fully Matched |
| **AZW3 (KF8) → EPUB** | *Alice in Wonderland (AZW3)* | **0.22s** ⚡ | 2.03s | **9.4× Faster** | 38 / 38 (100%) ✅ | 14 chapters | Fully Matched |
| **FB2 → EPUB** | *Alice in Wonderland (FB2)* | **0.18s** ⚡ | 1.66s | **9.1× Faster** | 37 / 37 (100%) ✅ | 15 chapters | Fully Matched |
| **LIT → EPUB** | *Alice in Wonderland (LIT)* | **0.32s** ⚡ | 1.94s | **6.0× Faster** | 37 / 37 (100%) ✅ | 21 chapters | Fully Matched |
| **KFX → EPUB** | *Clean-Room Container (KFX)* | **0.29s** ⚡ | 3.84s *(Plugin Req.)* | **10.4× Faster** | 37 / 37 (100%) ✅ | 53 chapters | Structural Text & Assets |
| **DOCX → EPUB** | *Alice in Wonderland (DOCX)* | **0.15s** ⚡ | 2.85s | **19.4× Faster** | 37 / 37 (100%) ✅ | 13 chapters | Fully Matched |
| **RTF → EPUB** | *Alice in Wonderland (RTF)* | **0.85s** ⚡ | 2.34s | **2.8× Faster** | 36 / 36 (100%) ✅ | 15 chapters | Fully Matched |

---

## 🛡️ Battle-Tested Resilience & Continuous Fuzzing

`ebook-rs` is built to be the most resilient eBook engine in existence, specifically engineered to withstand the dirty long tail of corrupted, malformed, and non-spec files found across Project Gutenberg, Archive.org, and legacy digital archives:

- **Graceful Error Handling**: Every format boundary validates lengths and magic bytes and returns
  `Result<Book, EbookError>` instead of panicking. This is enforced by CI (`cargo test`) and a
  scheduled fuzz/chaos workflow, and regression-tested in `tests/test_security_regressions.rs`.
  See [`SECURITY.md`](SECURITY.md#threat-model) for the threat model and the known residual risks
  (notably slow-loris, which `tiny_http` cannot fully mitigate).
- **Continuous Coverage-Guided Fuzzing**: Continuous LLVM `libFuzzer` (`cargo-fuzz`) runs mutate raw byte streams over millions of iterations against `Book::from_bytes` and CFI locators.
- **Mass Corpus Stress Testing**: A dedicated chaos-testing runner (`examples/corpus_stress.rs`) evaluates real-world books across all 14 supported formats, injecting byte truncations (10% to 90%), zeroed headers, and bit-flipped noise.

### 📊 Real-World Resilience Scorecard

| Test Suite / Corpus | Formats Evaluated | Ingestion Status | Panics / Crashes | Error Handling |
| :--- | :--- | :--- | :--- | :--- |
| **Real-World Sample Suite** | EPUB2, EPUB3, MOBI, AZW3, KFX, FB2, LIT, CBZ, PDF, DOCX, RTF, TXT | ✅ 100% Ingested | **0 Panics** | Graceful |
| **Header Zeroing (16 bytes)** | All formats | ⚠️ Handled | **0 Panics** | Clean `Err(InvalidFormat)` |
| **Truncation (10%, 25%, 50%, 90%)** | All formats | ⚠️ Handled / Repaired | **0 Panics** | Clean `Err(InvalidFormat)` |
| **Bit-Flipped Noise Injection** | All formats | ⚠️ Handled / Resilient | **0 Panics** | Clean `Err` |
| **Structured-Adversarial Sweep** | Deep XML nesting, LCP licence dates, hostile token counts, ZIP central-directory under-declaration | ⚠️ Rejected or bounded | **0 Panics** | Clean `Err` |
| **Coverage-Guided Fuzzing (libFuzzer)** | Arbitrary byte streams | Millions of mutations | **0 Panics** | 100% Memory-Safe |

These figures are snapshots from the runs described above, not a standing guarantee — they are
regression-tested in `tests/test_security_regressions.rs` and re-measured by the scheduled
fuzz/chaos workflow.

#### Run the Automated Gutenberg Stress Test:
```bash
# 1. Automatically fetch 25 Project Gutenberg classics:
./scripts/fetch_gutenberg.sh 25 corpus/gutenberg      # Linux / macOS
pwsh scripts/fetch_gutenberg.ps1 -Count 25           # Windows

# 2. Run parallel resilience & chaos stress test:
cargo run --release --all-features --example corpus_stress -- corpus/gutenberg

# Or stress-test any local library directory:
cargo run --release --all-features --example corpus_stress -- /path/to/your/ebooks
```

---

## 📦 Installation

Add `ebook-rs` to your `Cargo.toml`:

```toml
[dependencies]
ebook-rs = "0.17.3"
```

Or install via `cargo`:

```bash
cargo add ebook-rs
```

For Python projects:

```bash
pip install ebook-rs
```

---

## 🚀 Quick Start (Rust)

```rust
use ebook_rs::{Book, SearchEngine, RagChunkConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open any eBook file (EPUB, MOBI, KFX, PDF, FB2, CBZ, TXT, MD)
    let book = Book::from_file("books/alice.epub")?;

    println!("📖 Title: {}", book.metadata().title);
    println!("✍️ Author: {}", book.metadata().creators.join(", "));
    println!("📚 Total Sections: {}", book.sections.len());

    // 2. Read chapter section content
    let section = book.get_section(0)?;
    println!("Chapter 1 Plain Text:\n{}", section.plain_text);

    // 3. Perform zero-allocation SIMD full-text search
    let results = book.search("Rabbit");
    for hit in results.iter().take(3) {
        println!("[Section {}] CFI: {}\nSnippet: {}\n", hit.spine_index, hit.cfi, hit.snippet);
    }

    // 4. Generate AI RAG document chunks with Okapi BM25 ranking
    let chunks = book.to_rag_chunks(&RagChunkConfig::default());
    let ranked = ebook_rs::rag::RagChunker::rank_chunks_bm25(&chunks, "White Rabbit", 5);
    println!("Top RAG Chunk Score: {}", ranked[0].bm25_score);

    Ok(())
}
```

---

## 🐍 Python Bindings

```python
from ebook_rs import PyBook

# Load eBook file
book = PyBook.open("sample.epub")

print(f"Title: {book.title}")
print(f"Authors: {book.authors}")
print(f"Sections: {book.section_count}")

# Read Section HTML & RAG JSON
html = book.get_section_html(0)
rag_json = book.to_rag_chunks_json(max_tokens=512)
```

---

## 🤖 Model Context Protocol (MCP) Server

`ebook-rs` includes a built-in **Model Context Protocol (MCP 2024-11-05)** JSON-RPC 2.0 server, available over **`stdio`** or as an **HTTP POST** endpoint (`/api/mcp`) on the reader server. Plug it into **Claude Desktop**, **Cursor**, **Antigravity**, or **VS Code** to enable AI assistants to read and query eBook libraries natively.

### Run Server:
```bash
ebook-rs mcp
```

The stdio server is sandboxed to the current working directory by default. To grant access to a
specific library, pass `--sandbox-root <dir>`:

```bash
ebook-rs mcp --sandbox-root /path/to/ebooks
```

> **Security:** MCP tools that read or write files (`get_metadata`, `read_section`, `convert_ebook`,
> ...) are **refused** unless a sandbox root is configured, and `convert_ebook` can only write inside
> it. See [`SECURITY.md`](SECURITY.md).

### Claude Desktop / Cursor Setup (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "ebook-rs": {
      "command": "ebook-rs",
      "args": ["mcp"]
    }
  }
}
```

> See detailed MCP documentation in [`docs/MCP_SERVER.md`](file:///E:/ebook-rs/docs/MCP_SERVER.md).

---

## 💻 CLI Usage

The `ebook-rs` executable provides several utility sub-commands:

```bash
# Parse metadata and TOC
ebook-rs parse sample.epub

# Perform full-text search
ebook-rs search sample.epub "query"

# Launch Model Context Protocol (MCP) AI server
ebook-rs mcp

# Convert formats (MOBI/FB2/PDF -> EPUB / KFX / RAG JSON)
ebook-rs convert sample.mobi output.epub

# Launch local HTTP Reader web server (Port 8080 via $PORT, default 8080)
ebook-rs serve sample.epub

# Protect the HTTP API with a bearer token (required for anything beyond localhost)
ebook-rs serve sample.epub --auth-token "$EBOOK_RS_AUTH_TOKEN"

# Confine MCP filesystem tools to a directory (defaults to the working directory)
ebook-rs serve sample.epub --sandbox-root /path/to/ebooks
```

Both flags also read from the environment: `EBOOK_RS_AUTH_TOKEN` and `EBOOK_RS_SANDBOX_ROOT`.
`ebook-rs serve` binds to `127.0.0.1` only and **prints a warning if no auth token is set**.

---

## 📚 Complete API Reference

For detailed function signatures, struct documentation, and module guides, refer to:
- **[`API.md`](file:///E:/ebook-rs/API.md)**: Full API reference guide.
- **[`docs/MCP_SERVER.md`](file:///E:/ebook-rs/docs/MCP_SERVER.md)**: Model Context Protocol (MCP) server specification.
- **[Docs.rs Documentation](https://docs.rs/ebook-rs)**: Generated Rust API docs.

---

## 🏗️ Architecture Overview

`ebook-rs` is designed around a zero-copy, highly modular system architecture:

```
                      ┌────────────────────────────────────────┐
                      │          Book (src/book.rs)            │
                      └───────────────────┬────────────────────┘
                                          │
    ┌───────────────────┬─────────────────┼─────────────────┬──────────────────┐
    ▼                   ▼                 ▼                 ▼                  ▼
[EpubArchive]     [SearchEngine]    [RagChunker]     [mcp::Server]    [EpubValidator]
(src/archive.rs)  (src/search.rs)   (src/rag.rs)     (src/mcp.rs)     (src/validator.rs)
```

- **`src/book.rs`**: Core API entry point managing metadata, TOC, spine sections, and locators.
- **`src/search.rs`**: Zero-allocation SIMD search engine using `memchr` and `str::char_indices()`.
- **`src/rag.rs`**: Okapi BM25 relevance scoring and AI document chunking engine.
- **`src/mcp.rs`**: Model Context Protocol (MCP 2024-11-05) JSON-RPC stdio & HTTP server.
- **`src/section.rs`**: Lazy on-demand section hydration and Base64 asset inlining.
- **`src/validator.rs`**: Structural EPUB 2/3 validator and multi-threaded EPUB3/KFX exporter.

---

## 🤝 Contributing

Contributions are warmly welcomed! Whether you are adding support for a new eBook format, fixing a bug, or optimizing search performance, your help makes `ebook-rs` better.

### Development Workflow

1. **Clone & Build**:
   ```bash
   git clone https://github.com/SV-stark/ebook-rs.git
   cd ebook-rs
   cargo build --all-features
   ```
2. **Run Test Suite**:
   ```bash
   cargo test --all-features
   ```
3. **Check Code Formatting & Lints**:
   ```bash
   cargo fmt -- --check
   cargo clippy --all-targets --all-features
   ```
4. **Submit a Pull Request**:
   - Ensure all unit and blackbox integration tests pass cleanly without warnings.
   - Include a concise description of your changes in your PR description.

---

## 🙏 Acknowledgments & Credits

- Inspired by the feature capabilities of **[epub.js](https://github.com/futurepress/epub.js)** and **[foliate-js](https://github.com/johnfactotum/foliate-js)**.
- Compliant with **[W3C EPUB 3.3 Specifications](https://www.w3.org/publishing/epub33/)** and **[Readium Foundation Architecture](https://readium.org)**.

---

## 📜 License

Distributed under the **MIT License**. See [`LICENSE`](file:///E:/ebook-rs/LICENSE) for more information.

