How to Auto‑Install Missing Dependencies in book‑to‑skill

The book‑to‑skill CLI automatically detects and installs missing Python packages on demand using a centralized dependency‑management subsystem in dependencies.py.

The book‑to‑skill repository provides a built‑in mechanism to handle third‑party Python dependencies without requiring manual pip install commands. This auto‑install feature is especially useful when extracting content from PDFs, EPUBs, or other formats that rely on optional libraries. The following sections explain how this system works, how to enable it, and how to trigger it programmatically.

---

Core Dependency Detection and Installation Flow

The dependency lifecycle is orchestrated by four key functions in book_to_skill/dependencies.py:

1. run_dependency_check() (line 244) — Entry point that validates whether all required packages for the current extraction mode are available.

2. python_module_available() (line 73) — Tests if a specific Python module can be imported.

3. isolated_install_hint() (line 77) — Generates a reliable pip install command string for missing packages.

4. install_python_packages() (line 111) — Executes the actual installation via a subprocess call to python -m pip install.

When a missing dependency is detected, the CLI presents an interactive offer through offer_dependency_install() (line 147), which displays the packages to be installed and the exact command that will run.

---

Install Modes and Configuration

The behavior of the auto‑install system is governed by an install mode, normalized by normalize_install_mode() (line 130). Three modes are supported:

• auto — Silently install missing packages without prompting the user.
• prompt — Ask for confirmation before installing (default behavior).
• skip — Warn about missing dependencies but never attempt installation.

The CLI in book_to_skill/cli.py reads the install mode early in execution and passes it to prepare_dependencies() (line 194), which determines whether to invoke the installer or emit warnings.

---

Enabling Auto‑Install via CLI Flag

Pass the --install-mode flag directly to any book‑to‑skill command:

book-to-skill extract --install-mode=auto my_book.pdf

This triggers run_dependency_check() before extraction begins. Any missing packages—such as pdfminer.six for PDF parsing—are installed automatically, and the process continues without interruption.

---

Enabling Auto‑Install via Environment Variable

For persistent configuration across sessions, set the BOOK_TO_SKILL_INSTALL_MODE environment variable:

export BOOK_TO_SKILL_INSTALL_MODE=auto
book-to-skill extract my_book.pdf

The CLI reads this variable during startup and applies the same logic as the command‑line flag. If both are provided, the CLI flag takes precedence.

---

Programmatic Dependency Checks

Scripts and custom integrations can invoke the dependency system directly:

from book_to_skill.dependencies import run_dependency_check

# Returns 0 on success, non‑zero if installation failed or was rejected

exit_code = run_dependency_check()
if exit_code != 0:
    raise RuntimeError("Required dependencies could not be installed")

This pattern is useful when building wrappers or automated pipelines that need to guarantee dependency availability before calling extraction functions.

---

Key Source Files

File	Purpose	Line‑Referenced Functions
book_to_skill/dependencies.py	Core dependency detection, user prompts, and pip subprocess execution	python_module_available() (73), isolated_install_hint() (77), install_python_packages() (111), normalize_install_mode() (130), offer_dependency_install() (147), run_dependency_check() (244)
book_to_skill/cli.py	CLI argument parsing and delegation to prepare_dependencies()	prepare_dependencies() (194)
book_to_skill/config.py	Default configuration values including install mode defaults	—

---

Summary

• book_to_skill/dependencies.py centralizes all auto‑install logic, from import checks to pip execution.
• Use --install-mode=auto or BOOK_TO_SKILL_INSTALL_MODE=auto to enable fully automatic installation.
• The default prompt mode protects users from unexpected system modifications.
• Call run_dependency_check() programmatically to validate dependencies in custom scripts.

---

Frequently Asked Questions

What happens if I use skip mode and a required package is missing?

The CLI emits a warning listing the missing packages and exits with a non‑zero status code. Extraction does not proceed until the dependencies are installed manually.

Can I auto‑install dependencies for specific extraction modes only?

Currently, the install mode applies globally to all mode‑specific dependencies. When run_dependency_check() runs, it inspects the packages required for the selected extraction mode and handles them collectively.

Is the pip installation isolated from my system Python?

The install_python_packages() function runs python -m pip install in the current environment. It does not create a virtual environment automatically. For isolation, run book‑to‑skill inside a dedicated virtualenv before invoking auto‑install.

Where does book‑to‑skill store its default configuration defaults?

Default values including the fallback install mode are defined in book_to_skill/config.py. This file is imported by both the CLI and the dependency subsystem to ensure consistent behavior across the application.

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