How book-to-skill Handles MOBI, AZW, and AZW3 File Formats

book-to-skill processes MOBI, AZW, and AZW3 files exclusively through Calibre's ebook-convert command-line tool, treating these formats as external dependencies with no pure-Python fallback.

The virgiliojr94/book-to-skill repository implements a dedicated extraction pipeline for Amazon's proprietary e-book formats. When you provide a MOBI, AZW, or AZW3 file, the system validates the presence of Calibre's conversion utility before attempting extraction, routing these formats through a specialized parser that executes shell commands and processes the resulting plain-text output.

Format Registration and Extension Mapping

In book_to_skill/config.py, the three formats are explicitly categorized as requiring external conversion tools. Lines 37-40 define the CALIBRE_EBOOK_EXTENSIONS tuple, which includes .mobi, .azw, and .azw3 alongside other Calibre-dependent formats.

This centralized registry allows the extraction logic to quickly identify which files require external binary processing rather than native Python parsing. The configuration serves as the single source of truth for determining when to invoke the Calibre-specific dependency checks.

Dependency Validation and Pre-flight Checks

Before any conversion occurs, book_to_skill/dependencies.py declares a hard requirement for the ebook-convert binary. Lines 61-68 specify this external dependency, marking it as mandatory for MOBI/AZW/AZW3 processing.

The prepare_dependencies() function in book_to_skill/utils.py performs a pre-flight validation at lines 30-34. If the file extension appears in CALIBRE_EBOOK_EXTENSIONS but the ebook-convert command is absent from the system PATH, the function raises an ExtractionError with explicit installation instructions. This early failure prevents partial processing and provides clear feedback to users about missing Calibre installations.

The Calibre Extraction Pipeline

When processing begins, the main extraction logic in book_to_skill/utils.py routes MOBI, AZW, and AZW3 files through a dedicated branch. Lines 50-58 check if the extension exists in the Calibre registry, then delegate to extract_with_ebook_convert() from book_to_skill/parsers/calibre.py.

The parser function at lines 10-24 executes the ebook-convert CLI with the source file and a temporary output path within the OUTPUT_DIR working directory. After the subprocess completes, it reads the generated plain-text file and returns the contents. If the conversion fails due to binary corruption or missing dependencies, the function propagates the error with detailed stderr output.

Once extracted, the plain-text undergoes identical sanitization, token estimation, and metadata collection as EPUB or PDF inputs, ensuring consistent downstream processing regardless of the original format.

Practical Usage Examples

You can extract Amazon format files using the command-line interface or Python API.

CLI Extraction

# Extract a MOBI file

python3 scripts/extract.py path/to/book.mobi

# Disable interactive installation prompts for CI environments

python3 scripts/extract.py path/to/book.azw3 --install-missing no

Programmatic Access

from book_to_skill import extract

# Process an AZW file

metadata = extract("path/to/book.azw")

# Access extracted text and method information

print(metadata["text"][:200])          # First 200 characters

print(metadata["extraction_method"])   # Output: "ebook-convert"

Both approaches require Calibre installed and ebook-convert available on your system PATH.

Summary

• book-to-skill treats MOBI, AZW, and AZW3 as Calibre-exclusive formats with no native Python parser.
• The CALIBRE_EBOOK_EXTENSIONS tuple in book_to_skill/config.py registers these formats for external processing.
• prepare_dependencies() validates the presence of ebook-convert before extraction, raising ExtractionError if Calibre is missing.
• The extraction pipeline routes these files through extract_with_ebook_convert() in book_to_skill/parsers/calibre.py, which shells out to the Calibre CLI.
• Converted plain-text passes through the standard sanitization and metadata collection pipeline used for other formats.

Frequently Asked Questions

Why doesn't book-to-skill use a native Python parser for MOBI files?

Amazon's MOBI, AZW, and AZW3 formats employ proprietary encoding schemes and optional DRM protection that lack robust pure-Python implementations. The project intentionally delegates to Calibre's ebook-convert tool to ensure accurate handling of complex formatting, dictionary indexes, and older MOBI variants that would require extensive reverse-engineering to parse natively.

What happens if Calibre is not installed when processing an AZW3 file?

The system raises an ExtractionError during the dependency preparation phase in book_to_skill/utils.py. This occurs before any file processing begins, providing an immediate error message directing you to install Calibre. The application will not attempt partial extraction or produce corrupted output.

Can I process DRM-protected Kindle files with book-to-skill?

No. While book-to-skill can invoke ebook-convert on AZW and AZW3 files, Calibre's conversion tool respects DRM restrictions. If the input file contains active digital rights management, ebook-convert will fail and the parser will return the conversion error. You must remove DRM through legal means before extraction will succeed.

Does the Calibre extraction path differ from EPUB processing in the final output?

No. After extract_with_ebook_convert() returns the plain-text content, the pipeline converges with EPUB and PDF processing. The extracted text undergoes identical token estimation, whitespace normalization, and metadata attachment, ensuring consistent API responses regardless of whether the source was a MOBI, EPUB, or AZW3 file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}