📚 BookSearcher

BookSearcher is a Python-based CLI tool that interfaces with Prowlarr to search for books across multiple indexers. It provides a convenient way to search for both eBooks and Audiobooks, with support for caching results and managing downloads.

✨ Features

• 🔍 Powerful search across multiple indexers via Prowlarr
• 📚 Support for both eBooks and Audiobooks
• 💾 Smart caching system with size limits and auto-cleanup
• 🌐 Robust network handling with connection pooling and retries
• 🎯 Interactive and headless mode for easily using it remotely
• 🐳 Docker containerization for easy deployment
• 📡 Support for both Usenet and Torrent protocols
• 🐞 Enhanced error handling and debugging capabilities
• 📊 Detailed performance monitoring and statistics

🛠️ Requirements

Prowlarr Configuration

1. 🏃‍♂️ A running instance of Prowlarr

2. 🔑 Prowlarr API key (Settings > General)

3. 📥 Configured download client (Transmission, qBittorrent, SABnzbd, etc.)

4. 🏷️ Indexers must be tagged properly:

   • Tag audiobooks for audiobook indexers
   • Tag ebooks for ebook indexers
   • Both tags for indexers supporting both types

⚠️ Important: Tag names must be exactly audiobooks and ebooks (lowercase)

System Requirements

• 🐳 Docker
• 🔧 Docker Compose (recommended)

📦 Installation

Quick Start with Docker

Run the container with persistent cache and configuration:

docker run -d \
  --name booksearcher \
  --network host \
  -v "$(pwd)/cache:/app/cache" \
  -v "$(pwd)/config/config.yaml:/app/config/config.yaml" \
  -e PROWLARR_URL=https://prowlarr.your.domain \
  -e API_KEY='YOUR PROWLARR API KEY' \
  -e CACHE_MAX_AGE=168 \
  -e CACHE_MAX_SIZE=100 \
  -e CACHE_MAX_ENTRIES=100 \
  gaodes/booksearcher:latest

Or using Docker Compose:

services:
  booksearcher:
    image: gaodes/booksearcher:latest
    container_name: booksearcher
    network_mode: host
    volumes:
      - ./cache:/app/cache  # For persistent cache
      - ./config/config.yaml:/app/config/config.yaml  # For persistent configuration
    environment:
      - TZ=Europe/Bucharest
      # These values will be used to create the initial config.yaml if it doesn't exist
      - PROWLARR_URL=http://your-prowlarr-url:9696
      - API_KEY=your-prowlarr-api-key
      - CACHE_MAX_AGE=168  # 7 days in hours
      - CACHE_MAX_SIZE=100  # Size in MB
      - CACHE_MAX_ENTRIES=100  # Maximum number of cached searches
    restart: unless-stopped

Before starting the container, copy and customize the configuration:

# Copy the example config
cp config/config.yaml.example config/config.yaml

# Edit the configuration with your values
nano config/config.yaml

# Start the container
docker compose up -d

🚀 Usage Guide

Operation Modes

BookSearcher operates in two modes:

1. Interactive Mode (Default)

   • Full interactive interface with menus and prompts
   • Rich formatting and detailed result display
   • Step-by-step guidance through the search process
   • Continuous download prompt after results
   • Best for direct usage and exploration

2. Headless Mode (-x, --headless)

   • Minimal output suitable for scripts and automation
   • Single-line results format
   • No interactive prompts
   • Returns search ID for later use
   • Perfect for scripting and remote usage

Interactive Mode (Default)

Simply run without any flags:

docker exec -it booksearcher bs

Follow the interactive menu:

• Choose media type (Audiobooks/eBooks/Both)
• Enter your search term
• Browse through results
• Select an item to download

Headless Mode

Search for books:

# Headless search (no interactive prompts)
docker exec -it booksearcher bs --headless "book name"

When running in headless mode, the output will show a search ID and instructions. You can then grab a specific result:

# Format: bs -s <search_id> -g <result_number>
docker exec -it booksearcher bs -s 42 -g 1  # Grab first result from search #42

# Quick grab from last search
docker exec -it booksearcher bs --search-last -g 1  # Grab first result from most recent search

Managing Downloads

When you perform a search, you'll get a search ID. Use this to download items later:

# List recent searches
docker exec -it booksearcher bs --list-cache

# Download item #3 from search #42
docker exec -it booksearcher bs -s 42 -g 3

# Download from most recent search
docker exec -it booksearcher bs -sl -g 2

Additional Commands

