Audiobook Recommendation Engine - User Guide

Find your next great audiobook from your personal library

Access: https://audiobook-recommender.haiven.local/

Table of Contents

  1. Getting Started
  2. Importing Your Library
  3. Browsing Your Library
  4. Getting Recommendations
  5. Discovering New Books
  6. Tips and Best Practices
  7. FAQ

Getting Started

First-Time Setup

  1. Access the application at https://audiobook-recommender.haiven.local/
  2. You'll see an empty library dashboard prompting you to import books
  3. Export your audiobook library from Libation (see below)
  4. Import the Excel file to populate your library

What You'll Need

Importing Your Library

Step 1: Export from Libation

  1. Open Libation on your computer
  2. Go to File > Export Library
  3. Choose Excel (.xlsx) format
  4. Save the file (e.g., Libation Library Export 2026-01-18.xlsx)

Step 2: Import to Recommender

  1. Click the Import button in the top navigation
  2. Select your Libation export file
  3. Click Upload and Import
  4. Wait for processing (may take 2-5 minutes for large libraries)

What Happens During Import

  1. Validation - The system checks the Excel format
  2. Transformation - Data is cleaned and normalized
  3. Embedding Generation - Each book gets a semantic vector (~50 books/second on CPU)
  4. Storage - Books are indexed in the vector database

Import Progress

A progress bar shows:
- Books parsed
- Embeddings generated
- Database insertions

Post-Import

After import completes:
- Your library statistics appear on the dashboard
- Recommendations become available
- All features are enabled

Browsing Your Library

Library View

The main Library page shows all your audiobooks in a searchable grid.

Search and Filter

Book Cards

Each book card displays:
- Cover image (from Audible)
- Title and Author
- Narrator
- Series (if part of one)
- Length in hours
- Rating (community average)
- Status badge (Finished/Unfinished)

Book Details

Click any book to see:
- Full description
- Complete metadata
- Series information with other books
- Similar book suggestions
- External discovery options

Getting Recommendations

Backlog Recommendations

The Recommendations page helps you decide what to listen to next from your unfinished books.

How It Works

The system scores each unfinished book using four factors:

Factor Weight What It Considers
Content Match 30% How well it matches your listening history and preferences
Series Priority 25% Whether you're mid-series (next book gets boosted)
Rating Score 20% Community ratings and your personal ratings
Embedding Similarity 25% Semantic similarity to books you've enjoyed

Using Recommendations

  1. Go to the Recommendations tab
  2. View the ranked list of suggestions
  3. Click any book for details
  4. Click Score Breakdown to see why it ranked where it did

Score Breakdown

Each recommendation shows:
- Overall Score (0-100)
- Content Score - Based on category matching
- Series Score - Bonus for series continuation
- Rating Score - Weighted average rating
- Similarity Score - Vector similarity to favorites

Similar Books

Find books similar to one you enjoyed:

  1. Open any book's detail page
  2. Scroll to Similar Books section
  3. These are based on semantic similarity (not just categories)

What Makes Books Similar?

The BGE embedding model considers:
- Description content and themes
- Genre and category alignment
- Author style indicators
- Narrative structure cues

Discovering New Books

External Discovery

Find books you don't own that are similar to your favorites.

How to Discover

  1. Open any book's detail page
  2. Click Discover Similar button
  3. View external recommendations

Discovery Sources

  1. Hardcover (primary) - GraphQL API with rich metadata
  2. Open Library (fallback) - Free, open-source book database

Discovery Results

Each discovered book shows:
- Title and author
- Cover image
- Description
- Series information
- Average rating
- Link to purchase/find

Filtering Discoveries

Tips and Best Practices

For Better Recommendations

  1. Rate your books - Even a few ratings improve suggestions
  2. Finish series - The system learns your series completion patterns
  3. Keep library updated - Re-import periodically for new purchases
  4. Browse categories - Explore different genres to diversify recommendations

For Efficient Browsing

  1. Use keyboard shortcuts
    - / - Focus search bar
    - Escape - Clear search/close modal
    - Arrow keys - Navigate grid

  2. Save filters - Bookmark filtered URLs for quick access

  3. Dark mode - Toggle in the header for comfortable night reading

For Discovery

  1. Start with favorites - Discover from books you loved
  2. Check series - Discover often finds related series
  3. Verify availability - Check if audiobook version exists

Library Maintenance

  1. Re-import monthly - Catch new purchases and rating updates
  2. Mark finished books - Keep status current in Libation
  3. Clean up duplicates - Remove duplicate entries in Libation before export

FAQ

How often should I re-import my library?

Re-import whenever you:
- Finish a book
- Add new books to Libation
- Update ratings or statuses

Monthly re-imports keep recommendations fresh.

Why isn't my book showing up?

Check that:
- The book is in your Libation library
- You exported after adding it
- The import completed successfully

Why are recommendations not changing?

Recommendations update when:
- You mark books as finished
- You re-import your library
- You rate books differently

Try re-importing to refresh.

How do I reset everything?

Contact the system administrator to clear the database. This will require a fresh import.

What data is sent externally?

Why does startup take so long?

The embedding model (~200MB) needs to load into memory. This takes 1-2 minutes on first start but is cached afterward.

Can I use this offline?

How are embeddings generated?

The system uses BGE-small-en-v1.5, a sentence transformer model that converts text descriptions into 384-dimensional vectors for similarity comparison.

What if Hardcover API doesn't work?

The system automatically falls back to Open Library. Discovery may have fewer results but will still function.

Support

For issues or questions:
- Check the README at /mnt/apps/docker/ai/audiobook-recommender/README.md
- View logs: docker logs audiobook-backend
- Contact system administrator

Last Updated: January 2026