# Enable debug output
docker exec -it booksearcher bs -d "search term"

# Clear search cache
docker exec -it booksearcher bs --clear-cache

# Show help
docker exec -it booksearcher bs --help

📝 Command Reference

Available commands and flags for bs (booksearcher):

Search Flags

Flag(s)	Description
-k, --kind {audio,book,both}	Specify media type to search for
-p, --protocol {tor,nzb}	Filter results by protocol (torrent/usenet)
-x, --headless	Run in non-interactive mode
-d, --debug	Enable debug output

Cache Management

Flag(s)	Description
-s, --search <ID>	Specify a search ID to work with
-g, --grab <number>	Download specific result number
-sl, --search-last	Use most recent search
--list-cache	Show all cached searches
--clear-cache	Delete all cached searches

💾 Cache System

• 📂 Cache location:
  • Inside container: /app/cache
  • Host machine: ./cache (when using volume mount)
• 🔧 Configurable cache settings:
  • CACHE_MAX_AGE: Maximum age of cache entries in hours (default: 168 - 7 days)
  • CACHE_MAX_SIZE: Maximum cache size in MB (default: 100)
  • CACHE_MAX_ENTRIES: Maximum number of cached searches (default: 100)
• 🧹 Intelligent cache management:
  • Size-based limits (configurable in MB)
  • Entry count limits (configurable)
  • Auto-cleanup based on access time
  • Automatic removal of oldest entries when limits are exceeded
• 📊 Comprehensive cache statistics in debug mode:
  • Current cache size and limits
  • Entry counts
  • Hit/miss ratios
  • Age information
• 💿 Persistent across container restarts when using volume mount

🔧 Advanced Features

Network Optimization

• 🔄 Automatic retry mechanism with exponential backoff
• 🌐 Connection pooling for better performance
• ⏱️ Configurable timeouts and DNS caching
• 🛡️ Proper session management and cleanup

Debug & Monitoring

• 📊 Detailed performance statistics:
  • Request counts and timing
  • Cache hit/miss ratios
  • Resource usage monitoring
  • API endpoint statistics
• 🔍 Enhanced error tracking:
  • Error categorization (Network, Cache, Search)
  • Detailed error context and stack traces
  • API response debugging
  • Request/response logging

Type Safety

• 📝 Comprehensive type hints for better code reliability
• 🏷️ TypedDict definitions for structured data
• ✅ Improved IDE support and code completion

🐛 Troubleshooting

Common issues and solutions:

1. Can't connect to Prowlarr

   • Verify PROWLARR_URL is accessible from container
   • Check API key is correct
   • Ensure Prowlarr is running

2. No results found

   • Verify indexers are properly tagged
   • Check indexer health in Prowlarr
   • Try different search terms

3. Download not starting

   • Check download client configuration in Prowlarr
   • Verify download client is running
   • Check Prowlarr logs for errors

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📞 Support

• 📝 Open an issue for bugs
• 💡 Feature requests welcome
• 🌟 Star the repo if you find it useful!

🛠️ Configuration

BookSearcher supports two ways to configure the application:

1. YAML Configuration (Recommended)

The application uses a YAML configuration file located at config/config.yaml. This file will be automatically created on first run using environment variables or default values.

Example configuration:

prowlarr:
  url: http://localhost:9696
  api_key: your-api-key
cache:
  max_age: 168  # Cache duration in hours
  max_size: 100  # Maximum cache size in MB
  max_entries: 100  # Maximum number of cached searches
search:
  default_protocol: both
  default_media_type: both

You can modify this file directly, and changes will be picked up on the next application start.

2. Environment Variables

If no config file exists, the application will use environment variables:

PROWLARR_URL=http://localhost:9696
API_KEY=your-api-key
CACHE_MAX_AGE=168  # Hours
CACHE_MAX_SIZE=100  # MB
CACHE_MAX_ENTRIES=100

These can be set in your environment or in a .env file.

Configuration Priority

1. If config/config.yaml exists, use values from there
2. If no config file exists or there's an error reading it:
   • Use environment variables if available
   • Fall back to default values for any missing settings
   • Create a new config file with these values

Default Values

If neither config file nor environment variables are present:

• PROWLARR_URL: http://localhost:9696
• API_KEY: (empty)
• CACHE_MAX_AGE: 168 hours (7 days)
• CACHE_MAX_SIZE: 100 MB
• CACHE_MAX_ENTRIES: 100
• Default protocol: both
• Default media type: both